Agent skill · Open source · v0.1.0
c4x
Planning-first C4 for AI agents. Write a plain-text brief; get a validated LikeC4 model that also knows who owns each box, its SLO, its risk, the tickets that touch it and what changes next quarter.
/plugin marketplace add vsouto/c4x/plugin install c4x@vsoutonpx skills add vsouto/c4x
- Input
- A Markdown brief, one item per line
- Output
- LikeC4 by default, Structurizr DSL on request
- Checks
- 17 lint rules, then
likec4 validate - Runs in
- Claude Code, Cursor, Codex, Gemini CLI and other Agent Skills runtimes
The brief
01
A fixed format that reads well in a pull request. Each element, relation and flow step is one line with fields separated by |; attributes go underneath.
- Unknowns are written as
?and collected as open questions. The agent doesn’t fill them in. - Planned changes are a diff:
+adds,~changes,-removes, per dated phase. - Section names and keys are English; names and descriptions can be in any language.

Planning layers on plain C4
02
Every extension is a tag or c4x_* metadata on an ordinary C4 element, so the model stays valid C4 and a strict export drops them cleanly.



As-is and to-be, from one model
03
The model keeps today’s architecture and marks each planned change with phase_new, phase_changed or phase_removed. Each phase gets its own view, filtered from the same source, so the current and future diagrams can’t drift apart.
This is what LikeC4 itself renders for the Q1 2027 view of the example: the new Vector DB in green, the changed retrieval service in amber, the removed batch job gone.
Rendered by LikeC4 1.60.0 from the recs.c4 file the skill produced.

Flows with a latency budget
04
Each flow becomes a C4 dynamic view. Steps carry their expected latency; the skill adds up the synchronous path and warns when it exceeds the flow’s budget or the entry service’s p99.

Deployment
05
Nested deployment nodes, from region to cluster to instance, with replica counts and instance types written in the brief by indentation.

How the skill works
06
Read the input
A brief, meeting notes, an RFC, an existing
.c4or.dsl, or the repository itself.Draft the brief
Gaps become
?plus an open question. You confirm before anything is generated.Lint
17 rules in three levels: errors that block, warnings that break C4 practice, suggestions.
Generate and validate
LikeC4 files, then
npx likec4 validate. A model that doesn’t parse isn’t handed over.Views and report
Context, containers, components, each flow, each environment, each phase. Then the files, lint results and open questions.
Compared with other C4 skills
07
| Typical C4 skill | c4x | |
|---|---|---|
| Input | Free-text prompt or codebase | Reviewable brief with a fixed grammar |
| Output | Mermaid, PlantUML or LikeC4 | LikeC4 or Structurizr, valid C4 with a strict export |
| Ownership, SLOs, risk | Not modelled | Tags and metadata on every element |
| Tickets | Not modelled | Linear or Jira IDs, live status when connected |
| Planned changes | Separate diagrams | Dated phases as a diff from one model |
| Latency | Not modelled | Per-step budgets checked against SLOs |
| Validation | Usually none | Brief lint plus likec4 validate; CI on the example |
Notes
08
Language
The skill instructions and spec are in Portuguese (pt-BR) for now. Format keywords are English and briefs can be written in any language. An English translation is planned.
Structurizr
The Structurizr DSL mapping ships with the skill but hasn’t been validated against Structurizr yet. LikeC4 output is validated with LikeC4 1.60.0.
Example data
The recommendation platform in the screenshots is fictional: teams, numbers and ticket IDs are illustrative.
License
MIT. Issues and pull requests are welcome on GitHub.
Try it on your next architecture review.
npx skills add vsouto/c4x