diagramming
Skill1 starsChanged 24 days agoMITView on GitHub
How to draw diagrams and write math in codelabgen lessons — choosing Mermaid, D2 or Graphviz, generating diagrams from the code itself, size and labeling rules, and LaTeX conventions that render on both GitHub and the MkDocs site.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- z-Zihan/Evirtheir own version, first seen Oct 13, 2026
- ddmsolutions/claude-skillstheir own version, first seen Aug 27, 2026
- ArvindChander/skill-labtheir own version, first seen Jul 27, 2026
- CtriXin/diagramming-skilltheir own version, first seen Mar 28, 2026
- tEhThing/claude-skills-diagrammingtheir own version, first seen Dec 8, 2025
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- z-Zihan/Evir★ 11same name
- CtriXin/diagramming-skill★ 4same name
- tEhThing/claude-skills-diagramming★ 2same name
- ArvindChander/skill-lab★ 1same name
- ddmsolutions/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- code-authoringSkill
- codelabgen-orchestratorSkill
- course-extensionSkill
- curriculum-designSkill
- example-designSkill
- lesson-reviewSkill
- notes-writingSkill
- readalong-writingSkill
- runtime-strategySkill
- site-assemblySkill
- source-articlesSkill
- source-books-coursesSkill
- source-digestSkill
- source-evaluationSkill
- source-github-reposSkill
- source-official-blogSkill
- source-official-docsSkill
- source-package-internalsSkill
- source-papers-specsSkill
- source-qaSkill
- source-talks-workshopsSkill
- source-universitySkill
- state-protocolSkill
- topic-extractionSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Default to Mermaid. Use D2 or Graphviz only when codelabgen doctor shows the tool as ok.
- Very specific: line 24
Put the source in <lesson dir>/docs/diagrams/<name>.d2 (or .dot) and run codelabgen diagrams render <id> --course <dir>.
- Distinctive: line 26
No colors or fonts in the source: the renderer's themes handle light and dark mode.
- Distinctive: line 27
Keep it readable at page width: about 20 shapes at most.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Diagrams and math in lessons
A diagram earns its place when the reader needs to see structure or flow: how parts connect, the order things happen in, how state changes. Don't draw what a sentence says just as well.
Choosing the tool
| Need | Tool | Why |
| Flows, graphs of nodes, sequences, state machines | Mermaid (```mermaid block) | GitHub renders it natively; no build step |
| A diagram of something the library can draw itself | Generated from the code | It always matches the code |
| Architecture, layered systems, many containers | D2 (docs/diagrams/<name>.d2 + rendered .svg) | Better layout for big pictures |
| Dense graphs | Graphviz (docs/diagrams/<name>.dot + .svg) | Handles many edges |
Default to Mermaid. Use D2 or Graphviz only when codelabgen doctor shows the tool as ok.
D2 and Graphviz
- Put the source in
<lesson dir>/docs/diagrams/<name>.d2(or.dot) and runcodelabgen diagrams render <id> --course <dir>. It writes<name>.svgnext to the source. Graphviz SVGs have a transparent background; D2 SVGs switch between a light and a dark palette with the reader's color scheme.codelabgen verifyre-renders changed sources too. - Reference the SVG from the docs:
. Never reference the source file. - No colors or fonts in the source: the renderer's themes handle light and dark mode. Labels in the course language, short.
- Keep it readable at page width: about 20 shapes at most.
Generate from the code when you can
Libraries that build graphs can often draw them. For example, LangGraph's compiled graph prints Mermaid:
cd <lesson dir>
env -u VIRTUAL_ENV uv run python -c "from l1_2_routing.graph import build_graph; print(build_graph().get_graph().draw_mermaid())"Paste the result into a ```mermaid block and add a sentence saying it was generated from the code. You may simplify styling, but never change the structure.
Mermaid rules
- At most about 15 nodes. Split larger pictures, or show one level of detail.
- Labels in the course language, short (1–4 words). Identifiers stay as they are:
route(),TicketState. - Pick the right type:
flowchart LR/TDfor flows and graphs,sequenceDiagramfor interactions over time,stateDiagram-v2for state machines. - No hard-coded colors or themes. Let GitHub and the site apply light and dark themes.
- Put labels with spaces, parentheses or non-Latin text in quotes:
A["Классификация (classify)"]. - Introduce each diagram with one sentence saying what to look at.
Math
- Inline:
$…$with no spaces just inside the delimiters ($O(n)$, not$ O(n) $). - Block:
$$…$$on lines of their own, with a blank line before and after. - Nothing else: no
\(…\), no```mathblocks. - Escape a literal dollar sign in prose as
\$. - Formulas with
_or*in several places go in block form, so Markdown on GitHub doesn't mangle them.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.