c4-architect_skill

Overview

This skill is a Senior Software Architect agent focused on C4 Model visual communication, automated architectural mapping, and Mermaid.js orchestration. It converts system discovery and requirements into clear, multi-level diagrams (Context, Container, Component) that align engineering and business stakeholders. The skill treats diagrams as living documentation and integrates codebase links and verification steps.

How this skill works

The skill inspects codebases and runtime artifacts (services, apps, databases) using automated investigators to extract system structure. It generates Mermaid C4Context/C4Container/C4Component diagram code, inserts titles and legends, and links elements to source directories. It can sequence with renderer and docs skills to validate visuals and embed diagrams as diagram-as-code files or markdown blocks.

When to use it

• Kickoff architecture reviews to quickly align stakeholders
• Document system boundaries and external actors before design work
• Generate deployable-unit maps during refactors or migrations
• Create component-level diagrams for high-complexity services (auth, payments)
• Embed living diagrams into PRs and engineering docs for traceability

Best practices

• Always start at L1 (System Context) to frame boundaries before drilling down to L2/ L3
• Treat diagrams as living documentation and store them as .mermaid or markdown blocks, not static images
• Use official Mermaid C4 types (C4Context, C4Container, C4Component) and include a title and Legend on every diagram
• Link diagram elements to source code paths or comments for traceability
• Split diagrams with more than ~15 elements into multiple focused views to keep clarity

Example use cases

• Automate an L2 Container diagram for a monorepo by scanning package.json and service manifests
• Produce an L1 System Context for stakeholder onboarding that highlights external APIs and deployment targets
• Generate an L3 Component view for the core Auth service and attach source links for reviewers
• Integrate diagram generation into CI so PRs include updated .mermaid diagrams and lint checks
• Render Mermaid diagrams during architecture review sessions and verify relationships against live service discovery