vsouto.com

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.

Claude Code/plugin marketplace add vsouto/c4x
then/plugin install c4x@vsouto
Any agentnpx skills add vsouto/c4x
C4 container diagram of a recommendation platform in its Q1 2027 phase: a new Vector DB marked NEW, Candidate Retrieval marked CHANGED, and a removed batch relation struck through in red.
Containers view of the bundled example, Q1 2027 phase: new, changed and removed parts shown as a diff.
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.
A c4x brief in an editor: an element with parent, team, SLO, risk and ticket; two relations marked async and sync with a latency budget; a flow with per-step milliseconds; and a Q1 2027 change set.

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.

Container diagram with a ticket badge on each container, such as REC-214 In Progress and MLP-91 In Review, using Linear status names.
Ticket IDs with their tracker status. With a Linear or Jira MCP connected the status is fetched live; it is never guessed.

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.

LikeC4 rendering of the Q1 2027 containers view: Vector DB in green, Candidate Retrieval in amber, the rest in blue inside the platform boundary.

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.

Dynamic view of the request that opens the home screen, with step 3 highlighted, above a list of seven steps whose synchronous path totals 65 of 80 milliseconds.
Opening the home screen: 65 ms of an 80 ms budget on the critical path.

Deployment

05

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

Deployment view: an AWS region containing an EKS cluster with three services and their pod counts, a Databricks workspace, and managed MSK, ElastiCache and S3.

How the skill works

06

  1. Read the input

    A brief, meeting notes, an RFC, an existing .c4 or .dsl, or the repository itself.

  2. Draft the brief

    Gaps become ? plus an open question. You confirm before anything is generated.

  3. Lint

    17 rules in three levels: errors that block, warnings that break C4 practice, suggestions.

  4. Generate and validate

    LikeC4 files, then npx likec4 validate. A model that doesn’t parse isn’t handed over.

  5. 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 skillc4x
InputFree-text prompt or codebaseReviewable brief with a fixed grammar
OutputMermaid, PlantUML or LikeC4LikeC4 or Structurizr, valid C4 with a strict export
Ownership, SLOs, riskNot modelledTags and metadata on every element
TicketsNot modelledLinear or Jira IDs, live status when connected
Planned changesSeparate diagramsDated phases as a diff from one model
LatencyNot modelledPer-step budgets checked against SLOs
ValidationUsually noneBrief 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.

Installnpx skills add vsouto/c4x