loom-diagramming
Installation
SKILL.md
Diagramming
Overview
Create maintainable technical diagrams in Mermaid (renders in GitHub, GitLab, and most doc tools). Diagrams live in version control next to code — they must stay in sync or they mislead. This skill covers type selection, syntax, and the parsing footguns that waste the most time.
Choose the diagram type
| Type | Use when | Not when |
|---|---|---|
| Sequence | Interactions over time across participants | Showing static structure |
| Flowchart | Decision logic, process/pipeline steps | Timing between services (use sequence) |
| State | An entity's lifecycle + transitions/guards | Data flow or call order |
| ERD | Data model, tables, cardinality | Runtime behavior |
| Class | OO structure, interfaces, inheritance | Deployment or infra |
| C4 (Context) | System boundary + external actors/systems | Internal code detail |
| C4 (Container) | Deployable units + their tech + data stores | Class-level detail |
Rule of thumb: structure → flowchart/C4/class/ERD; behavior over time → sequence; lifecycle → state. For architecture, prefer C4's layered zoom (Context → Container → Component) over one sprawling diagram.