Learn Codebase

Learn Codebase

Overview

Orchestrate the other installed skills to understand a codebase. First find out what skills exist, pick the ones that fit this repo, then use them to produce a briefing plus a saved docs/CODEBASE_OVERVIEW.md.

Workflow

1. Discover skills — see what's available.
2. Detect the stack — cheap signals reveal languages/frameworks/tooling.
3. Select relevant skills — match stack + task to skills.
4. Analyze — apply the selected skills to learn the repo.
5. Output — deliver a briefing and write docs/CODEBASE_OVERVIEW.md.

1. Discover available skills

The agent's injected <available_skills> list is the primary source — read it first. It is frequently truncated ("Additional skills available…"), so when full descriptions are needed for selection, run the bundled scanner to recover complete name: description pairs:

scripts/list_skills.py            # scans ~/.agents/skills, ~/.claude/skills, ./.claude/skills, ./skills
scripts/list_skills.py /path/to/skills   # add a non-standard location

Invoke it by its full path in this skill's directory — your cwd is usually the target repo, not the skill folder.

Do not hardcode a skill catalog — always read the live list, since installed skills change.

2. Detect the stack

Read only what's cheap and decisive before committing to skills:

• Docs first: README, AGENTS.md / CLAUDE.md, CONTRIBUTING, docs/ — the highest-signal source for purpose, conventions, and the real build/run/test commands.
• Manifests / lockfiles: package.json, pyproject.toml, go.mod, Cargo.toml, *.csproj, Gemfile, pom.xml, Package.swift, *.xcodeproj.
• Config: framework configs (next.config, vite, tailwind, astro), Dockerfile, compose files, CI under .github/, Makefile.
• Monorepo?: check for workspaces (pnpm/yarn/npm workspaces, packages/*, apps/*, Cargo/Go workspaces) and analyze each package, not just the root.
• Shape: top-level dirs, file-extension histogram, entry points, test dirs.

Skip vendored/generated dirs (node_modules, .git, dist, build, target, vendor, .venv) — they skew signals and waste effort.

3. Select relevant skills

Match stack signals and the user's goal to skills from step 1. Selection is category-based — map signals to the kind of skill, then pick whatever concrete skills in the live list fit. Only pick skills that clearly apply; ignore the rest.

When a skill fits, read its SKILL.md and apply its guidance during analysis. Prefer one or two high-leverage skills over loading many.

4. Analyze

Apply the selected skills to trace the repo end to end and capture:

• Purpose — what the project does and who uses it.
• Architecture — major components/modules and their responsibilities and boundaries.
• Data & control flow — request/render/job lifecycles; where state lives.
• Entry points — how execution starts (main, server, CLI, routes).
• Build / run / test — the exact commands, from manifests and CI.
• Conventions — patterns, naming, error handling, folder structure the repo follows.
• Risks / rough edges — TODOs, dead code, fragile spots, missing tests.

For large repos, dispatch parallel explore sub-agents on independent areas (e.g. backend, frontend, infra) and merge findings. Verify claims against the code — don't infer from names.

5. Output

Deliver both:

1. A concise briefing in the conversation (lead with purpose + architecture).
2. A written report at docs/CODEBASE_OVERVIEW.md in the analyzed repo, following references/report-template.md. Create the docs/ folder if it doesn't exist. Anchor the report with the current date and commit SHA. If the file already exists, reconcile/update it rather than blindly overwriting.

Write the report file but do not commit it automatically — leave that to the user.