nano-step/mermaid-validator
skills/mermaid-validator/SKILL.md
Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors.
$ install --global
skillsauthnpx skillsauth add nano-step/skill-manager mermaid-validatorInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 22, 2026, 3:45 AM169.7s2 files scanned
SKILL.md
- name:
- mermaid-validator
- description:
- Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors.
- compatibility:
- OpenCode
- version:
- 2.0.0
Mermaid Validator Skill
MANDATORY WORKFLOW
Any time you write or edit a Mermaid diagram, you MUST:
- Write the diagram
- Run the validator
- Fix any errors reported
- Re-run until clean
Never mark a documentation task complete if the validator reports errors.
Validator Script Setup (Per Project)
This skill expects a zero-dependency Node.js validator script at scripts/validate-mermaid.mjs in the project root.
If the script doesn't exist yet, create it — see the reference implementation in any project that has already set this up, or ask to scaffold it.
# Validate all markdown files (default: scans .agents/ directory)
node scripts/validate-mermaid.mjs
# Validate a specific file
node scripts/validate-mermaid.mjs path/to/file.md
# Validate a whole directory
node scripts/validate-mermaid.mjs path/to/dir/
Expected clean output:
Scanned 12 file(s), 3 mermaid block(s).
✅ All diagrams passed.
Error output example:
❌ path/to/file.md
Line 47 [no-literal-newline]: Literal \n inside node/edge label — use <br/> or rewrite as plain text
> B --> C[ServiceName.method\n@Decorator]
Mermaid Syntax Rules (Mandatory Reference)
✅ Safe — No quoting needed
Letters, digits, spaces, hyphens, underscores, colons, slashes, dots, angle brackets
⚠️ Requires "double quotes" around the whole label
| Character | Wrong | Right |
|-----------|-------|-------|
| Parentheses () | A[label (detail)] | A["label (detail)"] |
| Percent % | A[100%] | A["100%"] |
| Ampersand & | A[foo & bar] | A["foo & bar"] |
| Hash # | A[#tag] | A["#tag"] |
| At-sign @ | A[@lock] | A["@lock"] |
❌ Never use inside a diagram block
| Pattern | Wrong | Fix |
|---------|-------|-----|
| Literal \n in label | A[Line1\nLine2] | A["Line1<br/>Line2"] or just A[Line1 Line2] |
| HTML entities | A[foo & bar] | A["foo & bar"] |
| HTML numeric entities | A[(parens)] | A["(parens)"] |
| Reserved word end as node ID | end[task] | End[task] |
Edge label quoting
A -- simple text --> B ✅ fine
A -- "text with (parens)" --> B ✅ quoted
A -- text with (parens) --> B ❌ breaks
Node shape reference
A[Rectangle]
A(Rounded)
A([Stadium]) ← OK to have ( inside [ here — this is shape syntax
A{Diamond}
A[(Cylinder/DB)]
A((Circle))
A>Asymmetric]
Mermaid entity codes (inside "quoted" labels only)
#40; = ( #41; = ) #35; = # #37; = %
Writing a Mermaid Diagram — Checklist
Before saving any diagram, mentally check each line:
- [ ] No
\ninside any label (bracket, brace, or paren) - [ ] No
&#NN;or&HTML entities - [ ] Any label containing
()is wrapped in"double quotes" - [ ] Node IDs are alphanumeric + underscore only (no hyphens in ID itself)
- [ ] No node ID named
end(lowercase) - [ ] Edge labels containing special chars are
"quoted" - [ ] Diagram has at least one node and one valid statement
Then run the validator. If it passes, you're done.
Common Diagram Patterns
Service method with decorator
flowchart TD
A[Controller] --> B["Service.method - @Decorator key ttl"]
Note: @ is safe after the first non-@ character. Put the whole label in quotes to be safe.
Lock/cache decision
flowchart TD
A --> B{"Redis SET NX EX - key - TTL 1800s"}
B -- Lock held --> C([Return void])
B -- Lock acquired --> D[Continue]
DB node (cylinder)
flowchart TD
A --> B[(database.table)]
Parallel execution
flowchart TD
A["Promise.all"] --> B[Task 1]
A --> C[Task 2]
Sequential batch loop
flowchart TD
A[Start loop] --> B["for i = 0 to items.length step batchSize"]
B --> C["batch = items.slice(i, i + batchSize)"]
C --> D["processBatch(batch)"]
D --> E{More batches?}
E -- Yes --> B
E -- No --> F[Return totals]
Related Skills
nano-step/iamhumans
tools
VerifiedTrustedCommunity
Humanization layer for LLM conversation — makes the model sound and respond like a real, thoughtful, embodied human rather than an assistant or chatbot. Use whenever the reply will be read by a human and warmth, presence, or texture matter more than machine-readability. Triggers on any of: "human", "humans", "humanize", "humanization", "be human", "more human", "feel human", "people", "person", "real person", "real human", "friend", "friendly", "like a friend", "respond like a friend", "buddy", "talk", "talking", "talk to me", "talk like a person", "chat", "chatting", "conversation", "converse", "discuss", "discussion", "communication", "communicate", "listen", "just listen", "sit with me", "vent", "venting", "I just want to vent", "company", "presence", "stop being an AI", "stop sounding like a bot", "less corporate", "less robotic", "less formal", "warmer", "warm tone", "empathy", "empathetic", "comfort", "support me", "emotional support", "be honest with me", "be real with me", "real talk", "heart-to-heart", "deep conversation", "casual", "casual chat", "small talk", "chitchat", "say something", "tell me something", and on any emotional / relational / personal-decision / interpersonal context — grief, joy, anger, fear, shame, doubt, loneliness, dating, breakup, conflict, family, parents, sibling, friendship, marriage, divorce, in-laws, kids, parenting, work stress, burnout, career decision, quitting, firing, layoff, anxiety, depression, panic, sleep, dreams, identity, faith, doubt, meaning, mortality, celebration, milestone, achievement, gratitude, apology, forgiveness. Also loads when the user writes in non-English (any language) with emotional weight, when the user's message is shorter than 8 words and affect-laden, when the user types in lowercase fragments, when the user types in ALL CAPS with excitement, or when the user explicitly asks for a friend / mentor / older-sibling / wise-listener voice. Do NOT use for code generation, tool calls, structured data output, SQL, API contracts, or any task where machine-readability matters more than human warmth.
3SKILL.mdUpdated Jun 1, 2026
nano-step/open-design-mcp
tools
VerifiedTrustedCommunity
Use this skill whenever the user mentions open-design, od_generate_design, OD daemon, BYOK design generation, generating HTML mockups from a PRD, creating or managing Open Design projects, saving design artifacts, linting generated HTML, or any of the 10 `od_*` MCP tools (od_list_projects, od_get_project, od_create_project, od_update_project, od_delete_project, od_save_artifact, od_save_project_file, od_lint_artifact, od_compose_brief, od_generate_design). Also trigger on phrases like "generate a design", "create a mockup", "make a landing page", "list my OD projects", "the design daemon", "the streaming design tool", and on any 401/404/422 error coming from an `od_*` tool call. Covers env-var setup (`OD_DAEMON_URL`, auth modes, BYOK), the full PRD → generate → save → lint workflow, error diagnosis, and the safety rails (lint before save, never commit BYOK keys). Triggers even if the user doesn't explicitly say "open-design-mcp" — keyword matches on `od_*` tool names or "design generation" workflows are enough.
3SKILL.mdUpdated May 19, 2026
nano-step/od-workflow
tools
VerifiedTrustedCommunity
Use this skill whenever a user wants the **full Open Design experience** — discovery questions asked first, brand-spec extraction from URLs/files, TodoWrite planning with live updates, 5-dimensional self-critique, polished artifact at the end. Trigger phrases include "design with questions first", "OD-style workflow", "full interactive design brief", "make me a complete landing page" (when the user wants quality over speed), "design my pitch deck", "brand-aware multi-page site", "follow the Open Design playbook", or any request where the user is starting a new design project rather than tweaking an existing artifact. Also trigger on any request that mentions wanting brand consistency across multiple pages or that provides a brand URL/spec. Pair with the `open-design-mcp` tool-reference skill — both loaded together give an LLM the full picture (this skill = workflow choreography; that skill = tool catalog + errors). This skill explicitly does NOT trigger for one-off tweaks ("make the nav stickier", "swap slide 3 image") — use od_generate_design directly for those.
3SKILL.mdUpdated May 19, 2026
nano-step/sync-skill-to-manager
development
VerifiedTrustedCommunity
Sync a locally-developed OpenCode skill to the skill-manager npm package and (if private) the private-skills GitHub repo. Handles per-skill version bumps, public/private classification, build verification, and conventional-commit-style git push. Auto-publish to npm is handled downstream by nano-step/shared-workflows@v1 when the push to master lands. Use this skill whenever the user says 'sync skill', 'publish skill', 'push skill to manager', '/sync-skill-to-manager <name>', or asks to release/distribute a skill they just edited.
3SKILL.mdUpdated May 7, 2026