Skip to content

skillDocumentation

Diagram as Code

Produces Mermaid diagrams of flows, sequences and data models read from the actual code, ready to commit next to your docs.

npx workspacetemplates add diagram-as-code --tool claude-code

Writes 1 file to .claude/skills/diagram-as-code/

.claude/skills/diagram-as-code/SKILL.md27 lines · 1.5 KBFile
---
name: diagram-as-code
description: Produces Mermaid diagrams of flows, sequences and data models read from the actual code, ready to commit next to your docs.
---

# Diagram as code

Draw what the code does. Every box must trace to a file, table or service.

## Steps

1. Clarify the question the diagram answers (how a request flows, how services talk, what states an order has, how tables relate). One question per diagram.
2. Choose the type: `sequenceDiagram` for interactions over time, `flowchart` for decisions and pipelines, `stateDiagram-v2` for lifecycles, `erDiagram` for data models, `classDiagram` only for real type hierarchies.
3. Trace the code: start at the entry point (route, handler, job, CLI) and follow calls, queries and outgoing requests. For data models read migrations or ORM models for tables, keys and relations.
4. Write the Mermaid. Use real names from the code for nodes. Keep it to roughly 12 nodes; split into two diagrams when larger. Label edges with the verb or payload.
5. Check syntax: keep labels with brackets or colons in quotes, avoid reserved word `end` as a node id, and render with `npx @mermaid-js/mermaid-cli` if available.
6. Place the diagram in a Markdown file in a `mermaid` fenced block, with two sentences of explanation above it.

## Rules

- No invented components or "future" boxes.
- Do not draw every function; show boundaries that matter.
- Note what you left out below the diagram.

## Report

File path, what question each diagram answers, and the source files you traced.

What it does

Hand-drawn architecture pictures are wrong within a month. A Mermaid block lives in Markdown, renders on GitHub, and can be fixed in a pull request. This skill has the agent trace the real code before drawing a single box.

It picks the right diagram type for the question, keeps each diagram small enough to read, and checks that every node maps to a real file, table or service.

Example

you › Diagram how an order is placed, from the API call to the email

agent › Added docs/order-flow.md with a sequence diagram of 7 participants (client, orders route, OrderService, Postgres, Stripe, queue, mailer) traced from src/orders/create.ts, plus an ER diagram of orders, line_items and payments. Left out: the admin refund path. Rendered both with mermaid-cli without errors.

Questions

Will it work outside GitHub?
Mermaid renders in GitHub, GitLab and many docs tools. If yours does not, the CLI renderer exports SVG or PNG.
Can it update a diagram I already have?
Yes. Point it at the file and it compares the diagram to the code, then edits only the parts that drifted.
  • API Documentation

    SkillDocumentation

    Free
  • Architecture Decision Records

    SkillDocumentation

    Free
  • Code Comments Docstrings

    SkillDocumentation

    Free
  • Design Doc Writing

    SkillDocumentation

    Free