c4-model

A Claude Code skill for producing C4 architecture diagrams (Simon Brown's model), interactively.

How it works

When you ask for an architecture diagram (or run /c4m:auto), the skill first figures out what you're actually doing. Designing a new system from a vague idea is a different job from retro-documenting an existing codebase, which is different again from reviewing someone else's diagram or updating one you already have.

Once the mode is clear, it runs the matching workflow: a structured dialogue, batches of no more than five questions at a time, with an explicit validation checkpoint at every level. Nothing gets written to disk until you say it's final.

If you already know which mode you want, a dedicated slash command skips the detection step (/c4m:design, /c4m:code, /c4m:prose, /c4m:review, /c4m:update). Or invoke /c4m:auto and let the router pick. See The 5 modes below.

By default the output is one Markdown document per C4 level (Context, Container, optionally Component) with the diagram embedded as Mermaid. Format and destination are negotiated at the start: Structurizr DSL, PlantUML, or an MCP destination (Notion, Linear, Google Drive) are all on the table.

See skills/c4-model/examples/ for a filled-out Context + Container pair built from Simon Brown's canonical Internet Banking System.

Installation

Claude Code plugin marketplace

/plugin marketplace add cheriftj/c4-model-skill
/plugin install c4m@c4-model-skill

Copy into a single project

cp -r path/to/this-repo/skills/c4-model /your/project/.claude/skills/

Claude Code auto-discovers skills under .claude/skills/ in the current project.

Install for all your projects

cp -r path/to/this-repo/skills/c4-model ~/.claude/skills/

The 5 modes

Each mode has a dedicated slash command. Claude Code namespaces commands under their plugin, so every command is prefixed with /c4m:. Use the auto variant if you want the router to pick the mode; use the mode-specific variants to skip detection.

Supporting diagrams (System Landscape, C4Deployment, C4Dynamic) are offered on explicit request from within any mode.

Example conversations

Design mode (via /c4m:design or a natural prompt)

You:   /c4m:design I'm building an event-sourced order management system.

Claude: Before we draft anything, a few quick questions (max 5):
        1. System name + one-line business intent?
        2. Audience (tech team, stakeholder, onboarding)?
        3. Which levels: Context only, Context + Container, deeper?
        4. Output format? Default is Mermaid + Markdown; alternatives: Structurizr DSL, PlantUML.
        5. Destination? Default docs/architecture/, or a Notion/Linear/Drive MCP if available.

You:   Orders MS, greenfield. Tech team audience. Context + Container. Defaults.

Claude: Got it. For Context first: who interacts with this system, and what external systems does it depend on?

[... dialogue continues, diagram emerges, user validates each level ...]

You:   Finalized, looks good.

Claude: Writing docs/architecture/01-context.md and docs/architecture/02-container.md now.

Without the slash command, the same flow is triggered by any architecture-design request (e.g. "help me design an order management system") — the skill's router detects Design mode from the signal.

Review mode (via /c4m:review)

You:   /c4m:review
       ```mermaid
       C4Container
           title My API
           Container(api, "API", "Node")
           ContainerDb(db, "DB")
           Rel(api, db, "Uses")
       ```

Claude: 3 issues, grouped by severity.

        BLOCKING
        - Missing title scope ("My API" doesn't say which system).
        - Container(db, "DB") has no technology — mandatory on every Container.
        - Rel(api, db, "Uses") is a bare verb — state the intent and the protocol,
          e.g. "Reads and writes orders to" with protocol "JDBC".

        IMPORTANT
        - No legend, no scope/description on the API.

        NICE-TO-HAVE
        - Consider a System_Boundary around the API + DB for visual grouping.

        Want me to apply these corrections? That would switch us to /c4m:update.

Other modes (/c4m:code, /c4m:prose, /c4m:update) follow the same shape: explicit slash command, a short framing dialogue, then the deliverable.

What makes it honest

• Mode detection first. Don't generate if we don't know what you want.
• Simon Brown's golden rule. Context + Container are enough for most teams; Component only on explicit request.
• One Markdown document per level. Never a bare Mermaid block.
• Relation labels state intent. "Uses", "Calls", "Reads" are banned on their own.
• Technology is mandatory on every Container and Component.
• Assumptions stay explicit. Inferences never slip silently into the diagram.
• Grounded in authority. The Mermaid syntax reference is rebuilt from mermaid.js.org; the review checklist from c4model.com. Editorial additions are separated from sourced content.

Contributing

Bug fixes, wording improvements, and new modes are all welcome. For anything larger than a typo, open an issue first so we can agree on scope before code is written. See CONTRIBUTING.md for the editorial invariants, the PR checklist, and the release process. This project follows the Contributor Covenant Code of Conduct.

License

MIT. See LICENSE.

Credits

The C4 model is by Simon Brown; the example deliverables in this repo use his canonical Internet Banking System. The Mermaid C4 syntax comes from the Mermaid project.