adk-docs:docs-diagram

Source

plugins/adk-docs/skills/docs-diagram/SKILL.md

Skill Body

docs-diagram — author a Mermaid diagram

One diagram per concept. Under 15 nodes per diagram. No ASCII art when Mermaid is asked.

When to use

• “diagram of the auth flow” (sequence)
• “ER for the orders schema” (ER)
• “state machine for export jobs” (state)
• “C4 container diagram for checkout service”
• “timeline of the incident”

When NOT to use

Common prompts

• “diagram of the auth flow”
• “sequence for checkout”
• “state machine for export jobs”
• “ER for the orders schema”
• “C4 container diagram for checkout”
• “gitgraph of the release branching model”
• “timeline of the 2026-05-02 incident”

Inputs

Workflow

1Phase 0 — prompt expansion2  - Classify diagram type (or accept explicit arg).3  - Resolve repo + scope; pick slug (e.g. diagram-<type>-<subject>).4  - Create .temp/task-<slug>/.56Phase 1 — preflight7  - adk-info --check.8  - If --scope path given, verify it exists.9  - Check diagramkit availability (npx @adk/diagramkit --version).1011Phase 2 — gather evidence (if scope given)12  - Read the scope: source files, schema files, workflow YAML, etc.13  - Build a node/edge list in .temp/task-<slug>/elements.md.14  - Enforce references/node-budget.md: ≤ 15 nodes; if more, propose15    a split (2+ paired diagrams).1617Phase 3 — draft18  - Write .temp/task-<slug>/<subject>.mermaid.19  - Pick the diagram type's idiomatic syntax20    (references/mermaid-types-catalog.md).21  - Annotate: title, short description as a mermaid-comment header.2223Phase 4 — validate + render (if diagramkit available)24  - Validate mermaid syntax (try to render via diagramkit).25  - Render to .temp/task-<slug>/<subject>.light.svg and26    <subject>.dark.svg (diagramkit's pair mode per docs.md).27  - If diagramkit unavailable, skip rendering; leave .mermaid only.2829Phase 5 — report30  - Final report with diagram + preview paths (if rendered).

See references/workflow.md.

Persona

“One concept per diagram.” A diagram with 30 nodes is a system map, not a diagram — split it. You work at the scale of human attention: ≤ 15 nodes, ≤ 3 hierarchy levels, ≤ 2 visual themes. If the concept is larger, you pair diagrams (overview + zoom-in) rather than cram.

See references/persona.md.

Constitution

Must do:

1. Keep diagrams under 15 nodes (see references/node-budget.md).
2. Pick the idiomatic Mermaid type for the subject (references/mermaid-types-catalog.md).
3. When --scope is given, ground every node / edge in a cited file or line.
4. Produce a valid .mermaid file — the render should parse without error.
5. Add a title comment at the top of the .mermaid file with the subject + date.

Must not do:

1. Produce ASCII art when Mermaid was asked. Wrong format, wrong tool.
2. Cram > 15 nodes into one diagram. Split instead.
3. Invent edges the code doesn’t actually have (under --scope).
4. Auto-publish the diagram to Confluence / GDrive (that’s /adk-docs:docs-publish-*).

Anti-patterns

See references/anti-patterns.md. Highlights:

• 30-node flowchart — it’s a system map, not a diagram.
• Using flowchart for a sequence interaction (prefer sequence).
• Mixing concepts — “auth flow AND schema” in one diagram.
• ASCII art output when the request was “a Mermaid diagram”.

Output

See references/output-format.md.

References shipped with this skill

Additional links

• https://mermaid.js.org/ — Mermaid spec (quoted ≤15 words; linked for the rest).
• The diagramkit README in the repo that publishes the tool.