structurizr-c4-skill

An Agent Skill to generate, validate and view C4 software architecture diagrams as code with the Structurizr DSL — the C4 reference implementation — locally and without Docker.

It ships a self-contained CLI (strz) that builds and drives Structurizr vNext: a live local viewer, DSL validation/inspection, and export to Mermaid / PlantUML / C4-PlantUML.

Why

• Diagrams as code: one model, many views, versioned in git.
• No Docker: runs on a plain JVM (Structurizr vNext compiled from source).
• Agent-friendly: the agent writes DSL, validates it, exports and serves it through a single CLI.

Requirements

• Java 21+
• git
• (to install the skill) Node.js — used via npx skills

Install

Install the skill into your agent (Claude Code, Cursor, Codex, Zed, …):

# all skills in this repo
npx skills add Tacuchi/structurizr-c4-skill

# or just this skill, globally
npx skills add Tacuchi/structurizr-c4-skill --skill structurizr-c4 -g

Then build Structurizr once (no Docker):

bash ~/.agents/skills/structurizr-c4/scripts/strz.sh setup

Optionally expose the CLI as strz on your PATH:

ln -sf ~/.agents/skills/structurizr-c4/scripts/strz.sh ~/.local/bin/strz

Usage

strz setup                     # one-time build (no Docker)
strz start docs/architecture   # start the local viewer
strz open                      # open http://localhost:8080
strz validate docs/architecture
strz export docs/architecture mermaid
strz restart docs/architecture
strz stop

dir defaults to docs/architecture (or the current directory). Port is configurable with STRZ_PORT.

Repository layout

structurizr-c4-skill/
└── skills/
    └── structurizr-c4/
        ├── SKILL.md
        ├── scripts/strz.sh          # self-contained CLI (source of truth)
        ├── references/dsl-reference.md
        └── examples/workspace.dsl

License

MIT — see LICENSE.

Credits

The C4 model and Structurizr are by Simon Brown.