| name | crawl-repo |
| description | Use this skill when the user wants the repository crawled, mapped, and documented into a single reusable REPO.md reference. Key triggers: "crawl the repo", "document this repository", "build/update REPO.md", "describe the whole repo", "make a repo map", "summarize the codebase for later". The skill reads every relevant file and writes a dense, accurate REPO.md so future Claude Code sessions can understand the repo from one file instead of re-reading everything — saving tokens. (Formalizes the older /detailed-repo command.) |
Claude Code — Crawl & Document Repository Skill
Goal
Produce (or refresh) a single REPO.md at the current working directory that lets a future Claude Code session understand this repository without re-reading every file. REPO.md is a token-saving reference: read it once, skip the crawl.
Optimise the output for that consumer (an LLM agent), not for a human reader:
- Dense, factual, skimmable. No filler, no marketing tone.
- Accurate to what is on disk. Never describe aspirational features as if they exist.
- Stable structure (same headings each run) so diffs are meaningful when re-run.
Procedure
1. List the files
Run the canonical crawl command from the repo root:
find . -mindepth 1 \( -name 'node_modules' -o -name '.*' -o -name 'dist' \) -prune -o -type f -print
That command prunes dotfiles/dot-dirs — but the repo's real intent often lives there. So also list a few high-signal hidden locations (ignore any that don't exist):
ls -la
find ./.ai-agent ./.claude ./docs ./plans -type f 2>/dev/null
git log --oneline -8 2>/dev/null; cat .gitignore 2>/dev/null
2. Read everything that matters — in parallel
- Read config, source, docs, and any plan / spec / ROADMAP / CLAUDE.md files. Batch independent
Read calls in a single message to go fast.
- Skip binaries by content but note they exist (favicons, lockfiles). For reference images / screenshots in a
references/ or assets/ dir, open them — design targets are signal.
- Note empty scaffolded directories (e.g.
src/lib/, tests/). "Exists but empty" tells a future agent the structure is planned but unbuilt.
3. Reconcile docs vs. reality (critical)
README / ROADMAP / marketing docs frequently describe a different or aspirational app than the code. When they disagree:
- Identify the authoritative source of truth (usually the newest approved plan/spec file, or the code itself).
- Explicitly flag stale docs in
REPO.md so the next agent doesn't build against them.
- State the current build state plainly: greenfield scaffold, partial, or shipped.
4. Write REPO.md
Overwrite (or create) REPO.md in the current directory using the structure below. Keep it tight — link to files by path; don't paste whole files.
# REPO.md — <repo/app name>
> Machine-oriented map for LLMs / agentic coders. Reflects actual state on disk as of <date>.
## ⚠️ Read first # ONLY if docs disagree with code — the truth table + which source wins
## 1. What this is # one-paragraph purpose + current build state (greenfield / partial / shipped)
## 2. Tech stack # framework, language, key deps (with versions), build/deploy target
## 3. Directory map # tree with one-line purpose per dir/file; mark EMPTY scaffolds
## 4. Current code # what actually runs today — entry points, routes, key modules
## 5. Commands # install / dev / test / build / deploy
## 6. Coding rules # binding conventions from CLAUDE.md / style guides (summarized)
## 7. Spec / roadmap # the authoritative plan: objectives, constants, out-of-scope
## 8. Gotchas # contradictions, risks, TODOs a future agent must know
## 9. First moves # suggested starting actions for an agent picking this up
Omit sections that genuinely don't apply (e.g. drop "Read first" if docs and code agree). Prefer tables for stacks and truth-comparisons.
5. Close out
- Tell the user
REPO.md was written and give a 3–5 bullet summary of the most important findings (especially any doc-vs-code drift or build-blocking contradictions).
- Do not commit unless asked.
Quality bar
- Faithful: if a feature isn't in the code, it isn't "done" — say so.
- Dense: every line earns its tokens; this file is read to avoid reading others.
- Stable: reuse the same headings on re-runs so updates are clean diffs.
- Pointers over dumps: reference
path:line; never inline large file bodies.
