Repo Map Skill

Agents burn their context windows on exploration: reading ten files to find the one, re-reading them next session, paying full price for code that was only ever navigation. The fix is the oldest one in computing — an index. This skill generates a compact, deterministic map (tree + line counts + top-level symbols via regex, no parser dependencies, nothing leaves the machine) and installs the discipline that makes it pay: read the map first, open only the files whose names and symbols match the task. The script prints its own economics: a typical map costs ~3% of reading everything.

What This Skill Produces

• The map — tree with per-file line counts and top-level symbols (functions, classes, types) for ~10 common languages
• The token math — reading-everything vs. reading-the-map, printed in the header
• The navigation plan — for the task at hand: which files the map says to open, which to skip
• The refresh rule — when the map is stale and what it costs to regenerate (nothing — it's local and instant)

Required Inputs

Ask for these if not provided:

• The directory — repo root or the subdirectory that matters (mapping src/ beats mapping node_modules' ancestors)
• The task — the map is generic; the navigation plan needs to know what's being hunted (a bug in auth? the payment flow? where X is defined?)
• Scale expectations — huge monorepos get mapped per-subdirectory (--max-files guards the map's own size; a 40,000-file map defeats itself)

Programmatic Helper