Skip to content
Michi v2026.11.16
Save the Tokens

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.

  • 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-library uses it for the project library
  • An existing Mermaid block renders badly, looks wrong in dark mode, or breaks on GitHub
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Renders in light and dark, and looks. Clipped labels, collapsed groups, text unreadable on dark — fixed and rendered again until clean. Rendering <name>.mmd writes <name>.light.png and <name>.dark.png next to it (and a <name>.light.err or <name>.dark.err there when a render fails), so delete them or ignore them in git.
  6. Delivers the Mermaid block (or a .mmd file, 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.
  • 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 mmdc when it’s installed, otherwise npx with 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 NOTICE file lists them.

For the full agent instructions, see the SKILL.md source.