C4 Architect

C4 Architect

Generate C4 model diagrams for the current project. Output: Mermaid .md files in docs/architecture/.

What to generate

| Level | File | When to generate | What it shows | |-------|------|-----------------|---------------| | C1 Context | c4-context.md | New project, new external dependency, new actor | System boundary, external systems, users | | C2 Container | c4-container.md | New service/app/DB/queue added | Apps, databases, message queues, their relationships | | C3 Component | c4-component-[name].md | New module/service layer, significant refactor | Internal components of a single container, their dependencies |

Invocation modes

| Argument | Behavior | |----------|----------| | context | Regenerate C1 only | | container | Regenerate C2 only | | component [name] | Regenerate C3 for named container | | all | Regenerate all levels | | refresh | Diff current code against existing diagrams, update only what changed | | (none) | Smart mode — detect what changed since last generation, update those |

Workflow

1. Read existing diagrams in docs/architecture/ (if any)
2. Scan the project to build the architecture model:

• Package.json / Gemfile / pyproject.toml → tech stack
• Directory structure → containers and components
• API routes, DB schemas, external service calls → relationships
• Environment variables → external dependencies
• Existing CLAUDE.md / README → documented architecture

1. Diff against existing diagrams — only regenerate what changed
2. Generate Mermaid using C4 notation (see reference/mermaid-c4.md)
3. Write files to docs/architecture/
4. Report what changed and why — flag any arrows that were added/removed

Diagram format

Each file follows this template:

# C[N] [Level Name] — [Project Name]

> Auto-generated by c4-architect. Last updated: YYYY-MM-DD
> Manual edits will be overwritten on next refresh.

```mermaid
C4Context
  title System Context — [Project]
  ...
`` `

## What changed
- [bullet list of changes since last generation, or "Initial generation"]

Rules

• Never remove a node without confirming it's actually gone from the codebase
• Preserve manual annotations — if a diagram has %% MANUAL: comments, keep them
• Flag uncertainty — if you can't determine a relationship direction, add %% UNCERTAIN: comment
• One component diagram per container — don't combine multiple containers in one C3
• Keep diagrams readable — max ~15 nodes per diagram. Split if larger.
• Use docs/architecture/ relative to project root. Create if missing.
• Include a docs/architecture/README.md index linking all diagrams

Post-commit hook behavior

When triggered automatically after a commit (via hook):

1. Check if the commit touches structural files (new dirs, schema files, route files, package deps, docker/infra)
2. If yes → run refresh mode silently
3. If the refresh produces changes → commit them as docs: update C4 diagrams
4. If no structural changes → skip silently

Reference

See reference/mermaid-c4.md for Mermaid C4 syntax and examples.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lucface
• Source: Lucface/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.