create-mermaid-diagrams

name	create-mermaid-diagrams
description	Create, validate, and repair Mermaid diagrams for technical documentation with a deterministic CLI feedback loop. Use when an AI needs to create Mermaid diagrams, improve Mermaid diagram quality, validate Mermaid fences in markdown, diagnose Mermaid rendering failures, or fix Mermaid syntax and formatting issues.

Create Mermaid Diagrams

Overview

Create clear Mermaid diagrams and always validate output through a repeatable loop that catches syntax and rendering errors before final delivery.

Context Marker

Always begin your response with all active emoji markers, in the order they were introduced.

Format: "<marker1><marker2><marker3>\n<response>"

The marker for this skill is: 🎨

Manual Triggering

When manual invocation is needed, trigger this skill using whatever mechanism your assistant/tool provides for manual skill selection or activation.

Workflow

1. Define communication intent and choose the smallest diagram type that fits:

   • flowchart for process and architecture flow.
   • sequenceDiagram for interaction timelines.
   • stateDiagram-v2 for state transitions.

2. Generate markdown with exactly one Mermaid fence per requested diagram:

   • Opening fence must be exactly ```mermaid (no leading space; any spaced example is only Markdown escaping).
   • Closing fence must be exactly ``` (no leading space; any spaced example is only Markdown escaping).
   • Keep fence markers at column 0.

3. Validate the full markdown file with mmdc:

   mmdc -i <input.md> -o /tmp/<name>-rendered.md -a /tmp/<name>-mermaid-artifacts
   

4. If validation fails:

   • Read raw Mermaid CLI output from mmdc.
   • Apply the minimal targeted fix in the failing Mermaid fence.
   • Re-run the same full-file validation command.

5. Repeat failure analysis and correction up to 3 attempts.

6. If still failing after 3 attempts, return:

   • Best-effort corrected diagram.
   • Validation summary with likely root cause.
   • Raw error excerpt from Mermaid CLI output.
   • Next manual fix suggestion.

Feedback Loop Rules

• Do not change diagram type unless the error indicates the type keyword is invalid.
• Prefer minimal edits per retry to avoid introducing new syntax errors.
• Preserve user intent and semantic meaning while repairing syntax.
• Stop retrying early when validation succeeds.

Runtime Requirements

• mmdc must be available in PATH.
• If running in a sandboxed AI tool, allow execution of mmdc explicitly.
• Treat mmdc stdout/stderr as the source of truth for pass/fail and diagnosis.

Existing Documentation with Multiple Mermaid Diagrams

When validating an existing markdown file that includes multiple Mermaid blocks:

1. Run one full-file validation command with mmdc.
2. Parse CLI output to identify discovered block count and rendered artifacts.
3. For failures, use parse error snippet and caret location to identify the failing fence.
4. Patch only failing blocks, then re-run full-file validation.
5. Provide a final rollup: total blocks, passed, failed, fixed, unresolved.

Error Handling

Treat any non-zero mmdc exit as a failure and use Mermaid CLI output as the source of truth for diagnosis and repair. For dependency, access, or input failures (for example mmdc not executable in sandbox), stop immediately and do not continue retries. When validation cannot run, the response must clearly state that validation did not occur and include:

• the exact mmdc command that failed
• exit code (if available)
• a raw stderr excerpt
• explicit next steps to grant mmdc execution access or fix file/path permissions

Output Requirements

• Always include the final Mermaid markdown block.
• Include a short validation result summary.
• On failure, include the actionable error context and exact next steps.

References

• Mermaid best practices and templates: references/mermaid-best-practices.md
• Advanced diagram patterns and constructs: references/advanced-patterns.md
• Error classes and repair strategies: references/error-patterns.md
• Multi-diagram markdown validation workflow: references/multi-diagram-validation.md