repo-atlas
Skill56 starsChanged 10 days agoMITView on GitHub
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'.
4 other projects use a version of this.
Adopted by
Most recently taken up by
- BrickerP/Personal-Skillstheir own version, first seen Nov 1, 2026
- AndreaMontemaggiore1/repo-atlastheir own version, first seen Nov 1, 2026
- vivekmaru/repo-atlastheir own version, first seen Oct 20, 2026
- Lxiny-zy/repo-atlastheir own version, first seen Oct 5, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- Lxiny-zy/repo-atlas★ 13same name
- AndreaMontemaggiore1/repo-atlas★ 2same name
- BrickerP/Personal-Skills★ 0same name
- vivekmaru/repo-atlas★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 8 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Do NOT change product/runtime behavior
- Distinctive: line 13
No paid/hosted tooling — everything lives in the repo
- Distinctive: line 15
All generated content must reflect real repo specifics, not generic filler
- Distinctive: line 21
Before writing anything, understand the repo:
- Distinctive: line 23
Read the top-level directory structure
- Distinctive: line 27
Read 5-10 key files to understand architecture patterns
- Very specific: line 50
After the script generates the skeleton, manually add these sections to repo-map.md:
- Very specific: line 74
Create docs/atlas/ with these files.
- Distinctive: line 91
Add an atlas section to the repo's CLAUDE.md (or create one) with:
- Very specific: line 99
Add to Makefile (create if needed):
- Very specific: line 109
If the repo uses package.json, also add to scripts:
- Very specific: line 117
Run atlas-generate — must complete without errors
- Very specific: line 118
Run atlas-check — must exit 0 immediately after generation
- Distinctive: line 124
After completing all phases, report:
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
IGNORE_NAMES— add repo-specific directory names to ignore (exact segment match)TREE_ANNOTATIONS— add short descriptions for key directoriesENTRYPOINT_NAMES— add framework-specific entry filenamesENTRYPOINT_PATH_PATTERNS— add path-based patterns (fnmatch style, e.g.,cmd/*/main.go)ENTRYPOINT_CONTENT_MARKERS— add code markers that identify entry pointsCONVENTIONAL_COMMITS— adjust if repo uses different commit conventionsCHANGELOG_DAYS— change the changelog lookback window (default: 14)
- Run:
python3 scripts/atlas/generate_atlas.py --write
This auto-generates:
docs/atlas/repo-map.md— directory tree + entrypoints + file statsdocs/atlas/08_CHANGELOG_LAST_14_DAYS.md— categorized recent commits
Phase 3: Enhance repo-map.md
After the script generates the skeleton, manually add these sections to repo-map.md:
Router Table — "Where to look for X" (10-15 rows):
## Where to Look for X
| Task | Start Here |
|------|-----------|
| Fix [domain concept] | `path/to/file.ext` |Map the top 10-15 tasks someone would do in this repo to specific files.
Danger Zones — fragile files/areas:
## Danger Zones
| File/Area | Why It's Fragile |
|-----------|-----------------|
| `path/to/file` | Reason |Phase 4: Write Manual Atlas Docs
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 against06_GOTCHAS.md, verifies flows via03_CRITICAL_FLOWS.md, and confirms tests per07_TEST_MATRIX.md - Working rules: read atlas before coding, verify critical flows after changes, update atlas docs when architecture changes, run
make atlas-generateafter structural changes
Phase 6: Add Build Targets
Add to Makefile (create if needed):
atlas-generate:
python3 scripts/atlas/generate_atlas.py --write
atlas-check:
python3 scripts/atlas/generate_atlas.py --checkIf the repo uses package.json, also add to scripts:
"atlas:generate": "python3 scripts/atlas/generate_atlas.py --write",
"atlas:check": "python3 scripts/atlas/generate_atlas.py --check"Phase 7: Verify
- Run
atlas-generate— must complete without errors - Run
atlas-check— must exit 0 immediately after generation - Confirm every atlas doc has real file paths and repo-specific content
- Confirm no runtime/product code was changed
Output Summary
After completing all phases, report:
- List of created files
- How to run atlas generation/check
- 10-line "How an agent should use this atlas" quick reference
Resources
- Generator script: See
scripts/generate_atlas.py— copy to target repo and customize - Doc templates: See
references/atlas-templates.mdfor structure guidance on each manual doc
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

