flow
Draw a flow diagram (what talks to what) or a sequence diagram (who calls whom, in what order, who waits). A chat diagram of about 12 boxes or fewer is drawn by hand and checked with fd --lint; a larg
SKILL.mdskills/flow/SKILL.md
GitHubFlow and sequence diagrams
First: count the boxes
| Diagram | Make it by |
|---|---|
| About 12 boxes or fewer, for chat only | drawing it by hand, then fd --lint (By hand, then lint) |
| Larger, or it also needs a picture page or a walkthrough | Mermaid, then fd or pic |
Decide this before you write any Mermaid. A hand layout of a small diagram is shorter and clearer: 5 boxes drawn by hand fit in 11 rows, and the same 5 boxes from fd take 31.
Mermaid: one source, three outputs
One Mermaid source, three outputs. The diagrams:walkthrough skill is the top layer and reads the same Mermaid.
Mermaid ─┬─► fd file.mmd ─────────► Unicode text in a ```text fence (chat)
├─► pic file.mmd ────────► picture page: clean (default) or sketch
└─► walkthrough skill ──► picture + voice, cues, quiz
Pick the diagram type by the question
| The reader asks | Draw | Mermaid header |
|---|---|---|
| What are the parts, and what flows between them? | flow | graph LR (a chain) or graph TD (a tree) |
| In what order do calls happen? Who waits for whom? When does the reply go back? | sequence | sequenceDiagram |
| Both (a new system, an incident) | flow first, then the sequence of the one path that matters | both |
A sequence shows what a flow hides. Example: at checkout the shop tells the customer "processing" before the payment provider confirms; the confirmation arrives later by webhook. A flow diagram cannot show that ordering.
1. Chat text (works everywhere)
Two ways to make it. Both end in a ```text fence.
| Diagram | Make it by | Why |
|---|---|---|
| About 12 boxes or fewer, chat only | drawing it by hand, then fd --lint |
Hand layout reads better: tight groups, labels on arrows, a legend row |
| Also needs a picture page or a walkthrough, or is larger | Mermaid, then fd |
One source for every output, alignment is exact |
By hand, then lint
Draw with box-drawing characters: ─ │ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼, dotted ┄ ┆ for async, rounded ╭ ╮ ╰ ╯ for storage, arrowheads ▶ ◀ ▲ ▼ (sync) and ▷ ◁ △ ▽ (async). Lay it out across and down: put a group frame around parallel boxes, label arrows next to the line, and add one Legend: row for the line styles. Then check it:
"${CLAUDE_SKILL_DIR}/fd" --lint diagram.txt # or pipe the text in: ... | fd --lint -
- The check finds lines that are one column off, junctions with nothing under them, arrowheads that stop short of a box, and anything over 90 columns or 45 rows. Each problem has its row and column. Fix every one, then lint again. Paste only a diagram that passes.
- Rows that start with
LegendorKeyare not checked, because their sample arrows touch nothing. - A line that touches a box edge or crosses another line without a junction is allowed. A line next to a junction whose arm points at empty space is reported as misplaced.
From Mermaid
"${CLAUDE_SKILL_DIR}/fd" diagram.mmd
- Paste stdout into a
```textfence. It is plain Unicode, so it reads the same in the terminal and in the desktop app. Never paste raw Mermaid into chat: neither surface renders it. - stderr reports the size (
fd: 43 cols x 37 rows) and notes. Keep chat text within 90 columns and about 45 rows. If a note says it is too big, shorten labels, split the diagram, or make a picture instead. - Use
graph LRfor a chain of calls: it reads left to right, like the request, and stays short. Usegraph TDfor a tree or a wide fan-out.fdswitches anLRflow toTDby itself when it is wider than 90 columns or its lines fail the check. - In a sequence, write branches as a
Note over X: ....alt/opt/loopblocks render badly as text, andfdwarns about them. - Chat text is single-colour by nature. Shapes carry meaning:
[( )]store (rounded),{ }decision (◇),-.->async (dotted). fd file --asciigives plain + - | > for limited terminals.fd file --jsonprints the parsed diagram.
Bigger Mermaid flows that spread across and down
graph LR with a fan-in and a fan-out still fits chat when it stays under 90 columns. The layout follows the order of the arrows, so write the source with care:
- Write the main path's arrows first. The first arrow out of a node stays on the main row; later arrows branch down. (
orders --> paybeforeorders --> dbkeeps the payment path straight.) - Put the parallel ends of a fan-in or fan-out in a
subgraph(Clients,Workers). The group frame keeps their arrows apart. - Lint the output too (
fd diagram.mmd | fd --lint -): the renderer can put a line one column off. Read every arrow before you paste it. If two arrows share a line segment (a┴or┬where they join), a reader cannot tell which box an arrow comes from. Reorder the arrows or add a subgraph until each arrow has its own path.
2. Picture page (clean or sketch)
"${CLAUDE_SKILL_DIR}/pic" diagram.mmd --look look.json --title "Checkout" -o out.html
- Clean is the default: crisp lines and one text weight, with colour for emphasis. Use it for anything read for its values: real runs, comparisons, dense diagrams.
--theme sketchgives hand-drawn boxes and arrows (rough.js) on graph paper, with the Architects Daughter font, for an early design that should look like a draft. - Colour means the same in both themes. The fill says who runs a box; the outline and labels stay dark ink so text always wins.
- Arrows are routed by libavoid. They never cross a box, and each one gets its own attachment point.
- Prints one JSON line
{"ok", "out", "warnings"}. Read the warnings. "Wider than tall" means: giveatpositions in the look, or usegraph TD. - To show the page, serve its folder on localhost (a launch.json preview entry, or
python3 -m http.server) and open it in the browser pane, which cannot openfile://URLs. Look at it before you hand it over.
The look file: what Mermaid cannot say
{
"customer": {"kind": "external", "color": "slate", "at": [0, 0]},
"provider": {"color": "sky"},
"decide>orders": {"tone": "good"},
"legend": [{"color": "slate", "label": "Outside your system"}, {"color": "sky", "label": "Payment provider"}]
}
- Node id keys:
at[col, row] (give it for every node or none; without it, nodes are placed in layers along the arrows),color,kind(service,external= dashed,store,decision),sub,label. - Subgraph id keys:
color. from>tokeys:tone(good,warnorbad) on the arrows that leave a decision.- Colours mean something, never decoration: slate = outside your system (people, their devices, third parties), sky = cloud or vendor services, emerald = your app (the default), amber = waits for a person, rose = failure. Add a
legendwhenever more than one colour appears.
Mermaid rules that matter here
- Define each node with its label (
pay[Payment API]) before the first arrow that uses it. The parser keeps a node's first mention, soshop --> payfirst leaves the label as "pay".fdstops with an error when this happens. - A second label line is the sub-label:
shop[Shop API<br/>order service]. - Shapes:
[ ]service,[( )]store,{ }decision. Arrows:-->sync,-.->async,-->|label|labelled. - Sequence arrows:
->>call,-->>reply (dashed),-)async (dotted in text, like a flow). Messages are numbered 1, 2, 3… in order. The walkthrough lights them by number.
Setup and limits
- Needs Node 18+ and
uv:picrunsdiagram.pyon uv's Python 3.12 (plainpython33.9+ without uv). Libraries come from the plugin'spackage.json; Claude Code installs them on plugin install and update. In a loose copy, runnpm ciwherepackage.jsonis: beautiful-mermaid (MIT) for text and parsing, libavoid-js (LGPL) for arrows, roughjs (MIT) for the sketch, and @fontsource/architects-daughter (OFL). All run at build time; nothing loads from a CDN. - If roughjs or libavoid is missing, the picture falls back (clean theme, simple curves) with a warning.
- The examples are in
examples/:checkout.flow.mmd(+checkout.look.json),checkout.seq.mmd, andshop.hand.txt(a hand-drawn diagram that passes--lint).