diagrams
diagrams, the rules for every Mermaid diagram. Use whenever you explain in chat how code, a set of files or a feature works, even when the user only asks what the files do. Also use when a flow, a process, a lifecycle, a data model, a type hierarchy or an architecture is explained in documentation, when the user plans a change to one, when an issue or a pull request changes one, when a code change touches a file a diagram links, or when the user names the diagrams skill.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- diagrams
- description
- diagrams, the rules for every Mermaid diagram. Use whenever you explain in chat how code, a set of files or a feature works, even when the user only asks what the files do. Also use when a flow, a process, a lifecycle, a data model, a type hierarchy or an architecture is explained in documentation, when the user plans a change to one, when an issue or a pull request changes one, when a code change touches a file a diagram links, or when the user names the diagrams skill.
03 SKILL.md 正文
Rules for every diagram you draw or touch. A diagram answers one question about a flow or a structure faster than the code or a page of prose does. It is a mermaid code block in Markdown. The text is the only source, so a person reads the picture and an agent reads the block. GitHub, VS Code and JetBrains render it without a build step.
Steps
- Decide whether a diagram helps. A flow or a structure you explain is a diagram. A single step or a single relation, such as one function that calls another, has nothing to connect and stays a sentence. The steps a reader follows in a how-to stay a numbered list. Values the reader looks up stay a table. When you explain a flow or a structure in chat, draw it without being asked.
- Name the question. One diagram answers one question, written as one sentence in the language of the surrounding document, or of the conversation in chat. A second question is a second diagram.
- Pick the type. Take it from Types by the question. Another type only when the user asks for it.
- Read the code. Every element of a diagram of the current state exists in the code. Every edge is a call, a transition or a relation you read there. What you did not read is left out, never guessed. A diagram of something that is not built yet is a planned state.
- Draw. Every line follows Form. A diagram the reader cannot take in at a glance is split. The overview keeps the main path and folds each group of steps into one element. Every folded group gets a diagram of its own.
- Explain and link. Add the terms and the example and the table of Sources.
- Place it. The file follows the
project-docsskill. An existing structure of the project wins.- A diagram of the whole project, such as its architecture, its data model or a process across features, lives in
docs/<topic>.md. - A diagram of one flow or one feature lives in the
README.mdof the folder that holds its code, such assrc/orders/README.md. GitHub shows that file when the reader opens the folder. - Code that has no folder of its own sends the diagram to
docs/<topic>.md. - A detail diagram lives in the
README.mdof the subfolder it describes. The overview links it from its table. - A folder that needs more than one diagram keeps the overview in its
README.md. Every detail diagram without a subfolder of its own gets a file in thedocs/folder next to the code, one diagram per file and named after what it shows, such assrc/extraction/pdf/docs/byte-checks.md. The overview links each file from its table.
- A diagram of the whole project, such as its architecture, its data model or a process across features, lives in
- Show it. A terminal prints a
mermaidblock as text. Write every diagram you show in chat into$TMPDIR/diagrams/<topic>.mdas well, outside the repository, and name the path. The user opens it in the Markdown preview of the IDE.
Done when every diagram names its one question, takes the type of that question, shows only what the code holds, links each element to its source, sits where the reader looks for it, parses without an error, and a reader understands it without opening the code.
Types
| The reader asks | Type | Instead |
|---|---|---|
| What happens in which order, and where does it branch? | flowchart |
|
| Who is responsible for which step? | flowchart with one subgraph per role |
sequenceDiagram when the messages matter more than the work |
| Who talks to whom, and when? | sequenceDiagram |
|
| Which states does it pass through? | stateDiagram-v2 |
flowchart when the nodes are actions |
| How does the data relate? | erDiagram |
classDiagram when behaviour or inheritance matters |
| How do the types relate? | classDiagram |
flowchart for plain dependencies between modules |
| What is the system made of? | architecture-beta |
|
| When does what happen? | timeline, gantt for durations, gitGraph for branches |
A list, unless time is the question |
| How is it divided? | mindmap |
flowchart once the parts link across |
The same question takes the same type inside the code, around it and in the domain. A control flow, a CI pipeline and an order process are all a flowchart.
architecture-beta is a beta type of Mermaid. Its icons are cloud, database, disk, internet and server, and it takes no classDef.
Form
- The first line after the keyword is
accTitle, followed by the question of step 2. A type that knows noaccTitle, such asmindmap,sankey-betaandblock-beta, takes the question astitlein its front matter. - An ID is the name the element has in the code, in lowerCamelCase, such as
checkOrder. Never a single letter and neverend. - A label says what happens in the words of the domain, a step with its verb first, such as
"Charge the payment", never the operator or the call in the code, such as"amount > limit". It stands in double quotes and in the language of the surrounding document. - Every branch of a decision carries its condition as the label of its edge. An edge that ends the flow early also names the reason, unless the condition already explains it. An error or a log code follows in parentheses, such as
-->|"over 20 MB, the parser holds the whole file in memory (file_too_large)"|. - A
flowchartrunsTD. A pipeline without a branch runsLR. - Declare the elements in reading order, so the edges cross as little as possible.
- A comment is
%%on a line of its own. - Meaning stands in the text. A colour or a shape alone never carries it.
- A
flowchart, astateDiagram-v2and aclassDiagramcarry the line%%{init: {"htmlLabels": false}}%%right before the keyword, after the front matter when there is one. Without it Mermaid draws each label as HTML in a box it measured at 100 % zoom, and Safari and Chrome cut the text off at any other zoom. With it every label is SVG text that wraps inside its shape. The other types draw SVG text on their own. - Only the syntax of the Mermaid version that Mermaid names. No
click, no icon, no other%%{init}%%, noconfigin the front matter and no ELK layout. Every renderer applies its own theme and layout, so nothing depends on where an element lands.
Sources
The table stands right under the diagram, with only a blank line between them. It has one row per element that exists in the code, a node, a participant, a state, an entity, a class or a service. The first cell is the ID as the diagram writes it. The second cell is a relative link to the file, with the symbol as its text. An element that folds a group links the file that holds its detail diagram, a README.md or a file under docs/.
```mermaid
%%{init: {"htmlLabels": false}}%%
flowchart TD
accTitle: How does an order get from the cart to the warehouse?
checkOrder["Check the order"] --> chargePayment{"Charge the payment"}
chargePayment -->|paid| shipOrder["Ship the order"]
chargePayment -->|declined| rejectOrder["Reject the order"]
```
| Element | Source |
| --- | --- |
| `checkOrder` | [`checkOrder`](checkout.ts) |
| `chargePayment` | [`chargePayment`](payment.ts) |
| `shipOrder` | [`shipOrder`](checkout.ts) |
| `rejectOrder` | [`rejectOrder`](checkout.ts) |
timeline, gantt, gitGraph, journey and mindmap take no table, because no file stands behind their elements.
Terms and example
- Every term the reader needs, of the domain or of the code, is explained once, in a table with the columns
TermandMeaningabove the diagram. The diagrams of one folder share the table in itsREADME.md. - A flow that computes a value or checks a limit gets a worked example under the table of sources. It runs one input through the flow with real values from the repository, such as the limit its configuration sets, and names the edge each step takes.
Planned state
A planned state is a sketch of something that is not built yet, or the effect of a change the user considers. It helps the user decide before the code changes.
- It goes into the chat, as step 8 shows it, and into the issue or the pull request that carries the change, as the
issueandpull-requestskills place it. The documentation shows what exists. A planned state enters it only on the user's word, under a> [!NOTE]that calls it a draft. - It takes no table of sources, because its new elements have no file yet.
- A change is one diagram of the future state. Every element the change touches takes one of the classes
added,changedandremoved. A removed element stays in the diagram, and the edges to it are dotted. The threeclassDeflines close the diagram as written below. - Under the diagram stands the legend as one sentence, then one bullet per consequence, such as a caller, a table, a test or a document the change also touches.
- Only the four types of the table below take a
classDef. In every other type, such assequenceDiagramandarchitecture-beta, the change is two diagrams, the current state under Before and the future state under After.
```mermaid
%%{init: {"htmlLabels": false}}%%
flowchart TD
accTitle: How does an order run once the fraud check exists?
checkOrder["Check the order"] --> chargePayment{"Charge the payment"}
chargePayment -->|paid| checkFraud["Check for fraud"]:::added
checkFraud --> shipOrder["Ship the order"]:::changed
chargePayment -.->|paid| shipDirectly["Ship without a check"]:::removed
chargePayment -->|declined| rejectOrder["Reject the order"]
classDef added fill:#d1f0d9,stroke:#1a7f37,color:#000,stroke-width:3px
classDef changed fill:#fff3c4,stroke:#9a6700,color:#000,stroke-dasharray:6 3
classDef removed fill:#eee,stroke:#888,color:#555,stroke-dasharray:2 2
```
A thick border is added, a dashed border is changed, a dotted grey border is removed.
- `shipOrder` waits for the fraud check, so an order ships later.
- The tests of `checkout.ts` cover the direct path and need the new one.
| Type | An element takes a class as |
|---|---|
flowchart |
checkFraud["Check for fraud"]:::added |
stateDiagram-v2 |
class Checked added |
classDiagram |
class FraudCheck:::added |
erDiagram |
FRAUD_CHECK:::added |
Update
A diagram in the repository is true for the current code. Bring it up to date when the user asks, when the hook reports path:line linked at the end of a turn, and when the pull-request skill asks for the files of a branch.
- Find the diagrams. The hook names the ones in a
README.mdabove the changed file and in adocs/folder beside one of those. For a diagram anywhere else, and without the hook, search the Markdown files for links to each changed file withgrep -rn --include='*.md' -F '<file name>' .and keep the hits that stand in a table under amermaidblock. - Read the code again, as step 4 of Steps does.
- Change what differs, in the diagram and in its table. An element whose file is gone leaves both.
- Report. Show the old and the new block as a diff. A diagram that still holds is named as unchanged.
Mermaid
GitHub, VS Code and JetBrains each ship their own Mermaid, and the oldest of the three decides what a diagram may use. That version is 11.15.0. The hook checks the syntax with the Mermaid of the project, so the project pins exactly that version. If a project with a package.json has no mermaid, install it after confirmation with the "Add dev dependency" command of the package-manager skill.
pnpm add -D --save-exact mermaid@11.15.0
Hook feedback
When a turn ends, a Stop hook parses every mermaid block of a Markdown file the turn changed with the Mermaid of the project. When it reports path:line syntax with the message of the parser, fix each reported line, then end the turn. A project without Mermaid gets no syntax check. The hook also reports path:line html-labels for a flowchart, a stateDiagram-v2 or a classDiagram without the init line of Form, with or without Mermaid in the project. Add the line, then end the turn. For any file the turn changed, however it changed, the hook reports path:line linked and the changed files for each diagram whose table links one of them. A diagram whose own file the turn changed is not named. Run Update on each of them. In a project that has Mermaid, silence means every diagram parses. The rules above still apply.
04 同仓库更多 Skills
why
Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
tdd
Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested.
swarm
Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration.
show-me-your-work
Keep a reviewable decision trail for long-running or unattended work: a TSV log with one row per decision (what, why, evidence, result). Local by default; commit it when a reviewer needs the trail to trust the result. Use for /show-me-your-work, autonomous or multi-phase runs, or work a human reviews after stepping away.
interrogate
Use for "interrogate", "adversarial review", "multi-model review", "challenge this", "stress test this code", "find blind spots", or "tear this apart". Multiple LLM reviewers challenge changes from independent angles.
how
Use for "how does X work", code walkthroughs before changing something, and placement / ownership / layering questions ("where should this live", "which package owns this", "is this the right layer"). Explains subsystem architecture, runtime flow, onboarding mental models. Use why for motivation.