c4-architecture

name	c4-architecture
description	Model and document existing or planned software architectures with the C4 model across System Context, Container, and Component levels plus deployment diagrams, then emit diagrams through a selected renderer. Use when an architect needs audience-appropriate software architecture documentation; use the 'architecture-diagrams' skill for infrastructure topology.
license	CC-BY-4.0 AND MIT
user-invocable	true
compatibility	Generates Mermaid source in any chat context. Preview needs a Mermaid-capable Markdown host. CLI render validation needs Node.js, @mermaid-js/mermaid-cli (mmdc) on PATH plus a Chrome/Chromium runtime; install may need package-manager and network access.
metadata	{"authors":"microsoft/hve-core","spec_version":"1.0","last_updated":"2026-08-13T00:00:00.000Z","content_based_on":"https://c4model.com/; https://mermaid.js.org/"}

C4 Architecture Skill

Goal

Produce audience-appropriate C4 diagrams for existing systems from code or planned systems from requirements. Create new diagrams with the selected renderer, or update existing diagrams when their renderer is supported.

Supported Diagrams

These defaults apply when creating new diagrams. Updates change only what the request targets.

Diagram	Generated by default	User selection	Answers
Level 1: System Context	Yes	Which system when several qualify	Who uses the system and what does it interact with
Level 2: Container	Yes	None	What separately deployable or runnable units make up a system
Level 3: Component	Yes	Which containers when several qualify	What major building blocks sit inside one container
Level 4: Code	On request only	Which component to detail	How one component maps to code structures
Deployment	Offered when evidenced	Opt-in and which environment	Where container instances run in one named environment

Supported Renderers

Read the selected renderer reference in full before generating or modifying diagrams. Apply every relevant rule.

Renderer	Reference	Status
mermaid	references/renderer-mermaid.md	Default

Process

Follow these steps when activating this skill:

1. Ensure the renderer required by the user is available.
2. Inspect the relevant code and documentation to identify architecture elements, boundaries, relationships, and deployment evidence.
3. Read and apply the C4 modelling instructions, including its modelling-uncertainty decision.
4. When creating new diagrams, identify which diagrams, systems, and levels are required. Ask the user to clarify if unclear from context.
5. When updating an existing diagram document, read the complete document first and apply only the requested model delta. Preserve existing nodes, relationships, comments, layout controls, and stable identifiers unless the requested change affects them. Ask the user before removing content whose relevance is uncertain.
6. Before responding, validate each created/edited diagram rule by rule against the selected renderer reference and correct every violation.

Success Criteria

Complete the run when the agreed diagrams are produced or updated, their content is supported by the available evidence, and each diagram passes rule-by-rule source validation against the selected renderer reference. Report renderer-specific validation using the statuses defined by that reference, including the reason when validation was not run.

Constraints

Preserve the agreed system boundary, diagram levels, and renderer. Do not infer architecture, deployment topology, ownership, or relationship technology that the provided evidence does not support. Follow the selected renderer reference in full.

Stop Rules

Stop and ask for clarification when unresolved modelling uncertainty materially affects the diagrams. Stop and report the limitation when required evidence is missing or the requested renderer is unsupported or unavailable. Do not substitute an unrequested renderer or fabricate unsupported elements to complete a diagram.

Final Response

When diagrams are produced or updated, report the diagrams, selected renderer, source-validation result, renderer-specific validation status, assumptions or limitations, and unresolved decisions.

For a clarification stop, state the evidence found, each specific modelling decision blocking the diagrams, the plausible options for each decision, and that no diagrams were produced. Do not report validation status during a clarification stop because no diagram source has been produced yet.

Attribution and licensing

Each source is paraphrased with attribution; none is reproduced verbatim.

• C4 model concepts and abstractions (System Context, Container, Component, Code) are based on the C4 Model by Simon Brown, licensed under CC BY 4.0.
• Mermaid syntax conventions in the Mermaid renderer are derived from the Mermaid documentation, licensed under MIT.

Derived and original material share files here, so the boundary is marked inline in each file rather than split by file. The frontmatter expression is the conjunction of every license present in the package.

Path	License	Origin
references/renderer-mermaid.md	CC-BY-4.0 AND MIT	Repository renderer rules, paraphrased C4 concepts, and MIT-derived Mermaid syntax conventions
references/c4-modelling-instructions.md	CC-BY-4.0	Repository modelling rules with paraphrased C4 concepts
SKILL.md and remaining package content	CC-BY-4.0	Repository-original with paraphrased C4 concepts