{
  "markdown": "# c4-model\n\nA [Claude Code](https://claude.com/claude-code) skill for producing [C4 architecture diagrams](https://c4model.com) (Simon Brown's model), interactively.\n\n[![CI](https://github.com/cheriftj/c4-model-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/cheriftj/c4-model-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n## How it works\n\nWhen you ask for an architecture diagram (or run `/c4m:auto`), the skill first figures out what you're actually doing. Designing a new system from a vague idea is a different job from retro-documenting an existing codebase, which is different again from reviewing someone else's diagram or updating one you already have.\n\nOnce the mode is clear, it runs the matching workflow: a structured dialogue, batches of no more than five questions at a time, with an explicit validation checkpoint at every level. Nothing gets written to disk until you say it's final.\n\nIf you already know which mode you want, a dedicated slash command skips the detection step (`/c4m:design`, `/c4m:code`, `/c4m:prose`, `/c4m:review`, `/c4m:update`). Or invoke `/c4m:auto` and let the router pick. See [The 5 modes](#the-5-modes) below.\n\nBy default the output is one Markdown document per C4 level (Context, Container, optionally Component) with the diagram embedded as Mermaid. Format and destination are negotiated at the start: Structurizr DSL, PlantUML, or an MCP destination (Notion, Linear, Google Drive) are all on the table.\n\nSee [`skills/c4-model/examples/`](./skills/c4-model/examples/) for a filled-out Context + Container pair built from Simon Brown's canonical Internet Banking System.\n\n## Installation\n\n### Claude Code plugin marketplace\n\n```bash\n/plugin marketplace add cheriftj/c4-model-skill\n/plugin install c4m@c4-model-skill\n```\n\n### Copy into a single project\n\n```bash\ncp -r path/to/this-repo/skills/c4-model /your/project/.claude/skills/\n```\n\nClaude Code auto-discovers skills under `.claude/skills/` in the current project.\n\n### Install for all your projects\n\n```bash\ncp -r path/to/this-repo/skills/c4-model ~/.claude/skills/\n```\n\n## The 5 modes\n\nEach mode has a dedicated slash command. Claude Code namespaces commands under their plugin, so every command is prefixed with `/c4m:`. Use the auto variant if you want the router to pick the mode; use the mode-specific variants to skip detection.\n\n| Mode | Slash command | Fires on | Flow |\n|---|---|---|---|\n| **Design** | `/c4m:design` | Vague idea, no code | Framing → Context → Container → optional Component → finalization |\n| **Document-code** | `/c4m:code` | You point at a repo | Quick framing → scan (delegates to an Explore sub-agent on large repos) → review → dialogue → deliver |\n| **Document-prose** | `/c4m:prose` | You paste a README / ADR / spec | Extraction → gap-filling dialogue → deliver |\n| **Review** | `/c4m:review` | You paste a diagram + *\"is this good?\"* or *\"explain this\"* | Checklist critique (grouped by severity) or structured narration |\n| **Update** | `/c4m:update` | You have a C4 + *\"add / remove / change X\"* | Read, clarify the diff, update every affected level |\n| *(any / unsure)* | `/c4m:auto` | Any of the above | Detects the mode from what follows the invocation, then routes |\n\nSupporting diagrams (System Landscape, C4Deployment, C4Dynamic) are offered on explicit request from within any mode.\n\n## Example conversations\n\n### Design mode (via `/c4m:design` or a natural prompt)\n\n```text\nYou:   /c4m:design I'm building an event-sourced order management system.\n\nClaude: Before we draft anything, a few quick questions (max 5):\n        1. System name + one-line business intent?\n        2. Audience (tech team, stakeholder, onboarding)?\n        3. Which levels: Context only, Context + Container, deeper?\n        4. Output format? Default is Mermaid + Markdown; alternatives: Structurizr DSL, PlantUML.\n        5. Destination? Default docs/architecture/, or a Notion/Linear/Drive MCP if available.\n\nYou:   Orders MS, greenfield. Tech team audience. Context + Container. Defaults.\n\nClaude: Got it. For Context first: who interacts with this system, and what external systems does it depend on?\n\n[... dialogue continues, diagram emerges, user validates each level ...]\n\nYou:   Finalized, looks good.\n\nClaude: Writing docs/architecture/01-context.md and docs/architecture/02-container.md now.\n```\n\nWithout the slash command, the same flow is triggered by any architecture-design request (e.g. *\"help me design an order management system\"*) — the skill's router detects Design mode from the signal.\n\n### Review mode (via `/c4m:review`)\n\n```text\nYou:   /c4m:review\n       ```mermaid\n       C4Container\n           title My API\n           Container(api, \"API\", \"Node\")\n           ContainerDb(db, \"DB\")\n           Rel(api, db, \"Uses\")\n       ```\n\nClaude: 3 issues, grouped by severity.\n\n        BLOCKING\n        - Missing title scope (\"My API\" doesn't say which system).\n        - Container(db, \"DB\") has no technology — mandatory on every Container.\n        - Rel(api, db, \"Uses\") is a bare verb — state the intent and the protocol,\n          e.g. \"Reads and writes orders to\" with protocol \"JDBC\".\n\n        IMPORTANT\n        - No legend, no scope/description on the API.\n\n        NICE-TO-HAVE\n        - Consider a System_Boundary around the API + DB for visual grouping.\n\n        Want me to apply these corrections? That would switch us to /c4m:update.\n```\n\nOther modes (`/c4m:code`, `/c4m:prose`, `/c4m:update`) follow the same shape: explicit slash command, a short framing dialogue, then the deliverable.\n\n## What makes it honest\n\n- **Mode detection first.** Don't generate if we don't know what you want.\n- **Simon Brown's golden rule.** Context + Container are enough for most teams; Component only on explicit request.\n- **One Markdown document per level.** Never a bare Mermaid block.\n- **Relation labels state intent.** *\"Uses\"*, *\"Calls\"*, *\"Reads\"* are banned on their own.\n- **Technology is mandatory** on every Container and Component.\n- **Assumptions stay explicit.** Inferences never slip silently into the diagram.\n- **Grounded in authority.** The Mermaid syntax reference is rebuilt from [mermaid.js.org](https://mermaid.js.org/syntax/c4.html); the review checklist from [c4model.com](https://c4model.com/diagrams/checklist). Editorial additions are separated from sourced content.\n\n## Contributing\n\nBug fixes, wording improvements, and new modes are all welcome. For anything larger than a typo, open an issue first so we can agree on scope before code is written. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the editorial invariants, the PR checklist, and the release process. This project follows the [Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md).\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n\n## Credits\n\nThe [C4 model](https://c4model.com) is by [Simon Brown](https://simonbrown.je/); the example deliverables in this repo use his canonical [Internet Banking System](https://c4model.com/diagrams). The Mermaid C4 syntax comes from the [Mermaid](https://mermaid.js.org/) project.\n",
  "bytes": 7123,
  "sha": "aa9dc8aaa4dfe91727e91f6f4ec840251c8e10250d58edea3c132b339f7068ea",
  "repo_slug": "cheriftj/c4-model-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_cheriftj_c4_model_skill_c4m_fa5529bc/readme"
}