C4 Diagrams Skill

When to Use

• •When you need to generate or update system/containers/components/context diagrams following the C4 model.
• •Trigger: changes under docs/architecture/diagrams or creating new architecture artifacts.

Critical Patterns

• •Keep diagrams as source files in docs/architecture/diagrams using either Mermaid (.mmd/.mmdx) or PlantUML (.puml).
• •Prefer small, focused diagrams per file (one diagram per file). Don't bloat a single file with all C4 levels.
• •Use consistent IDs and naming for elements across diagrams (SYSTEM_xxx, CONTAINER_xxx, COMP_xxx).
• •Version diagrams in git. The skill MUST not modify files without creating clear diffs and a suggested commit message.
• •Always provide both Mermaid and PlantUML variants when a diagram is shared with external stakeholders who may prefer one renderer.

Commands

# Validate Mermaid syntax (requires mmdc installed)
mmdc -i docs/architecture/diagrams/example.mmd -o /tmp/example.png

# Render PlantUML (requires plantuml.jar or plantuml binary)
plantuml -tpng docs/architecture/diagrams/example.puml

# Quick lint: search for .mmd/.puml files changed by git
git diff --name-only --diff-filter=ACMRTUXB HEAD~1..HEAD | rg "docs/architecture/diagrams/.*\.(mmd|puml)"

Templates (assets)

• •assets/mermaid-template.mmd -> minimal C4-style Mermaid snippet
• •assets/plantuml-template.puml -> PlantUML using C4-PlantUML macros
• •assets/README.md -> instructions to render locally

Code Examples

Mermaid (minimal C4-like context diagram):

%% assets/mermaid-template.mmd
flowchart TB
  %% Context - System and external actors
  actor(User):::person
  subgraph SYSTEM [My System]
    APP["Web App"]
  end
  User --> APP

  classDef person fill:#f9f,stroke:#333,stroke-width:1px

PlantUML (using C4-PlantUML):

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
Person(user, "User")
System(webapp, "Web App")
Rel(user, webapp, "uses")
@enduml

Rules for the Agent

• •When asked to update diagrams, propose both Mermaid and PlantUML outputs when possible.
• •Validate diagram syntax and show render command output or error.
• •When creating new diagram files, place them under docs/architecture/diagrams/<level>/<name>.<ext> where <level> is context|container|component|code.
• •Add a short header comment in each generated file with: generation timestamp, generator name (c4-diagrams skill), and git SHA (if available).

Resources

• •Templates: assets/
• •Docs location: docs/architecture/diagrams/