Menu
Architecture diagrams for documentation. Covers ASCII, Mermaid, C4, and D2. Applies C4 methodology by default. Trigger terms: diagram, flowchart, architecture diagram, sequence diagram, C4, mermaid, ascii diagram.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Write Architecture Decision Records when making significant technical choices. Use when selecting tools, patterns, frameworks, or making structural changes that future developers need to understand.
Write AGENTS.md files that serve as operating contracts for AI agents. Use when creating or updating AGENTS.md for a project. Trigger terms: AGENTS.md, agent instructions, agent contract, agent configuration, coding agent setup.
Quality rules for changelog entries. Use when validating, writing, or reviewing changelog content to ensure user-facing value communication.
Task completion sequence including verification, git, signaling, and handoff. Use when finishing a task or reporting status.
Classify documentation by audience and content type. Use when planning, auditing, or placing project documentation.
Audit project documentation for quality, completeness, and freshness. Use when assessing documentation health, planning cleanup, or measuring improvement.
| name | diagrams |
| description | Architecture diagrams for documentation. Covers ASCII, Mermaid, C4, and D2. Applies C4 methodology by default. Trigger terms: diagram, flowchart, architecture diagram, sequence diagram, C4, mermaid, ascii diagram. |
C4 zoom level — which abstraction?
Format — ask user, or default to ASCII:
| Situation | Format | Why |
|---|---|---|
| Inline in docs | ASCII | No tooling, survives copy-paste |
| GitHub/GitLab rendered | Mermaid | Native rendering |
| Architecture with containers | D2 | Auto-layout, container edges |
| Formal design doc | C4 PlantUML | Full methodology via Kroki |
Rules:
┌ ┐ └ ┘ │ ─ ┬ ▶ ▼Use for: sequence diagrams, flowcharts with branches, state machines.
C4 in Mermaid:
C4Context
Person(user, "User", "Uses the system")
System(sys, "Our System", "Does the thing")
Rel(user, sys, "Uses")
| Type | Comfortable | Max | Then use |
|---|---|---|---|
| Flowchart | 15–25 | ~70 | D2 or Graphviz |
| Class | 10–15 | ~40 | Split diagrams |
| Sequence | 5–8 participants | ~15 | Split scenarios |
Workarounds: subgraph clustering, split into linked diagrams.
direction: right
user: User {shape: person}
system: Our System {
api: API
db: Database {shape: cylinder}
}
user -> system.api: Uses
system.api -> system.db: Reads/Writes
Render: POST https://kroki.io/d2/svg
Every architecture diagram must answer: