| name | c4-architecture-docs |
| version | 1.0.0 |
| owner | swarmery-core |
| description | Document an epic/feature architecture with the C4 model -- system context/container/component/dynamic diagrams as Mermaid .mmd plus a narrative doc. NOT for rendering an existing .mmd (use mermaid-viewer). |
| color | cyan |
| docs | {"status":"reviewed","source_sha":"ff189543c257","updated":"2026-08-06T00:00:00.000Z"} |
Purpose
Produce house-consistent C4 architecture documentation for a big issue: a small set of Mermaid C4 diagrams (.mmd) plus a short narrative doc, filed in the task dir and rendered for review. C4 gives "maps of your code" at fixed zoom levels (System Context -> Container -> Component -> Code, plus supplementary types — System Landscape, Dynamic, Deployment) so every diagram is typed, labelled, and self-explanatory instead of "a confused mess of boxes and lines" (c4model.com, Simon Brown).
This skill owns the HOW — level selection, diagram grammar, boundary/technology-labelling rules, and the file-and-promote workflow. It authors .mmd source and narrative; it does not render (hand the .mmd to the project's Mermaid viewer/renderer) and it does not replace an ADR (that is the ADR template).
The project's own tiers, repos, and containers are not baked into this skill — read them from .claude/project.json (repos, apps, mainApp, device, stack) and the project's CLAUDE.md. Ground every box in that real inventory.
When to use this skill
- User says "document the architecture", "draw the C4 / system context / container / component diagram", "give me an architecture diagram for this feature/epic".
- A big issue (epic, cross-tier feature, incident post-mortem, audit) needs a durable structural picture before or after implementation.
@architecture-designer reaches its "design architecture" step and needs the C4 grammar.- You need to show how the project's containers (from
.claude/project.json → repos/apps/stack) fit together for a specific change.
When NOT to use this skill
- You already have a
.mmd and just want to view it -- render it with the project's Mermaid viewer skill (if it has one) or the mmdc CLI.
- You want a FigJam / freeform whiteboard diagram -- use
figma:figma-generate-diagram.
- You only need to record a decision (options, trade-offs, consequences) with no structure diagram -- write an ADR from the ADR template.
- You need business-process / workflow / state-machine / data-model detail -- C4 deliberately omits these; supplement with the relevant diagram type, not a C4 view.
- A tiny single-file change -- an architecture doc is over-documenting; a one-line PR note suffices.
Required environment
rg / Glob / Read to inventory the affected repos before drawing (repo list from .claude/project.json → repos).- A task dir under
${AGENT_WORKSPACE_ROOT}/${AGENT_PROJECT}/workspace/working/YYYY/MM/DD/{slug}/ (create via agent-work.sh init or mkdir -p).
- A Mermaid renderer to view
.mmd for review — the project's viewer skill if it ships one, otherwise the mmdc CLI (@mermaid-js/mermaid-cli).
Inputs
| Input | Required | Description |
|---|
| Issue / epic scope | Yes | The big issue to document (issue-tracker id, MR, or prose). Sets which containers are touched |
| Affected repos | Yes | Which of the project's repos (.claude/project.json → repos) the change spans |
| Task dir / slug | No | Existing working/YYYY/MM/DD/{slug}/; created if absent |
| Promotion target | No | The project's architecture docs directory by default (matches @architecture-designer's {component}-design.md output path) if the doc is durable + cross-team; another project docs area only for a topic-specific doc (ASK-gated if it touches a contract) |
Outputs
Format: Mermaid .mmd source files + one narrative markdown doc, in the task reports/.
Length budget: Narrative doc <= 200 lines (diagrams carry the detail; prose only frames them). One .mmd per chosen level. This SKILL.md stays under 250 lines. Keep the final chat summary within the project's compression conventions.
Contents:
reports/architecture.md — narrative, structured per templates/architecture-doc-template.md.reports/c4-l1-context.mmd, reports/c4-l2-container.mmd, and reports/c4-l3-<container>.mmd / reports/c4-dynamic-<flow>.mmd as chosen.- Rendered
.html per .mmd (via the project's Mermaid renderer).
- Linked ADR(s) for each boundary/technology decision.
Procedure
-
Scope the issue. Classify it (epic / feature / incident / audit) and state the big issue in 2-3 sentences: what is in and out of scope. Read resources/c4-levels.md for the abstraction model (Person / Software System / Container / Component / Code) before drawing.
Checkpoint: one-paragraph scope written; you can name the systems the issue touches.
-
Pick the minimum C4 levels. Over-diagramming is the common failure — draw only levels that carry the argument (decision table below; full rationale in resources/c4-levels.md).
| Level | Diagram | Include when |
|---|
| L1 System Context | who/what talks to the system | Always — one diagram sets the frame |
| L2 Container | deployable units + their wires | Always — where most issues live |
| L3 Component | internals of one container | Only for a container this issue actually changes |
| L4 Code | class/function detail | Almost never — only a load-bearing algorithm; prefer IDE-generated |
| Dynamic | numbered runtime collaboration | Only for a tricky multi-step flow (e.g. a command handshake) |
| Deployment | per-environment infra map | Only when the issue changes how containers map onto infra; see resources/c4-levels.md §5 |
Rule of thumb: L1 + L2 for every big issue; add one L3 per touched container; add a Dynamic view only for a non-obvious runtime sequence.
Checkpoint: a level list with a one-line "why" each (seeds section 2 of the doc).
-
Inventory the real boxes. With rg / Glob / Read, confirm which containers the issue touches. Do not invent systems or protocols — ground every box in the project's real inventory (.claude/project.json → repos/apps/stack, the project CLAUDE.md, and the worked examples in examples/). Flag any of the project's safety-critical / do-not-touch paths now (the project's NEVER/ASK rules, if it defines them) — these change the review requirements.
Checkpoint: box/relationship list matches the inventory; do-not-touch overlaps noted.
Quick reference
| Level | Mermaid decl | Starter | Draw when |
|---|
| System Context | C4Context | templates/starter-system-context.mmd | Always |
| Container | C4Container | templates/starter-container.mmd | Always |
| Component | C4Component | templates/starter-component.mmd | Per touched container |
| Dynamic | C4Dynamic | templates/starter-dynamic.mmd | Tricky runtime flow |
| Deployment | C4Deployment | — | Per-environment infra topology |
| Code (L4) | — (IDE/ERD) | — | Almost never |
Reference files: levels -> resources/c4-levels.md; notation + checklist -> resources/notation-and-review-checklist.md; Mermaid syntax + gotchas -> resources/mermaid-c4-syntax.md. Worked examples -> examples/.
Self-check before returning
Common mistakes to avoid
| Red flag / symptom | Fix |
|---|
| Drew all four C4 levels for a two-container change | Draw only what adds value — L1+L2 for most issues; skip Component/Code unless the issue changes that container's internals |
| Modeled a Docker container / message bus as a C4 Container | A C4 Container is a runtime app or data store, not Docker. Model queues/topics as data-store containers or a "via" relationship — never the bus as a hub (see resources/c4-levels.md) |
| Relationship labelled "Uses" with no protocol | Be specific and protocol-label inter-container wires ("Streams events [WebSocket]"), per resources/notation-and-review-checklist.md |
| Invented a service/protocol that isn't in the project | Ground every box in .claude/project.json + the project CLAUDE.md + examples/; if unsure, rg the repos |
Used oklch(...) in UpdateElementStyle or unquoted a comma in a label | Hex/rgba colors only; quote any label with , ( ) — Mermaid C4 gotchas in resources/mermaid-c4-syntax.md |
| Wrote the doc as a loose file at the workspace root | Blocked by protect-sensitive-files.sh; write inside working/YYYY/MM/DD/{slug}/reports/ |
| Verified "renders with zero console errors" and shipped without looking at the picture | Console-clean ≠ readable. Screenshot every diagram and inspect it (step 6); crossing lines / overlapping labels = apply the step-4 fallback |
| Diagram destined for a STATIC surface (artifact, PDF, README image) authored with Mermaid C4 | The readability bar is higher with no pan-zoom crutch: keep the density well under the step-4 gate, or hand-lay the SVG / use a styled flowchart for that surface; keep the .mmd as the diffable source |
What to surface to the user
- The task-dir path and each
.mmd -> rendered .html pair.
- Which C4 levels were drawn and why (the level table from step 2).
- Any project do-not-touch path the change touches and the review it triggers.
- Whether a promotion to the project's architecture docs directory is warranted — and, if it touches a contract, the ASK.
Escalation
- Scope spans >1 repo with a contract change -- surface merge order and delegate coordination back to
@architecture-designer / the orchestrator; a contract edit is an ASK (the project's ASK policy).
- A diagram needs a level/type C4 doesn't provide (state machine, ERD, business process) -- supplement with the right diagram type; don't force it into a C4 view.
- Auto-layout sprawls or overlaps -- fall back to a plain
flowchart with C4 styling conventions (mapping table in resources/mermaid-c4-syntax.md).
Examples
Input: Epic "persist per-order event history for replay" touching the API server + the relational DB.
Process: Scope -> pick L1+L2 (+ one L3 for the API server container) -> inventory boxes against examples/example-container.mmd -> fill starters -> write architecture.md -> render via the project's viewer -> ADR for the append-only-log-vs-snapshot-table choice.
Output: reports/{architecture.md, c4-l1-context.mmd, c4-l2-container.mmd, c4-l3-api-server.mmd, adr-001-event-store.md} + rendered .html.
Input: Document the checkout/payment command path for an incident review.
Process: L1+L2 for frame + one C4Dynamic from templates/starter-dynamic.mmd, modeled on examples/example-dynamic.mmd (auto-numbered Rel steps browser -> API server -> payment gateway -> DB).
Output: reports/c4-dynamic-checkout.mmd + .html, linked from architecture.md section 6.
Failure modes
| Failure | Recovery |
|---|
| Blank render in the viewer | Check console for Unsupported color format: "oklch(...)" — convert UpdateElementStyle colors to hex (resources/mermaid-c4-syntax.md) |
| Parse error on a label | A literal , ( ) : in an unquoted label — double-quote the label; avoid nested " |
| Diagram is unreadable / sprawls | Split into per-area diagrams at the same abstraction level, or fall back to flowchart with C4 styling |
| Reviewer can't tell element types apart | Add a key and ensure every element uses a typed macro (Person/System/Container/Component); rerun the checklist |
| Doc rejected as "over-documented" | Cut to L1+L2; move Component detail to an appendix or drop it |
Related skills
- browser-verification — the render + screenshot + visual-inspection mechanics for step 6.
- summary-templates — format the completion
SUMMARY.md / work summary (user-invoked).
- html-reporting — wrap a multi-section narrative architecture report in the canonical shell.
@architecture-designer agent — primary caller; this skill supplies the C4 grammar for its design step.- A project's own Mermaid viewer skill (if it ships one) renders the
.mmd this skill authors into interactive HTML (step 6).
File layout
c4-architecture-docs/
SKILL.md (this file)
resources/
c4-levels.md (C4 abstractions + 4 levels + supplements; when to use/stop)
notation-and-review-checklist.md (notation rules + diagram review checklist)
mermaid-c4-syntax.md (Mermaid C4 syntax + gotchas + viewer integration)
templates/
architecture-doc-template.md (big-issue narrative doc template)
starter-system-context.mmd (minimal C4Context skeleton)
starter-container.mmd (minimal C4Container skeleton)
starter-component.mmd (minimal C4Component skeleton)
starter-dynamic.mmd (minimal C4Dynamic skeleton)
examples/
example-system-context.mmd (neutral: Orders Platform system context)
example-container.mmd (neutral: SPA + API server + DB containers)
example-dynamic.mmd (neutral: checkout/payment command flow)
How to use
What it does
This skill turns a big issue — an epic, a cross-tier feature, an incident review — into house-consistent C4 architecture documentation: a small set of Mermaid .mmd diagrams plus a short narrative doc, filed in the task directory and rendered for review. It picks the minimum set of abstraction levels that carries the argument, grounds every box in your project's real repos and containers, and enforces the notation rules so the result reads as a map instead of a tangle of boxes and lines.
When to use it
- Someone asks you to "document the architecture" or "draw the system context / container diagram" for a feature.
- A cross-tier epic needs a durable structural picture before implementation starts.
- An incident post-mortem needs a runtime flow drawn as a numbered dynamic view.
- You need to show how the containers listed in
.claude/project.json fit together for one specific change.
When not to use it
- You already have a
.mmd file and only want to see it — use your project's Mermaid viewer skill or the mmdc CLI.
- You only need to record a decision with its trade-offs — write an ADR from the ADR template instead.
- You need a state machine, data model, or business-process view — C4 deliberately omits these; use the right diagram type.
- The change touches one file — a one-line note in the pull request is enough.
How to invoke
Skill(skill: "core:c4-architecture-docs")
Invoke it once you know the scope of the issue and which repositories it spans; the skill reads the rest from your project configuration.
Inputs
- Issue or epic scope — the change to document, as a tracker id or prose — required.
- Affected repositories — which of your project's repos the change spans — required.
- Task directory slug — an existing working directory; created if you leave it out — optional.
- Promotion target — where a settled copy should land in your project docs — optional.
What you get back
Files in the task directory's reports/: architecture.md (narrative, 200 lines or fewer), one .mmd per chosen level, a rendered .html per diagram, and an ADR for each boundary or technology decision. In chat you get the task path, each .mmd → .html pair, which levels were drawn and why, and any do-not-touch path the change overlaps.
Worked example
Skill(skill: "core:c4-architecture-docs")
Request: document the architecture for the epic "persist per-order event
history for replay" — it touches the API server and the relational database.
What happens: the skill scopes the issue, picks L1 + L2 plus one L3 for the
API server, inventories the real containers, fills the starter skeletons,
writes the narrative, renders and visually inspects each diagram, and
records the append-only-log vs snapshot-table choice as an ADR.
You end up with: reports/architecture.md, c4-l1-context.mmd,
c4-l2-container.mmd, c4-l3-api-server.mmd, adr-001-event-store.md,
plus a rendered .html beside each diagram.
Related
- browser-verification — the render, screenshot, and visual-inspection mechanics this skill leans on for review.
- html-reporting — when you want the narrative wrapped in the canonical report shell.
- summary-templates — for formatting the completion summary once the documentation is filed.
@core:architecture-designer — the agent that calls this skill for the C4 grammar during its design step.
