Logic first, pixels last — a Claude Code skill that turns a process, program, or decision into a flowchart by deriving the logic as a completeness-checked table before it draws anything.
A flowchart is a projection of verified logic, never a freehand drawing. This skill makes the model build and check the logic table first, then render it — so the diagram is correct, not just plausible.
Claude Code (recommended — auto-updates via marketplace):
/plugin marketplace add DavidChen-006/flowchart-skill
/plugin install flowchart
Codex, Cursor, Copilot, Gemini CLI, or any of 50+ Agent Skills hosts:
npx skills add DavidChen-006/flowchart-skill -g
(-g installs globally for your user. Drop it to scope per-project.)
Manual (developer):
git clone https://github.com/DavidChen-006/flowchart-skill.git
ln -s "$(pwd)/flowchart-skill/skills/flowchart" ~/.claude/skills/flowchartThen use it: /flowchart <what you want charted>.
Ask any agent "make me a flowchart of X" and you usually get boxes around English: a diagram that looks like a flowchart but was drawn straight from a vibe. It looks authoritative, which is exactly what makes it dangerous.
Default prompting fails in specific, repeatable ways:
- Missing branches. It draws the happy path and quietly omits the error/timeout/empty cases. There's no check that every condition combination is handled.
- Invented control flow. For "how does this code work," the model charts what the code probably does from memory instead of reading it — confidently wrong.
- Unlabeled decisions. Diamonds with two arrows and no
yes/no, so the reader can't actually follow the logic. - No verification. Nothing ever asks "did we cover the whole space?" or "do two rules contradict?"
- Inconsistent visuals. Shapes and colors used decoratively, so shape stops meaning anything.
This skill attacks each of those by separating logic from rendering and refusing to draw until the logic is provably complete:
| Default "make a flowchart" | /flowchart |
|
|---|---|---|
| Order of work | draw, then maybe reconsider | build a completeness-checked table first, render last |
| Coverage | happy path; branches as the model remembers them | every cell addressed — action, impossible (reason), or don't care (—) |
| For existing code | charts from memory | refuses to chart unread source; reads it and cites file:line per row |
| Verification | none | count check (n binary conditions ⇒ all 2ⁿ rows), conflict check, adversarial pass |
| Decision edges | often unlabeled | every edge out of a decision is labeled |
| Visual language | decorative | fixed semantic shapes + a 6-color palette (style.md) |
| Output | one image | an editable .mmd for future edits + a PNG, vetted by a visual-QA loop |
The result is a chart you can trust enough to act on — and an editable source file so the next change updates the logic (and re-verifies) instead of redrawing from scratch.
Four phases (full spec in skills/flowchart/SKILL.md):
- Derive the logic — classify the request and pick the matching intermediate representation, then fill it in completely:
Logic kind Representation Completeness check Interacting conditions / business rules Decision table nbinary conditions → all2ⁿrows presentLifecycle / events / modes State × event grid no silently empty cell Sequential pipeline Step × failure-mode table every step has a defined failure behavior Existing code ("how does X work") Trace table with file:lineper rowevery row cites source; read the code first - Verify — count check (is the whole space covered?), conflict check (do two rules disagree?), and an adversarial pass that actively hunts for 3+ unhandled scenarios (concurrent events, mid-step failures, repeated invocations) and folds real findings back in. The verified table is shown to you — it's the artifact the chart is judged against.
- Render — a dedicated Opus subagent turns the table into Mermaid, following a fixed style reference. Every table row maps to a traceable path; no node exists without a row. It runs a visual-QA loop (renders, reads the PNG, fixes clipping / overlaps / crossing arrows / unlabeled edges / contrast, re-renders — up to 3 passes).
- Deliver — the lead verifies the PNG exists and is complete top-to-bottom, then hands back the table, the PNG path, and the editable
.mmd.
Editing an existing chart? Phase 0 finds it in ~/.claude/flowcharts/, applies the change to the logic table first, re-verifies, and re-renders from the edited source — never a blank-slate redraw.
- Logic-first: a verified intermediate representation precedes every render.
- Completeness-checked:
2ⁿ-row coverage for decision logic, no empty cells for state grids, a failure behavior for every pipeline step. - Reads code before charting it: for "how does X work," it opens the source and cites
file:line; it will not chart from memory. - Adversarial verification: a dedicated pass to surface unhandled scenarios before they become missing branches.
- Fixed visual grammar: semantic shapes (stadium / rounded-rect / diamond / parallelogram / double-rect / error) and a 6-color light palette — shape and color always mean something.
- Editable output: an
.mmdsource file (with a header comment recording purpose + where the logic lives) so future edits re-derive context. - Scales by decomposition: logic past ~15 nodes is factored into linked sub-process charts instead of one unreadable mega-chart.
- Claude Code (or another Agent Skills host).
- Node.js — rendering uses
@mermaid-js/mermaid-clivianpx(no global install needed;npxfetches it on first run).
/flowchart how does the retry logic in src/queue.py work
/flowchart the refund eligibility rules for our store
/flowchart the state machine for a websocket connection
You can also just ask in plain language for "a flowchart/diagram of …".
- Editable source:
~/.claude/flowcharts/<slug>.mmd - Rendered image:
~/Downloads/<slug>.png
See examples/ for a small, fully worked refund-eligibility flow — the decision table, its verification, and the example.mmd projection.
Issues and PRs welcome. Good contributions:
- New intermediate representations or completeness checks (keep them logic-first).
- Style-reference improvements in
skills/flowchart/references/style.md(the single source of truth for renders). - Worked examples in
examples/(generic, no private/third-party system internals).
Please keep the README and skill behavior in sync — describe only what SKILL.md actually does.
MIT © 2026 David Chen