crawl-repo

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.