How to use the Code Tour Builder agent skill (code-tour)

What is the code-tour skill and what does it make the agent do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for one kind of task. The code-tour skill tells the agent to create CodeTour .tour files for codebase walkthroughs. The tour is stored in a .tours/ folder and opens at real files and line ranges rather than as a loose Markdown note.

The skill is written for a specific reader. A good tour tells that reader what they are looking at, why it matters, and which path to follow next. The skill is meant to write .tour JSON files only and should not change source code.

• Works on onboarding tours, architecture walkthroughs, pull request tours, RCA tours, and requests like 'explain how this works'
• Each step includes a file path, line numbers and an explanation
• Chooses a persona and depth based on the request

Install the code-tour skill from the ZIP file

Download the ZIP for the code-tour skill from this page and unzip it. The skill is a single file, SKILL.md, so the unzipped folder should contain that file.

For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in the project's .claude/skills/ folder so it applies only to that repository.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

You do not need a special command. Ask for a tour in plain language and the agent should recognise the request. The skill's description lists the situations it covers, so requests that match them are the most likely to trigger it.

Name the audience and the scope when you can. The skill chooses its persona and depth from the request, so 'a tour for a new joiner' gives a different result from 'a walkthrough of the payment flow for a reviewer'.

• 'Create a code tour for onboarding a new engineer to this repo'
• 'Make a .tour walkthrough of how the login feature works'
• 'Build a PR tour for the changes on this branch'
• 'Explain how this works as a guided tour'

What the agent does before writing a tour

The skill asks the agent to explore the repository before writing any step. The agent reads the README, the package or app entry points, the folder structure, relevant config files, and the changed files when the tour is about a pull request.

The agent is told not to start writing steps until it understands the shape of the code. It also chooses a persona from the request. For onboarding or new-joiner requests, the persona is new-joiner and the recommended depth is 9 to 13 steps.

• Reads README and entry points
• Reads folder structure and config files
• Reads changed files for PR tours
• Matches the persona and depth to the request

What the output looks like and what it needs

The output is a CodeTour .tour file in JSON format. Each step contains a file path, line numbers and an explanation. Reading it comfortably usually means opening it with the CodeTour VS Code extension, which the source names as the typical viewer.

The source does not describe any scripts or network access for this skill. It lists no scripts to run and no network use.

• Requires the CodeTour .tour format
• Typically viewed with the CodeTour VS Code extension
• Runs scripts: no
• Uses network: no

Safety notes: scripts, network and source code

According to the skill's listing, code-tour runs no scripts and uses no network. Its own instructions say to create only .tour JSON files and not to change source code as part of the skill.

Because the agent reads your repository to build a tour, use it on code you are comfortable having the agent read, as you would for any agent task. Review the generated .tours/ files before you commit them.

• No scripts are run by the skill
• No network use is listed
• Only .tour files are meant to be created
• Review .tours/ output before committing

When to use code-tour and when not to

Use this skill when a reusable, guided artifact helps more than a flat summary. It fits engineers onboarding to an unfamiliar repository, reviewers who want a route through a pull request, and teams that already use or want to adopt the CodeTour format.

Skip it for one-off questions that a direct answer can handle. The skill adds overhead for simple explanations. It is also the wrong choice if your team wants ordinary prose documentation, or if you need broad codebase onboarding, where the skill points you to codebase-onboarding instead.

• Good fit: onboarding, architecture walkthroughs, PR tours
• Poor fit: quick one-off explanations
• Poor fit: teams that want standard prose docs
• Use codebase-onboarding for broad onboarding