c4m

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.

Mode	Slash command	Fires on	Flow
Design	/c4m:design	Vague idea, no code	Framing → Context → Container → optional Component → finalization
Document-code	/c4m:code	You point at a repo	Quick framing → scan (delegates to an Explore sub-agent on large repos) → review → dialogue → deliver
Document-prose	/c4m:prose	You paste a README / ADR / spec	Extraction → gap-filling dialogue → deliver
Review	/c4m:review	You paste a diagram + "is this good?" or "explain this"	Checklist critique (grouped by severity) or structured narration
Update	/c4m:update	You have a C4 + "add / remove / change X"	Read, clarify the diff, update every affected level
(any / unsure)	/c4m:auto	Any of the above	Detects the mode from what follows the invocation, then routes

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.