cartography_skill

Overview

This skill generates hierarchical codemaps to help you understand and document a TypeScript repository. It creates and maintains a slim state file, spawns explorer agents to produce per-folder codemaps, and assembles a root atlas that acts as the master entry point for humans or agents.

How this skill works

On first run the skill initializes repository state (.slim/cartography.json), discovers core code files (e.g., src/**/*.ts, package.json) while excluding tests, docs, build artifacts and node_modules, and creates empty codemap.md placeholders. It spawns one explorer agent per relevant folder to read code and fill codemap.md files. When state exists it detects added/removed/modified files, updates only affected codemaps, and then updates the stored state. Finally, an orchestrator aggregates all folder codemaps into a root codemap.md (Repository Atlas) that cross-references each sub-map and summarizes responsibilities.

When to use it

• Mapping or documenting an unfamiliar TypeScript codebase before making changes
• Generating a navigable, machine- and human-readable repository atlas for agents
• Maintaining codemaps after incremental updates to keep docs in sync
• Onboarding engineers who need a directory-level responsibility and flow summary
• Automating codebase summaries for orchestration or agentic workflows

Best practices

• Run init only when no .slim/cartography.json exists; otherwise run changes/update flow
• Limit inclusion to core code and config (src/**/*.ts, package.json) and respect .gitignore
• Always exclude tests, docs, translations, node_modules, dist, and build outputs
• Spawn one explorer per folder to keep codemaps concise and focused on local responsibility
• Aggregate clear Responsibility, Design Patterns, Flow, and Integration sections in each codemap.md

Example use cases

• Initialize codemaps for a new fork to produce a minimal token-efficient atlas
• Detect modified folders after a PR and update only affected codemap.md files
• Create a root Repository Atlas that points engineers and agents to detailed sub-maps
• Automate agent handoffs by providing precise directory responsibilities and integration points
• Produce machine-consumable maps for other orchestration skills that route tasks