/exploring-codebases

name: exploring-codebases
description: >-
  First-encounter orientation on a repository nobody here has worked in yet.
  Runs a fixed five-step workflow — venv setup, tarball fetch, tree-sitting
  structural scan, featuring synthesis, then reasoning over the two — and
  yields an account of what the repo contains and how it is arranged,
  optionally written out as _FEATURES.md. Use for "I just cloned this",
  "what is this repo", "what does this do", "explore this repo", "give me an
  orientation", "what are the main features", "review what's new in this repo",
  or before starting work in a codebase you have not seen. This is the
  divergent what's-here skill. Route elsewhere for: a named symbol, a file's
  structure or a line range (tree-sitting); all callers of a Python symbol
  (searching-codebases); teaching a human the codebase through exercises
  (orienting-codebases); fetching or cloning a repo without analysing it
  (accessing-github-repos, cloning-project).
metadata:
  version: 2.6.0

Exploring Codebases

Exploratory code analysis for unfamiliar repositories. Orchestrates tree-sitting (structural) and featuring (semantic) over a local copy.

Workflow

Five numbered steps, in order. Do not skip step 0.

0. Setup (once per session)

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter --python /home/claude/.venv/bin/python
export PYTHON=/home/claude/.venv/bin/python
export TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py
export GATHER=/mnt/skills/user/featuring/scripts/gather.py

If step 2's `--stats` reports `Symbols: 0` on a repo you know contains code, the `tree-sitter` core package isn't installed — come back here and install it (the engine bundles its own grammars and does NOT use tree-sitter-language-pack). Treesit exits 0 and prints no error in that case, so zero symbols is the only signal you get. There is no `Errors:` line: that one appears for parse failures, and an absent parser never reaches parsing. The full signal is in the tree-sitting skill's Setup section.

1. Get the repo (tarball, not per-file)

OWNER=...
REPO=...
REF=main                    # branch name, tag, or SHA. For a PR: pull/N/head
curl -sL -H "Authorization: Bearer $GH_TOKEN" \
  "https://api.github.com/repos/$OWNER/$REPO/tarball/$REF" -o /tmp/$REPO.tar.gz
mkdir -p /tmp/$REPO && tar -xzf /tmp/$REPO.tar.gz -C /tmp/$REPO --strip-components=1
ls /tmp/$REPO | head        # sanity check — did extraction land?

One HTTP call gets the whole repo. Do NOT curl README, cat files, or fetch via `contents/PATH` first — they're in the tarball. The Authorization header is only needed for private repos; public repos work without it.

**Ref selection matters.** If exploring a feature branch, PR, or tag, set `REF` accordingly. The default `main` will silently give you stale code if the question is about an unmerged branch.

2. Structural scan

$PYTHON $TREESIT /tmp/$REPO --stats

Read the output. It gives file counts, symbol counts, languages, and per-directory symbol density. This IS the orienting artifact — treat it as the product of this step, not warm-up.

**Drill only if you have a specific question.** For pure "what is this repo" exploration, skip drilling and go to step 3 — featuring surfaces the interesting paths for you. Drill when a user asked about a specific subsystem, or when step 3's output raises a question that needs source.

**When you do drill, batch queries in one invocation.** Every treesit call pays the full scan cost. Multiple queries added to the same command share that scan and each additional query adds ~0ms. If you're about to make a second treesit call on the same path, fold it into the first.

# GOOD — one scan, three answers
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full \
  'find:*Handler*:function' 'source:main' 'refs:Config'

# BAD — three scans, three answers (3× the cost for the same information)
$PYTHON $TREESIT /tmp/$REPO --path=SUBDIR --detail=full
$PYTHON $TREESIT /tmp/$REPO 'find:*Handler*:function'
$PYTHON $TREESIT /tmp/$REPO 'refs:Config'

3. Feature synthesis

**Pick the mode from your DELIVERABLE, before you run it.**

| Your deliverable | Command | Size | |---|---|---| | Your own understanding — a review, an orientation read, answering a question | `--orient` | ~115 lines | | A written `_FEATURES.md` that must cite every symbol | full output | thousands of lines |

# Default. Complexity assessment, decomposition ranking, directory tree, entry points.
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --orient

# Only when you are about to WRITE the inventory into a file:
$PYTHON $GATHER /tmp/$REPO --skip tests,.github,node_modules --source-budget 8000

Output includes a "Candidate areas for sub-files (by symbol density)" list near the top — that's your drill-target picker, ranked.

**Never pipe the full output through `head`.** If you are about to truncate it, `--orient` was the correct mode and you have paid for thousands of lines you will not read. One review's full gather ran to 5,697 lines and was cut at line 120; every finding in it came from `treesit` drilling and targeted reads instead. `--orient` returns the ~115 lines that get used. The full mode's symbol inventory exists to be CITED, not read.

4. Reason about the combined output

Synthesize 2+3: capabilities, feature groups, architecture, entry points, anomalies. Produce `_FEATURES.md` when warranted. This is the LLM step; everything before was mechanical.

When to Use This vs Other Skills

| Situation | Use | |-----------|-----| | "I just cloned this, what is it?" | **exploring-codebases** (this skill) | | "Where is the retry logic?" | searching-codebases | | "Find all files matching `class.*Error`" | searching-codebases | | "Show me the symbols in auth.py" | tree-sitting directly | | "Which files are most about CSRF / sessions / queryset filtering?" | bm25 | | "Rank these docs by