architecture-md-builder

# 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: ```bash # Search for exceptional architecture.md examples python3 ~/.claude/skills/exa-search/scripts/exa_search.py \ "architecture.md documentation best practices" \ --category github -n 10 # Find matklad's original guidelines ...