repo-atlas

Name: repo-atlas
Author: cathrynlavery

2installs4forks

How to install repo-atlas?

cathrynlavery/repo-atlas/repo-atlas

$npx -y skills add cathrynlavery/repo-atlas --skill repo-atlas

Installs into the current project.

Summary

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 rep

Files · 1

View on GitHub

SKILL.md

1	# Repo Atlas
2
3	Build an in-repo persistent context system so engineers and LLM agents can understand any codebase quickly with minimal searching.
4
5	## Hard Constraints
6
7	- Do NOT change product/runtime behavior
8	- No paid/hosted tooling — everything lives in the repo
9	- Zero or minimal dependencies (Python 3 standard library only)
10	- All generated content must reflect real repo specifics, not generic filler
11
12	## Workflow
13
14	### Phase 1: Reconnaissance
15
16	Before writing anything, understand the repo:
17
18	1. Read the top-level directory structure
19	2. Identify the repo type (app, backend/API, library, monorepo, CLI, infrastructure)
20	3. Identify the primary language(s) and framework(s)
21	4. Find entrypoints, build configs, CI files
22	5. Read 5-10 key files to understand architecture patterns
23
24	### Phase 2: Run the Generator Script
25
26	Copy `scripts/generate_atlas.py` (bundled with this skill) to the repo at `scripts/atlas/generate_atlas.py`. Then customize and run it:
27
28	1. Copy the script to the target repo
29	2. Review and adjust the configuration section at the top:
30	- `IGNORE_NAMES` — add repo-specific directory names to ignore (exact segment match)
31	- `TREE_ANNOTATIONS` — add short descriptions for key directories
32	- `ENTRYPOINT_NAMES` — add framework-specific entry filenames
33	- `ENTRYPOINT_PATH_PATTERNS` — add path-based patterns (fnmatch style, e.g., `cmd/*/main.go`)
34	- `ENTRYPOINT_CONTENT_MARKERS` — add code markers that identify entry points
35	- `CONVENTIONAL_COMMITS` — adjust if repo uses different commit conventions
36	- `CHANGELOG_DAYS` — change the changelog lookback window (default: 14)
37	3. Run: `python3 scripts/atlas/generate_atlas.py --write`
38
39	This auto-generates:
40	- `docs/atlas/repo-map.md` — directory tree + entrypoints + file stats
41	- `docs/atlas/08_CHANGELOG_LAST_14_DAYS.md` — categorized recent commits
42
43	### Phase 3: Enhance repo-map.md
44
45	After the script generates the skeleton, manually add these sections to `repo-map.md`:
46
47	Router Table — "Where to look for X" (10-15 rows):
48	```markdown
49	## Where to Look for X
50
51	\| Task \| Start Here \|
52	\|------\|-----------\|
53	\| Fix [domain concept] \| `path/to/file.ext` \|
54	```
55
56	Map the top 10-15 tasks someone would do in this repo to specific files.
57
58	Danger Zones — fragile files/areas:
59	```markdown
60	## Danger Zones
61
62	\| File/Area \| Why It's Fragile \|
63	\|-----------\|-----------------\|
64	\| `path/to/file` \| Reason \|
65	```
66
67	### Phase 4: Write Manual Atlas Docs
68
69	Create `docs/atlas/` with these files. See `references/atlas-templates.md` for structure guidance on each.
70
71	\| File \| Content Source \|
72	\|------\|--------------\|
73	\| `00_README.md` \| How to use the atlas + agent workflow conventions \|
74	\| `01_ARCHITECTURE.md` \| Read entrypoints, DI setup, module boundaries \|
75	\| `02_DOMAIN_MODEL.md` \| Read models/types, identify state machines \|
76	\| `03_CRITICAL_FLOWS.md` \| Trace top 3-5 user flows through the code \|
77	\| `04_STATE_SOURCES_OF_TRUTH.md` \| Identify all state stores (DB, cache, files, memory) \|
78	\| `05_EXTERNAL_DEPENDENCIES.md` \| Read package manifests + integration code \|
79	\| `06_GOTCHAS.md` \| Look for race conditions, init ordering, fragile patterns \|
80	\| `07_TEST_MATRIX.md` \| Read test configs, describe how to run tests \|
81
82	Each doc should be 50-150 lines with real paths, real code references, and real gotchas from the codebase. Not generic advice.
83
84	### Phase 5: Add Agent On-Ramp
85
86	Add an atlas section to the repo's `CLAUDE.md` (or create one) with:
87
88	- A pointer to `docs/atlas/` and its purpose
89	- 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`
90	- Working rules: read atlas before coding, verify critical flows after changes, update atlas docs when architecture changes, run `make atlas-generate` after structural changes
91
92	### Phase 6: Add Build Targets
93
94	Add to `Makefile` (create if needed):
95
96	```makefile
97	atlas-generate:
98	python3 scripts/atlas/generate_atlas.py --write
99
100	atlas-check:
101	python3 scripts/atlas/generate_atlas.py --check
102	```
103
104	If the repo uses `package.json`, also add to scripts:
105	```json
106	"atlas:generate": "python3 scripts/atlas/generate_atlas.py --write",
107	"atlas:check": "python3 scripts/atlas/generate_atlas.py --check"
108	```
109
110	### Phase 7: Verify
111
112	1. Run `atlas-generate` — must complete without errors
113	2. Run `atlas-check` — must exit 0 immediately after generation
114	3. Confirm every atlas doc has real file paths and repo

People who liked this also viewed

6 picks

Type

repo-atlas

2installs4forks

View on GitHub

How to install repo-atlas?

cathrynlavery/repo-atlas/repo-atlas

$npx -y skills add cathrynlavery/repo-atlas --skill repo-atlas

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Repo Atlas
2
3	Build an in-repo persistent context system so engineers and LLM agents can understand any codebase quickly with minimal searching.
4
5	## Hard Constraints
6
7	- Do NOT change product/runtime behavior
8	- No paid/hosted tooling — everything lives in the repo
9	- Zero or minimal dependencies (Python 3 standard library only)
10	- All generated content must reflect real repo specifics, not generic filler
11
12	## Workflow
13
14	### Phase 1: Reconnaissance
15
16	Before writing anything, understand the repo:
17
18	1. Read the top-level directory structure
19	2. Identify the repo type (app, backend/API, library, monorepo, CLI, infrastructure)
20	3. Identify the primary language(s) and framework(s)
21	4. Find entrypoints, build configs, CI files
22	5. Read 5-10 key files to understand architecture patterns
23
24	### Phase 2: Run the Generator Script
25
26	Copy `scripts/generate_atlas.py` (bundled with this skill) to the repo at `scripts/atlas/generate_atlas.py`. Then customize and run it:
27
28	1. Copy the script to the target repo
29	2. Review and adjust the configuration section at the top:
30	- `IGNORE_NAMES` — add repo-specific directory names to ignore (exact segment match)
31	- `TREE_ANNOTATIONS` — add short descriptions for key directories
32	- `ENTRYPOINT_NAMES` — add framework-specific entry filenames
33	- `ENTRYPOINT_PATH_PATTERNS` — add path-based patterns (fnmatch style, e.g., `cmd/*/main.go`)
34	- `ENTRYPOINT_CONTENT_MARKERS` — add code markers that identify entry points
35	- `CONVENTIONAL_COMMITS` — adjust if repo uses different commit conventions
36	- `CHANGELOG_DAYS` — change the changelog lookback window (default: 14)
37	3. Run: `python3 scripts/atlas/generate_atlas.py --write`
38
39	This auto-generates:
40	- `docs/atlas/repo-map.md` — directory tree + entrypoints + file stats
41	- `docs/atlas/08_CHANGELOG_LAST_14_DAYS.md` — categorized recent commits
42
43	### Phase 3: Enhance repo-map.md
44
45	After the script generates the skeleton, manually add these sections to `repo-map.md`:
46
47	Router Table — "Where to look for X" (10-15 rows):
48	```markdown
49	## Where to Look for X
50
51	\| Task \| Start Here \|
52	\|------\|-----------\|
53	\| Fix [domain concept] \| `path/to/file.ext` \|
54	```
55
56	Map the top 10-15 tasks someone would do in this repo to specific files.
57
58	Danger Zones — fragile files/areas:
59	```markdown
60	## Danger Zones
61
62	\| File/Area \| Why It's Fragile \|
63	\|-----------\|-----------------\|
64	\| `path/to/file` \| Reason \|
65	```
66
67	### Phase 4: Write Manual Atlas Docs
68
69	Create `docs/atlas/` with these files. See `references/atlas-templates.md` for structure guidance on each.
70
71	\| File \| Content Source \|
72	\|------\|--------------\|
73	\| `00_README.md` \| How to use the atlas + agent workflow conventions \|
74	\| `01_ARCHITECTURE.md` \| Read entrypoints, DI setup, module boundaries \|
75	\| `02_DOMAIN_MODEL.md` \| Read models/types, identify state machines \|
76	\| `03_CRITICAL_FLOWS.md` \| Trace top 3-5 user flows through the code \|
77	\| `04_STATE_SOURCES_OF_TRUTH.md` \| Identify all state stores (DB, cache, files, memory) \|
78	\| `05_EXTERNAL_DEPENDENCIES.md` \| Read package manifests + integration code \|
79	\| `06_GOTCHAS.md` \| Look for race conditions, init ordering, fragile patterns \|
80	\| `07_TEST_MATRIX.md` \| Read test configs, describe how to run tests \|
81
82	Each doc should be 50-150 lines with real paths, real code references, and real gotchas from the codebase. Not generic advice.
83
84	### Phase 5: Add Agent On-Ramp
85
86	Add an atlas section to the repo's `CLAUDE.md` (or create one) with:
87
88	- A pointer to `docs/atlas/` and its purpose
89	- 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`
90	- Working rules: read atlas before coding, verify critical flows after changes, update atlas docs when architecture changes, run `make atlas-generate` after structural changes
91
92	### Phase 6: Add Build Targets
93
94	Add to `Makefile` (create if needed):
95
96	```makefile
97	atlas-generate:
98	python3 scripts/atlas/generate_atlas.py --write
99
100	atlas-check:
101	python3 scripts/atlas/generate_atlas.py --check
102	```
103
104	If the repo uses `package.json`, also add to scripts:
105	```json
106	"atlas:generate": "python3 scripts/atlas/generate_atlas.py --write",
107	"atlas:check": "python3 scripts/atlas/generate_atlas.py --check"
108	```
109
110	### Phase 7: Verify
111
112	1. Run `atlas-generate` — must complete without errors
113	2. Run `atlas-check` — must exit 0 immediately after generation
114	3. Confirm every atlas doc has real file paths and repo

People who liked this also viewed

6 picks

Type