enterprise-architecture — a Claude Code Agent Skill

A unified enterprise & software architecture skill for Claude Code, grounded in four open-source standards instead of one. It helps Claude produce architecture work the way the standards intend it: diagrams as code, documentation as code, decisions as records, and one traceable model underneath.

🌐 Live site & eval examples: https://gauravs19.github.io/enterprise-architecture-skill/

Contents

• Why this exists
• The theory — frameworks in practice
• The mental model — four frameworks, four altitudes
• The four frameworks
• The four modes
• Traceability — one model under everything
• Install
• Usage
• The consistency linter
• Eval results
• Repository layout
• License

Why this exists

The open-source ecosystem has excellent single-purpose skills — C4+ArchiMate plugins, arc42 toolkits, ADR generators — but none unify all four frameworks, and none cover TOGAF or architecture review. This skill fills that gap: one skill that picks the right framework at the right altitude, produces everything as code, and keeps a single traceable model under every diagram, doc, and decision.

The theory — frameworks in practice

There's a large gap between how EA frameworks are marketed and how they're used. Almost no organization runs TOGAF or Zachman "by the book" — full-ceremony adoption usually collapses under its own weight. What survives contact with reality is selective borrowing:

Where frameworks genuinely earn their keep: M&A integration (two of everything — what to kill?), cloud migration programs (baseline/target/gap keeps multi-year work coherent), vendor/platform decisions (ADRs make them defensible two years later), regulatory traceability (requirement → capability → app → deployment), and fighting shadow-IT sprawl (a maintained app landscape is the only way anyone knows what exists).

Frameworks are scaffolding, not the building — the value is a handful of living artifacts (a capability map, an application landscape, a decision log, a roadmap), not framework compliance.

→ Full write-up with four worked case studies and the six EA anti-patterns: Frameworks in practice

The mental model — four frameworks, four altitudes

These frameworks are not competitors — they answer different questions. Knowing which one fits the question is most of the skill.

• C4 zooms into one system.
• ArchiMate zooms out to the enterprise.
• TOGAF is the method for changing it.
• arc42 / ADR is how you narrate it.

They compose: an arc42 doc embeds C4 diagrams and links ADRs; a TOGAF engagement produces ArchiMate models and ADRs as deliverables.

The four frameworks

Each framework is explained in full — origin, structure, worked examples, what practitioners actually keep — in the frameworks-in-practice guide. For "which framework should I use?" questions, the skill itself loads references/choosing-frameworks.md.

The four modes

The skill routes any architectural request to one of four modes — you don't have to name a framework.

Mode 3 grades against ISO/IEC 25010 quality attributes (performance, security, reliability, maintainability, …) plus EA principles, and returns findings categorized Critical / Major / Minor / Suggestion, each with evidence and a concrete remediation, then a verdict (Approved / Approved-with-changes / Needs-revision) — not personal taste.

→ Review rubric: references/review-rubric.md

Traceability — one model under everything

Give every architectural element a stable, human-readable ID and reuse it across diagrams, docs, and ADRs. This is what turns a pile of pictures into an actual model.

• ID scheme (URN-style): ea:{org}:{system}:{kind}:{name}
  • e.g. ea:acme:checkout:container:payment-api, ea:acme:enterprise:capability:billing
  • kind ∈ person, system, external, container, component, capability, app, node, decision …
• When a repo exists, persist these in an architecture/ folder (one file per significant artifact, or a Structurizr workspace as the model-of-record) so they're diff-able and greppable, and reference the same ID from the arc42 doc and the ADRs.
• Before inventing a new element, check whether it already exists under another name and reuse the ID. Two names for one thing is the most common EA documentation defect.

Install

Option A — clone into your Claude Code skills directory:

git clone https://github.com/<you>/enterprise-architecture-skill \
  ~/.claude/skills/enterprise-architecture

Option B — plugin marketplace (no clone needed). In Claude Code:

/plugin marketplace add gauravs19/enterprise-architecture-skill
/plugin install enterprise-architecture@gauravs19-skills

Option C — download the packaged skill: grab enterprise-architecture.skill (or from the latest release) and install it through Claude Code.

Claude Code discovers it automatically — the skill folder must be named enterprise-architecture (that's the skill's invocation name); the repo it comes from can be named anything.

Usage

Just ask in plain language — the skill triggers itself and picks the framework + mode:

draw the container diagram for this checkout service
write an ADR for choosing Kafka over RabbitMQ for our order events
review this architecture — is it sound for 50k daily users?
map our business capabilities to the apps that realize them
create a Structurizr workspace for the payments platform
document this service with arc42 at ESSENTIAL detail

Each response states which framework and view it's producing, so you learn the map as you go — part of the skill's job is to make you fluent in the frameworks, not just hand you artifacts.

The consistency linter

scripts/ea_lint.py checks the connective tissue between artifacts (it doesn't validate diagram syntax — renderers do that). It flags:

• EA IDs referenced but never defined
• ADR numbering gaps, missing Status, and dangling "superseded by ADR-XXXX"
• accepted ADRs not linked from any doc
• vague (unmeasurable) quality goals
• empty arc42 decision sections
• orphan diagram source files never referenced from a doc

python scripts/ea_lint.py path/to/docs/architecture
python scripts/ea_lint.py path/to/docs/architecture --strict   # exit 1 on Major+ findings

Findings are grouped by severity. It's advisory — it reports, it doesn't rewrite your intent.

Eval results

The skill was tested with the skill-creator eval loop — each prompt run with the skill and as a baseline, graded against objective assertions:

The skill's main value is forcing the right artifact in the right format. Because installed skills are globally discoverable, the measured gap is a conservative lower bound. The actual example outputs are in docs/examples/ and rendered on the live site.

Repository layout

enterprise-architecture/
├── SKILL.md                       # router: pick framework + mode, shared workflow
├── references/
│   ├── c4-structurizr.md          # C4 levels, Structurizr DSL, Mermaid/PlantUML
│   ├── archimate.md               # layers, element catalog, relationships, viewpoints
│   ├── togaf-adm.md               # 10 ADM phases, deliverables, TIME portfolio model
│   ├── arc42.md                   # 12 sections + LEAN/ESSENTIAL/THOROUGH detail knob
│   ├── adr-madr.md                # ADR & MADR templates and conventions
│   ├── review-rubric.md           # quality attributes, severity scheme, verdict format
│   └── choosing-frameworks.md     # "which framework?" — verdicts, pay-off situations, anti-patterns
├── assets/templates/              # ADR, arc42 section, Structurizr workspace starters
├── scripts/
│   └── ea_lint.py                 # cross-artifact consistency checker
├── evals/                         # test prompts + assertions
└── docs/                          # GitHub Pages site + example outputs

License

MIT — see LICENSE.