C4 diagrams: Claude Code skill for architecture diagrams

The C4 diagram skill is a Claude Code skill, built at AR Labs, for drawing software architecture diagrams that follow the C4 model, Simon Brown's method of describing software at four zoom levels: system context, containers (separately running applications and data stores), components and code. The C4 model is Simon Brown's; the skill, its colour scheme and its rules for applying the model are ours, and architecture documentation with C4 describes the practice it serves. Agents must load it before creating or editing any Mermaid diagram that shows system architecture, containers, components or deployment, even when nobody says "C4" and even for a one-line edit, because small edits made from memory are where the rules get broken: one such edit added a two-way arrow the rules forbid. Other skills, such as Comprehend, hand their diagrams to a dedicated diagram agent that follows this skill.

How it works

There are two authoring paths. Both produce Mermaid, the text-based diagram format that renders in web pages and markdown.

flowchart LR
  B["Diagram brief"] --> Q{"Maintained architecture doc?"}
  Q -->|"Yes"| D["Write Structurizr DSL"]
  D --> V["Validate"]
  V --> E["Export to Mermaid"]
  Q -->|"No"| M["Write Mermaid directly"]
  E --> C["Review checklist"]
  M --> C

• Structurizr DSL for design documents and any architecture that will be maintained. The model is written in Structurizr's text language, validated through a Structurizr MCP server (a tool server the agent calls), then exported to Mermaid. Validation catches missing descriptions, unlabelled relationships and wrong element types before they reach a picture.
• Direct Mermaid for diagrams inside decision records and one-off explanations, with the same rules applied by hand.

The skill also records the four places a diagram renders (the website's React component, markdown documents, a zoom-and-pan viewer, and standalone HTML pages) and the configuration each needs. The website component applies the theme itself, so a diagram defined for the site carries no theme block; a markdown diagram must carry one or it falls back to Mermaid's default blue theme.

The judgement it encodes

No two-way arrows. A bidirectional arrow, or a single arrow labelled "sends and receives", hides what flows in each direction. A two-way connection such as a WebSocket is drawn as two arrows, each with its own label.

Every line says what flows and how. "Uses" carries no information. Labels read as sentences in the direction of the arrow, and lines between containers name the protocol.

Every element has a name, a type, a technology and a responsibility. Descriptions state what an element is responsible for, not how it is built.

One zoom level per diagram. A container and a component never appear as peers.

Data flow must be true. Static files do not call backends; the diagram shows the real route, such as browser to proxy to backend.

A legend, always. It is the most common omission.

Colour shows role, not type. Colours come from a fixed palette of five: mint for the diagram's focus, yellow for infrastructure and data stores the team controls, purple for third-party systems, white for de-emphasised actors, grey for deprecated parts. The same element can change colour between diagrams: a person is mint on a context diagram, where people are the focus, and white on a container diagram, where the containers are. Every node gets an explicit fill (no white on white), and subgraphs get tinted backgrounds.

Rendering pitfalls are written down. Markdown bold renders as literal asterisks inside Mermaid labels, and in Mermaid version 11 sequence diagrams the font-size settings and actor colours set through the theme are silently ignored. The skill records each pitfall with its working alternative, such as applying actor colours with a small script after the diagram renders.

A mandatory review checklist of eighteen questions covers these rules before any diagram counts as done. One known conflict is written into the skill rather than resolved quietly: client-facing proposal diagrams should stay technology-neutral, while the C4 rules require technology on every container. The skill keeps the client diagram neutral and carries the technology on an internal twin.

What exists today

We use the skill for our design documents, architecture decision records and website diagrams, including the container and component diagrams of our sales voice agent.

Example

Illustrative example. A container diagram for a small voice agent, in markdown form, shown here without its theme block and colour styles. Note the two WebRTC arrows: the connection is two-way, so each direction gets its own arrow and label.

flowchart LR
  U["Visitor [Person]"]
  subgraph SYS ["VOICE AGENT"]
    W["Web client [Container: React] captures audio, shows transcript"]
    B["Voice backend [Container: Python, Pipecat] runs the conversation"]
  end
  L["Language model API [External system]"]
  U -->|"Speaks to, in browser"| W
  W -->|"Streams audio via WebRTC"| B
  B -->|"Streams speech via WebRTC"| W
  B -->|"Sends prompts via HTTPS"| L

Container diagram for a voice agent. In the themed version, a legend sits under the diagram:

Colour	Meaning
Mint	Containers the team builds
White	People
Purple	External systems