agentleFS
cathrynlaverycathrynlavery/repo-atlas/SKILL.md

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

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. Lxiny-zy/repo-atlas★ 13same name
    2. AndreaMontemaggiore1/repo-atlas★ 2same name
    3. BrickerP/Personal-Skills★ 0same name
    4. 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
  1. Distinctive:

    Do NOT change product/runtime behavior

    line 12
  2. Distinctive:

    No paid/hosted tooling — everything lives in the repo

    line 13
  3. Distinctive:

    All generated content must reflect real repo specifics, not generic filler

    line 15
  4. Distinctive:

    Before writing anything, understand the repo:

    line 21
  5. Distinctive:

    Read the top-level directory structure

    line 23
  6. Distinctive:

    Read 5-10 key files to understand architecture patterns

    line 27
  7. Very specific:

    After the script generates the skeleton, manually add these sections to repo-map.md:

    line 50
  8. Very specific:

    Create docs/atlas/ with these files.

    line 74
  9. Distinctive:

    Add an atlas section to the repo's CLAUDE.md (or create one) with:

    line 91
  10. Very specific:

    Add to Makefile (create if needed):

    line 99
  11. Very specific:

    If the repo uses package.json, also add to scripts:

    line 109
  12. Very specific:

    Run atlas-generate — must complete without errors

    line 117
  13. Very specific:

    Run atlas-check — must exit 0 immediately after generation

    line 118
  14. Distinctive:

    After completing all phases, report:

    line 124

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Read the top-level directory structure
  2. Identify the repo type (app, backend/API, library, monorepo, CLI, infrastructure)
  3. Identify the primary language(s) and framework(s)
  4. Find entrypoints, build configs, CI files
  5. 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:

  1. Copy the script to the target repo
  2. 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 directories
    • ENTRYPOINT_NAMES — add framework-specific entry filenames
    • ENTRYPOINT_PATH_PATTERNS — add path-based patterns (fnmatch style, e.g., cmd/*/main.go)
    • ENTRYPOINT_CONTENT_MARKERS — add code markers that identify entry points
    • CONVENTIONAL_COMMITS — adjust if repo uses different commit conventions
    • CHANGELOG_DAYS — change the changelog lookback window (default: 14)
  3. Run: python3 scripts/atlas/generate_atlas.py --write

This auto-generates:

  • docs/atlas/repo-map.md — directory tree + entrypoints + file stats
  • docs/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.

FileContent Source
00_README.mdHow to use the atlas + agent workflow conventions
01_ARCHITECTURE.mdRead entrypoints, DI setup, module boundaries
02_DOMAIN_MODEL.mdRead models/types, identify state machines
03_CRITICAL_FLOWS.mdTrace top 3-5 user flows through the code
04_STATE_SOURCES_OF_TRUTH.mdIdentify all state stores (DB, cache, files, memory)
05_EXTERNAL_DEPENDENCIES.mdRead package manifests + integration code
06_GOTCHAS.mdLook for race conditions, init ordering, fragile patterns
07_TEST_MATRIX.mdRead 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

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 --check

If 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

  1. Run atlas-generate — must complete without errors
  2. Run atlas-check — must exit 0 immediately after generation
  3. Confirm every atlas doc has real file paths and repo-specific content
  4. 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.md for structure guidance on each manual doc

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.