Use codebase-tour

Get a newcomer (a new engineer, or the agent itself) oriented in an unfamiliar repository before they make one specific change, with a short tour scoped to that change

Get a newcomer (a new engineer, or the agent itself) oriented in an unfamiliar repository before they make one specific change, with a short tour scoped to that change. It gives the install, run and test commands taken from CI, package scripts and the Makefile; the path the change touches, traced through the code with file:line citations; where the change goes; the conventions the code actually follows; the traps (generated files, a second copy of the logic, untested code, env vars, flags); and a first step that can be checked.

Reach for it when someone says "I'm new to this repo", "get me oriented", "where would I make this change", "walk me through the code for X", "onboard me before I start this ticket", or "how do I run and test this".

Install it

npx skilldrop-cli install codebase-tour                 # Claude Code, your user folder
npx skilldrop-cli install codebase-tour --project       # Claude Code, this repo
npx skilldrop-cli install codebase-tour --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Dev team pack: --pack dev-team installs it with its neighbours.

It ships scripts, so it needs Python 3 (standard library only, nothing to install). What they may touch is declared in its manifest.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "I'm new to this repo and need to add rate limiting to the login endpoint. Get me oriented."
• "Before I start this ticket, walk me through the code that handles invoice exports"
• "Where would I make this change? I've never seen this codebase"
• "How do I run and test this project, and where does the payment retry logic live?"
• "Onboard me to this repo so I can fix the timezone bug in the scheduler"

Requests like these belong to a different skill, so it shouldn't answer them:

• "Reverse-engineer the architecture of this whole system and draw the as-is diagram"
• "Write an AGENTS.md for this repo so agents stop running the wrong commands"
• "Implement the carrier filter on GET /shipments with tests, here are the acceptance criteria"

If another skill answers instead, ask for this one by name: "use codebase-tour".

Check what you get

A good result:

• Every claim has a citation or an [inferred] tag. Run a spot check: pick any three statements in the tour, and each must lead to a file and line that says it.
• Zero invented commands. Every command traces to CI, a package script, a Makefile, a tox or nox session or pyproject, or it is a labelled derived filter of a runner the repo already calls.
• Ran and read are never blurred. Every command carries ran: passed, ran: failed, or read, not run.
• README-versus-code conflicts are named, each with both citations and the code taken as the fact.
• Scoped, not surveyed. The path stops at the change's far edge, the tour fits the caps, and the scope line says what was skipped.
• The trap checks all report, including "none found". A second copy of the logic, when one exists, is named with its location.
• The tests for the area are named, with a command for just those, or the tour says plainly that there are none.
• It ends at a place to work. Files and functions, then a first step with a command and an expected result, then at most five open questions.
• The reply leads with the 3–5 things that matter, not a tree.

See a worked example

• refund window

Use something else when

• A full as-is architecture write-up or diagram of the whole system: reverse-architecture
• Drawing a diagram of a flow or a system: interactive-diagram or architecture-diagrams
• Writing a standing AGENTS.md or agent-policy file for the repo: agents-md-generator
• Writing the code for the change: feature-implement-loop
• Reviewing a diff that already exists: pre-merge-review

Where a loop runs it

• Stage shape of the build loop
• Stage survey of the modernize loop

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: agents-md-generator, architecture-diagrams, feature-implement-loop, interactive-diagram, pre-merge-review, reverse-architecture

Edit this page on GitHub · View source