Generate C4 Architecture Documentation

This skill generates comprehensive C4 architecture documentation for an existing repository using a bottom-up analysis approach, following the official C4 model (Context, Container, Component, Code). It coordinates four specialized agents - c4-code, c4-component, c4-container, and c4-context - that work through four phases. Phase 1 discovers every subdirectory in the repository, sorts them deepest-first, filters out non-code directories such as node_modules, .git, build, and dist, then analyzes each one bottom-up to produce code-level documentation covering function signatures, classes, dependencies, and relationships. Phase 2 synthesizes the code-level files into logical components grouped by domain, technical, or organizational boundaries, documenting each component's purpose, software features, interfaces, and dependencies, plus a master component index with a Mermaid relationship diagram. Phase 3 maps components to deployment containers by searching for Dockerfiles, Kubernetes manifests, Docker Compose files, Terraform/CloudFormation configs, and CI/CD pipeline definitions, then documents each container's purpose, technology, and infrastructure, generating an OpenAPI 3.1+ specification for every container API. Phase 4 produces context-level documentation aimed at non-technical stakeholders: a system overview, personas for both human and programmatic users, system features, step-by-step user journeys, and a catalog of external systems and dependencies, tied together with a C4Context Mermaid diagram. All output is written to a new C4-Documentation/ directory in the repository root. The skill notes that per the C4 model itself, most teams only need the system context and container diagrams - it generates all four levels for completeness, but teams can choose which levels to actually use.

Use this skill when documenting the architecture of an existing repository or codebase for teams that need C4-style documentation spanning code, component, container, and context levels. It is explicitly out of scope for anything unrelated to C4 architecture documentation, or for a different domain or tool outside that scope.

Inputs are configurable: target_directory (defaults to the current repository root), exclude_patterns (defaults to node_modules, .git, build, dist, etc.), output_directory (defaults to C4-Documentation/), include_tests (whether to analyze test files for context, default true), and api_format (defaults to openapi). Outputs are a structured C4-Documentation/ directory: one c4-code-.md file per analyzed directory, one c4-component-.md file per identified component plus a master c4-component.md index, a single c4-container.md with OpenAPI/Swagger specs under an apis/ subfolder, and a single c4-context.md with personas, user journeys, and a system context diagram. The skill is invoked as a slash command:

/c4-architecture:c4-architecture

The workflow searches the target repository for existing artifacts to ground its output: README files, architecture and requirements documents, and test files. For container-level synthesis it specifically searches deployment and infrastructure definitions - Dockerfiles, Kubernetes manifests, Docker Compose files, Terraform/CloudFormation configs, cloud service definitions such as AWS Lambda or Azure Functions, and CI/CD pipeline definitions. Diagrams are produced in Mermaid notation, including C4Context diagrams at the system level.

Engineering teams and technical writers who need to produce or refresh full C4-model documentation for a codebase, as well as the non-technical stakeholders the context-level output is specifically written to be understandable by.