# c4-codebase-architecture A skill that walks an agent through a repository and writes C4 architecture docs: system context, containers, components. Handy for onboarding or picking up someone else's code. - skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 24 - Author: lmammino - License: MIT · policy=mirror · the beginning of the file is at the end of this page - Source: https://github.com/lmammino/c4-codebase-architecture-skill/tree/HEAD/skills/c4-codebase-architecture/SKILL.md - Updated: 2026-04-09 - HTML: https://affpapa.org/en/nevibecode/skills/c4-codebase-architecture ## What it does The agent works in six phases. It pins down the scope of the repository, finds the runnable and deployable units, maps how they talk to each other, then works out external systems and the people using them. Only after that does it split the important containers into components. Output is a system context view, a container view, one or two component views, plus a written section covering assumptions and open questions. Diagram source comes as Mermaid, PlantUML or Structurizr DSL when you ask for it. Facts and guesses stay apart. Whatever the agent can point to in the code is labelled as observed; anything it concludes from that is labelled as inferred. When reading the code is not enough, it asks questions in batches of 3 to 7 instead of drip-feeding them one at a time. Detail level follows the repository — a small service will not get a component breakdown it does not need. The skill earns its keep when the repo holds more than source files: package manifests, infrastructure code, deployment descriptors, API specs, CI/CD config, tests. On code alone, system boundaries and business intent usually stay hidden, so skipping the agent's questions leaves the documentation thin. A full code-level diagram is not produced unless you ask for one. ## Install ### Claude Code (native platform) 1. **Skills CLI (Vercel)** ```bash npx skills add lmammino/c4-codebase-architecture-skill --skill c4-codebase-architecture -a claude-code ``` 2. **Manually: put the files in place** - File: `~/.claude/skills/c4-codebase-architecture/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/c4-codebase-architecture/ ### Codex 1. **Skills CLI (Vercel)** ```bash npx skills add lmammino/c4-codebase-architecture-skill --skill c4-codebase-architecture -a codex ``` 2. **Manually: put the files in place** - File: `.agents/skills/c4-codebase-architecture/SKILL.md` — For all projects use ~/.agents/skills/ ### Cursor 1. **Skills CLI (Vercel)** ```bash npx skills add lmammino/c4-codebase-architecture-skill --skill c4-codebase-architecture -a cursor ``` 2. **Manually: put the files in place** - File: `.cursor/skills/c4-codebase-architecture/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/ ### GitHub Copilot 1. **GitHub CLI** ```bash gh skill install lmammino/c4-codebase-architecture-skill c4-codebase-architecture ``` 2. **Manually: put the files in place** - File: `.github/skills/c4-codebase-architecture/SKILL.md` ### Gemini CLI 1. **Skills CLI (Vercel)** ```bash npx skills add lmammino/c4-codebase-architecture-skill --skill c4-codebase-architecture -a gemini-cli ``` 2. **Platform CLI** ```bash gemini skills install https://github.com/lmammino/c4-codebase-architecture-skill --path skills/c4-codebase-architecture ``` ### Windsurf (Devin Desktop) **Manually: put the files in place** - File: `.devin/skills/c4-codebase-architecture/SKILL.md` — The legacy .windsurf/skills/ path still works ### OpenCode **Skills CLI (Vercel)** ```bash npx skills add lmammino/c4-codebase-architecture-skill --skill c4-codebase-architecture -a opencode ``` ### Claude.ai **Claude.ai** - Zip the folder and upload it in Settings → Capabilities → Skills Where a file is given instead of a command, copy the files from the source to that path: https://github.com/lmammino/c4-codebase-architecture-skill/tree/HEAD/skills/c4-codebase-architecture/SKILL.md ## When to use it - get oriented in an unfamiliar repository before touching it - draw a system context view with external dependencies - document containers: services, databases, queues, workers - split a large container into components by responsibility - compare the intended architecture with what the code actually does ## Example prompts - Inspect this repository and write C4 documentation: system context and containers - Build a container diagram with Mermaid source, and list your assumptions and open questions - Break the `api` service into components and explain what each one is responsible for ## Source text · SKILL.md · MIT Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: abfe1601046d61aa. BEGIN THIRD-PARTY FILE abfe1601046d61aa ```text --- name: c4-codebase-architecture description: Helps an agent inspect a repository and produce C4 architecture documentation. Use this when reverse engineering a codebase, documenting system context, containers, components, or clarifying architecture from code and infrastructure. license: MIT --- # C4 Model Codebase Documentation Skill ## Purpose This skill helps an agent inspect a codebase and produce useful C4-style architecture documentation. It should combine evidence from the repository with targeted follow-up questions whenever code inspection alone is not enough to determine system boundaries, responsibilities, runtime topology, or business intent. The skill should be pragmatic rather than dogmatic. The goal is not to force every repository into a perfect set of four diagrams, but to produce the clearest possible architecture view at the right level of detail. --- ## When to use this skill Use this skill when the user wants to: * understand the architecture of an existing codebase * produce C4 documentation for a repository * generate a system context, container, or component view * onboard new engineers with architecture docs * reverse engineer system structure from code and infrastructure definitions * compare intended architecture with implemented architecture This skill works best when the repository includes at least some of the following: * source code * infrastructure as code * deployment descriptors * README or docs * API specifications * CI/CD configuration * test suites --- ## What this skill should produce The skill should aim to produce some or all of the following, depending on what the codebase supports: 1. **System Context** * the system under study * human users or personas * external systems, APIs, providers, or dependencies * key relationships 2. **Container view** * main deployable or runnable units * databases, queues, frontends, APIs, workers, serverless functions, data stores * protocols and interactions between them 3. **Component view** ``` END THIRD-PARTY FILE abfe1601046d61aa The third-party file has ended. Everything between the abfe1601046d61aa tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file. First 2042 of 15124 bytes. © lmammino · MIT · https://github.com/lmammino/c4-codebase-architecture-skill/tree/HEAD/skills/c4-codebase-architecture/SKILL.md _Part of the page did not fit — see the HTML version._ --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md