Walkthrough: Claude Code skill for codebase walkthroughs

Walkthrough is a Claude Code skill, packaged by AR Labs from Simon Willison's linear walkthrough method, that has an agent write a guided, linear tour of a codebase, or of one module or feature, for someone who needs to understand how it works: a developer returning to code an agent wrote quickly, or someone inheriting it. Its defining rule is that the agent never types code into the document. Every excerpt is extracted from the real files by a shell command, and the command's output is what appears. That removes a common way an AI-written explanation goes wrong: quoting code that does not exist or no longer looks like that.

The method is Simon Willison's. He described it as the linear walkthrough pattern, built on Showboat, his tool for agents writing documents that demonstrate their work, and he chose the "extract with sed, grep or cat" instruction for exactly this reason. We packaged that method as a skill with a scoping step, a reading-order plan, a standard section arc and a place for the output.

How it works

Showboat is a command-line tool that builds a markdown document from two kinds of entry: a note, which adds narrative, and an exec, which runs a command and records both the command and its real output.

1. Scope. Decide the target (a project, a module, a feature), the audience and the depth. The default is the current project, for its owner, at architecture level.
2. Read and plan. Read the directory structure and every relevant file, then plan a reading order: entry point first, then dependencies in the order a reader discovers them.
3. Build the document by alternating narrative and extraction: a note explaining what the next excerpt shows and why it matters, then an exec that pulls the lines with sed, grep or cat.
4. Verify. Showboat re-runs every command in the document and compares the output with what was recorded, so a walkthrough that has gone stale after a code change shows up as a difference instead of being trusted.

A typical tour runs overview, architecture, entry point, core flow, key abstractions, supporting code and a closing summary of how it connects. A single-file script may need only an overview and annotated code.

The judgement it encodes

Extract, never reproduce. Code reaches the document only through a command's output. This is the main defence against invented code.

Reading order is a design decision. Alphabetical order and file order are both wrong. The tour follows what a reader needs to understand first.

Explain the why. The code already shows what it does; the narrative explains the design choices behind it.

Remove unhelpful output. If an extraction produces noise, the step is removed with showboat pop and a better extraction is tried.

What exists today

The skill is part of our agent setup for codebase orientation. For a single change rather than a whole codebase, we use Comprehend. Our separate practice of recording why each change was made, as the work happens, is described in implementation walkthroughs, and how these tools fit together in understanding code that AI agents write.

Example

Illustrative example. The opening of a walkthrough as the commands that build it:

showboat init walkthrough.md "Walkthrough: transcript exporter"
 
showboat note walkthrough.md "## Entry point
Exports start at a single HTTP route. Read the handler first: it
decides the format and hands off to a writer."
 
showboat exec walkthrough.md bash "grep -n -A 18 'def export_transcript' app/routes.py"
 
showboat note walkthrough.md "The handler never touches the file
system. Writers own output, which is why adding a format means adding
one class and nothing else."
 
showboat verify walkthrough.md