Build a persistent context system (atlas) for any repository — generates directory maps with entrypoints, documents architecture and module boundaries, traces critical flows, catalogs external dependencies, and creates agent-ready onboarding guides. Use when asked to create a repo map, generate codebase documentation for LLM agents, set up an atlas, or create onboarding docs. Also use when asked to 'map this repo', 'document this codebase', or 'create context docs'.
Instrucciones de origen · Vista previa de solo lectura
name
repo-atlas
description
Build a persistent context system (atlas) for any repository — generates directory maps with entrypoints, documents architecture and module boundaries, traces critical flows, catalogs external dependencies, and creates agent-ready onboarding guides. Use when asked to create a repo map, generate codebase documentation for LLM agents, set up an atlas, or create onboarding docs. Also use when asked to 'map this repo', 'document this codebase', or 'create context docs'.
Repo Atlas
Build an in-repo persistent context system so engineers and LLM agents can understand any codebase quickly with minimal searching.
Hard Constraints
Do NOT change product/runtime behavior
No paid/hosted tooling — everything lives in the repo
Zero or minimal dependencies (Python 3 standard library only)
All generated content must reflect real repo specifics, not generic filler
Workflow
Phase 1: Reconnaissance
Before writing anything, understand the repo:
Read the top-level directory structure
Identify the repo type (app, backend/API, library, monorepo, CLI, infrastructure)
Identify the primary language(s) and framework(s)
Find entrypoints, build configs, CI files
Read 5-10 key files to understand architecture patterns
Phase 2: Run the Generator Script
Copy scripts/generate_atlas.py (bundled with this skill) to the repo at scripts/atlas/generate_atlas.py. Then customize and run it:
Copy the script to the target repo
Review and adjust the configuration section at the top:
Create docs/atlas/ with these files. See references/atlas-templates.md for structure guidance on each.
File
Content Source
00_README.md
How to use the atlas + agent workflow conventions
01_ARCHITECTURE.md
Read entrypoints, DI setup, module boundaries
02_DOMAIN_MODEL.md
Read models/types, identify state machines
03_CRITICAL_FLOWS.md
Trace top 3-5 user flows through the code
04_STATE_SOURCES_OF_TRUTH.md
Identify all state stores (DB, cache, files, memory)
05_EXTERNAL_DEPENDENCIES.md
Read package manifests + integration code
06_GOTCHAS.md
Look for race conditions, init ordering, fragile patterns
07_TEST_MATRIX.md
Read test configs, describe how to run tests
Each doc should be 50-150 lines with real paths, real code references, and real gotchas from the codebase. Not generic advice.
Phase 5: Add Agent On-Ramp
Add an atlas section to the repo's CLAUDE.md (or create one) with:
A pointer to docs/atlas/ and its purpose
A two-agent workflow: Agent A loads repo-map.md → domain-specific doc → source files → implements; Agent B reviews diffs against 06_GOTCHAS.md, verifies flows via 03_CRITICAL_FLOWS.md, and confirms tests per 07_TEST_MATRIX.md
Working rules: read atlas before coding, verify critical flows after changes, update atlas docs when architecture changes, run make atlas-generate after structural changes
