Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are written in English. When generating user-facing output, detect the project's primary language (from README, comments, docs, commit messages) and produce labels, titles, and annotations in that language. If the project is bilingual, ask the user which language to use before proceeding.

Schema Forge — Clear Diagrams, Zero Syntax Errors

Generate professional, GitHub-compatible Mermaid diagrams that are readable first, pretty second.

Core Philosophy

1. Clarity over completeness — a diagram that shows too much shows nothing. If it's complex, split it
2. Right tool for the job — pick the diagram type that makes the data obvious, not the one that looks fancy
3. GitHub-first — every diagram must render on GitHub without errors. No FontAwesome, no click events, no exotic features
4. UX ergonomics — treat diagrams like UI: if a user needs more than 5 seconds to understand the flow, redesign it
5. Truth over aspiration — a diagram must reflect what EXISTS in the code, not what someone hopes to build. Stale diagrams are worse than no diagrams
6. Gotchas — read ../gotchas.md before producing output to avoid known mistakes

Operating Modes

This skill operates in three modes, detected from the user's input:

Mode A — Single Diagram

The user describes something specific to visualize. Generate one diagram.

Trigger: text description, broken Mermaid, table to convert, specific request.

Mode B — Doc Scan & Convert

The user points at a directory or says "scan", "audit docs", "make visual". The skill crawls documentation files and converts everything that would be genuinely more readable as Mermaid.

Trigger: path to a directory, "scan docs", "convert everything", "make docs visual".

Mode C — Project Schema

The user wants a diagram of the current project (architecture, module structure, data flow). The skill reads the actual codebase to generate accurate diagrams.

Trigger: "project schema", "architecture of this project", "visualize this codebase", "show me the structure".

Mode B — Doc Scan & Convert

Read references/modes.md for the full workflow: candidate detection table, conversion rules, and output format.

Key rule: Only convert if the diagram is genuinely more readable than the original.

Mode C — Project Schema

Read references/modes.md for the full workflow: codebase analysis, diagram generation table, IMPLEMENTED vs PLANNED distinction, and accuracy checklist.

Mode A — Single Diagram

Step 1 — Understand the intent

What does the user want to visualize?

Step 2 — Choose the right diagram type

Think like a UX designer. Match the data shape to the diagram type:

Decision heuristic: If you hesitate between two types, pick the one with fewer visual elements for the same information.

Step 3 — Complexity check (the 5-second rule)

Before writing, estimate complexity:

nodes + edges = complexity score

Splitting strategy:

1. Create a Level 0 overview (max 7 boxes, one per sub-diagram)
2. Each sub-diagram is self-contained with clear entry/exit points
3. Name sub-diagrams consistently: "Detail: [Topic]"
4. Reference between diagrams using consistent node names

Step 4 — Write the diagram

Follow these rules strictly:

GitHub Compatibility (non-negotiable)

• Use ```mermaid fenced code blocks
• NO FontAwesome icons (fa:fa-*) — use emoji or text instead
• NO click events or callbacks
• NO tooltips or interactive features
• NO %%{init: {"theme": "..."}}%% with custom fonts (GitHub ignores them)
• Node IDs: start with a letter, use camelCase or snake_case
• Keep under 50 nodes and 100 edges per diagram (GitHub hard limits: 280 edges)
• Keep total Mermaid block under 2000 characters for reliable rendering
• Test-worthy: the diagram must parse without errors

Readability Rules

1. Direction matters:
   • TB (top-bottom) for hierarchies and flows
   • LR (left-right) for timelines and sequences
   • RL for right-to-left language projects
2. Labels are mandatory — no unlabeled arrows. Every edge tells a story
3. Node shapes convey meaning:
   • [text] rectangle = process/action
   • (text) rounded = start/end
   • {text} diamond = decision
   • [(text)] cylinder = database/storage
   • [[text]] subroutine = external system
   • >text] flag = event/signal
4. Subgraphs for grouping — use them to reduce visual noise, not add it
5. Max 3 levels of nesting in subgraphs

Color & Styling (functional, not decorative)

Use classDef for semantic coloring. Never more than 5 classes per diagram.

classDef primary fill:#4A90D9,stroke:#2C6CB0,color:#fff
classDef success fill:#27AE60,stroke:#1E8449,color:#fff
classDef warning fill:#F39C12,stroke:#D68910,color:#fff
classDef danger fill:#E74C3C,stroke:#C0392B,color:#fff
classDef neutral fill:#ECF0F1,stroke:#BDC3C7,color:#2C3E50

When to use color:

• Highlight the happy path (green) vs error path (red)
• Distinguish system boundaries (colored subgraphs)
• Mark status: done/active/pending
• Never use color as the only differentiator — labels must stand alone

Step 5 — Convert existing content

Read references/conversions.md for 15+ conversion patterns: table→diagram, kanban→flowchart, PERT→flowchart (DAG with durations), roadmap→gantt, SQL→ER, JSON→class, API→sequence, RACI→flowchart, and more.

Step 6 — Review checklist

Before delivering, verify:

• Renders on GitHub (no syntax errors)
• Passes the 5-second rule (intent is immediately clear)
• All edges are labeled (except trivial parent-child)
• Node count under 50 per diagram
• Colors are functional, not decorative (max 5 classDef)
• No GitHub-incompatible features (FA icons, click events, tooltips)
• Direction matches the data flow (TB for hierarchy, LR for timeline)
• Complex diagrams are split with an overview
• Labels match the project's language

Diagram Type Quick Reference

Read references/diagram-types.md for detailed syntax and GitHub-tested examples of each diagram type.

Anti-patterns

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

Integration with other cli-* skills