Skill Visualizer

Analyzes any skill's structure and generates Mermaid diagrams, rendered into a single timestamped PDF.

When to Use

• User says "visualize X skill", "diagram X skill", "show me X skill's flow"
• User wants to understand a skill's structure visually
• User asks for structural analysis of a skill

When NOT to Use

• User only wants to read/review skill code without visualization
• User asks about skill functionality without requesting diagrams
• Target skill directory does not exist

Process

Step 0 — Verify prerequisites

Check mmdc is installed:

which mmdc || echo "NOT_INSTALLED"

If not installed, inform user:

mmdc (mermaid-cli) is required. Install with:
npm install -g @mermaid-js/mermaid-cli

Check target skill exists:

ls ~/.claude/skills/<skill-name>/SKILL.md

If not found, list available skills and ask user to confirm.

Step 1 — Read the skill

• ls the target skill directory to understand file structure
• Read SKILL.md + all scripts/configs/templates in the directory
• Note: skill directories live at ~/.claude/skills/<name>/

Step 2 — Analyze & generate Mermaid

Comprehend the skill's full logic, then decide scope:

Write .mmd files to temp dir: ~/.claude/skills/<skill-name>/tmp-diagrams/.

Mermaid guidelines

• flowchart TD for overviews and decision trees
• flowchart LR for linear phase sequences
• {{"Decision"}} diamond nodes for conditional branches
• -.-> dashed arrows for loops/backtracking
• subgraph to group related steps
• Keep node labels short (≤6 words)
• Use meaningful node IDs (e.g. parse_input not A)

Example template

flowchart TD
    start([Start]) --> check_input{{"Input valid?"}}
    check_input -->|Yes| process[Process data]
    check_input -->|No| error[Show error]
    process --> output[Generate output]
    output --> done([End])
    error -.-> start

Step 3 — Render diagrams to PDF

Render each .mmd directly to PDF:

mmdc -i X.mmd -o X.pdf -b white -t default

If mmdc fails, check error and report to user.

If multiple diagram PDFs, invoke the pdf skill to merge them into one diagrams PDF.

Step 4 — Write summary & suggestions

Write summary.md in tmp-diagrams/ — list all diagrams with brief descriptions.

Write suggestions.md in tmp-diagrams/ covering:

• Clarity: Are instructions unambiguous? Any contradictions?
• Completeness: Missing edge cases, error handling, or "when NOT to use"?
• Structure: Could sections be reordered or split for better flow?
• Actionability: Are steps concrete enough for Claude to follow without guessing?

Keep suggestions concise and actionable — bullet points, not essays.

Step 5 — Finalize & cleanup

1. Convert both .md files to PDF via the pdf skill.
2. Merge all PDFs (diagrams + summary + suggestions) into one final PDF via the pdf skill. Order: diagrams → summary → suggestions.
3. Move final PDF to skill root with timestamp: ~/.claude/skills/<skill-name>/<skill-name>-YYYYMMDD-HHMMSS.pdf
4. Optionally move summary/suggestions .md files to skill root (timestamped).
5. Clean up — delete tmp-diagrams/.

Note: Historical PDFs are preserved (timestamp naming prevents overwrite).

Output Structure

~/.claude/skills/<skill-name>/
├── SKILL.md
├── <skill-name>-YYYYMMDD-HHMMSS.pdf           # all-in-one PDF
├── <skill-name>-YYYYMMDD-HHMMSS-summary.md    # optional
└── <skill-name>-YYYYMMDD-HHMMSS-suggestions.md # optional

After Running

1. Present diagram descriptions from summary to the user
2. Share structural suggestions
3. If user wants changes, help edit the skill based on suggestions

Requirements

• mmdc (mermaid-cli): npm install -g @mermaid-js/mermaid-cli
• pdf skill for merging PDFs