architecture-md-builder

name	architecture-md-builder
description	Build comprehensive ARCHITECTURE.md files following matklad's canonical guidelines — bird's-eye views, ASCII/Mermaid diagrams, codemaps, invariants, and layer boundaries. Triggers on document the architecture, create ARCHITECTURE.md, map this codebase, architectural overview.

Architecture.md Builder

Create production-quality ARCHITECTURE.md files that serve as definitive maps of any codebase, following matklad's canonical guidelines with modern AI-agent documentation patterns.

When to Use This Skill

• Creating architecture documentation for a new or existing repository
• Auditing a codebase to understand its structure
• Onboarding documentation for developers and AI agents
• User asks to "document the architecture", "create architecture.md", or "map this codebase"

Core Principles (matklad's Guidelines)

The canonical ARCHITECTURE.md follows these principles:

1. Bird's eye overview - Problem being solved, high-level approach
2. Coarse-grained codemap - Modules and relationships (country-level, not state-level)
3. Named entities - Important files, types, modules by name (no links, use symbol search)
4. Architectural invariants - Constraints, what is NOT done, absence patterns
5. Layer boundaries - Transitions between systems
6. Cross-cutting concerns - Issues spanning multiple modules

See references/matklad-guidelines.md for detailed explanations.

Workflow

Phase 1: Research Best Practices (Optional)

If unfamiliar with architecture documentation patterns, use Exa search:

# Search for exceptional architecture.md examples
python3 ~/.claude/skills/exa-search/scripts/exa_search.py \
   \
  --category github -n 10


python3 ~/.claude/skills/exa-search/scripts/exa_research.py \