michi-diagrams
A diagram earns its place when it shows a relationship the prose can only describe: who hands off to whom, where a rejected record goes, which checks gate a release, what loops back. This skill turns facts in a document into that figure, as Mermaid source that lives in the markdown.
Two things decide whether the figure is any good. It has to be true to the source, and it has to render the same everywhere the document is read — GitHub in light and dark mode, VS Code, JetBrains, Obsidian.
When to use
Section titled “When to use”- A design doc, README, spec or architecture page needs a figure of a pipeline, a hand-off, a decision flow, a state lifecycle, a data model, a sequence of calls, or a plan
- You say “add a diagram”, “draw the flow”, “show how X works”
- Another skill is writing a document and needs figures —
michi-libraryuses it for the project library - An existing Mermaid block renders badly, looks wrong in dark mode, or breaks on GitHub
What it does
Section titled “What it does”- Finds the relationship — the one thing the reader should see that a bullet list can’t show. If it can’t name one, it says a diagram is the wrong tool.
- Fixes the facts — the components, edges and boundaries to draw, each traced to the source. Nothing goes on the figure that isn’t in that list; an inference is drawn dotted and said so.
- Picks the smallest diagram type that fits — a flowchart by default; a sequence diagram, state diagram, ER diagram, Gantt chart or mindmap when its grammar matches the meaning; a class diagram only when the source is actually object-oriented.
- Drafts with a consistent visual grammar: each shape means one thing, solid and dotted edges mean different things, groups are real boundaries, labels stay short.
- Renders in light and dark, and looks. Clipped labels, collapsed groups, text unreadable on dark — fixed and
rendered again until clean. Rendering
<name>.mmdwrites<name>.light.pngand<name>.dark.pngnext to it (and a<name>.light.error<name>.dark.errthere when a render fails), so delete them or ignore them in git. - Delivers the Mermaid block (or a
.mmdfile, if you ask for one) with a one-sentence caption that tells the reader what to notice. It says “rendered and inspected” only if it was.
Key things to know
Section titled “Key things to know”- No theme directives, no ELK layout. Both break or silently change on GitHub. Colour goes in class definitions that set fill, stroke and text colour, so dark mode stays readable.
- Colour is a category, not decoration — and never the only carrier of a meaning.
- One idea per diagram. Past about fifteen nodes it splits into an overview and detail figures, and never merges two things the source keeps separate.
- Rendering uses
mmdcwhen it’s installed, otherwisenpxwith Node 22.13 or later (the first run downloads a headless browser). - Credits. The skill is original work; a few parser traps, a guidance note, and the “rendered and inspected”
distinction are adapted from MIT-licensed community skills, and its twelve techniques from Yugene Lee’s “12 Mermaid
Tricks Worth Copying”. The skill’s
NOTICEfile lists them.
For the full agent instructions, see the SKILL.md source.