Guide · Agent skill
How to use the Code Tour Builder agent skill (code-tour)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The code-tour skill lets an AI agent read a codebase and write a CodeTour file: a step-by-step walkthrough that opens in the VS Code CodeTour extension and links to specific files and line numbers. It is useful for engineers onboarding onto an unfamiliar repo, reviewers working through a pull request, and maintainers writing contributor guides. By the end of this guide you will know what the skill does, how to install it, how to ask for a tour in plain language, and how to check the result.
Code Tour Buildergithub/awesome-copilot · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the code-tour ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 2Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 3Install Python 3. The bundled validator and generator are Python scripts, so Python 3 must be available on your machine.
- 4Ask for a tour in plain language. Name the reader and the goal, for example 'make an onboarding tour for a new joiner'.
- 5Let the agent explore and write the .tour file. The agent reads the README, config files and entry points, then writes the tour into .tours/.
- 6Run the validator. Run validate_tour.py against the new .tour file with --repo-root . and fix any reported errors.
- 7Open it in VS Code. Open the repo in VS Code with the CodeTour extension installed and start the tour.
What an agent skill is and what this one makes the agent do
An agent skill is a folder of instructions and optional scripts that an AI agent loads when your request matches the skill's purpose. The main file, SKILL.md, tells the agent what to do; bundled files give it reference material and helper scripts.
Once code-tour is installed, the agent explores the repository, picks the parts that matter for a chosen reader, and writes a narrative of steps in a .tour JSON file. Tours are stored in a .tours/ folder in the repo. The skill supports 20 developer personas, including new joiner, bug fixer, architect, PR reviewer, and security reviewer, and it covers the CodeTour step types for file and line, selection, pattern, uri, commands and view.
- Output: .tour JSON files in .tours/ only. The skill is meant to write only tour files, not change application code.
- Reader-specific: the same repo can get a different tour for a new joiner than for a PR reviewer.
- Validated: the agent runs a bundled validator that checks JSON validity, that file paths and directories exist, that line numbers are in bounds, and that nextTour cross-references resolve.
Install the code-tour skill
Download the ZIP of the code-tour skill from this page. You can install it in one of two ways.
For Claude Code, unzip it into your user skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it available only in that repository. For the Claude apps, upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/ (available across your projects).
- Project install: .claude/skills/ inside one repository.
- Claude apps: Settings → Capabilities → Skills, then upload the skill.
Know the requirements before you start
The skill runs Python scripts, so Python 3 must be installed. The scripts are validate_tour.py, which checks finished tours, and generate_from_docs.py, which builds a starter skeleton from README and docs. The skill does not use the network.
To read the output you need VS Code with the CodeTour extension. A .tour file is only useful inside that tool, so teams without VS Code or CodeTour will get little value from it.
- Python 3 (runs validate_tour.py and generate_from_docs.py).
- VS Code with the CodeTour extension (to view .tour files).
- The skill's bundled files: references/codetour-schema.json, references/examples.md, scripts/generate_from_docs.py, scripts/validate_tour.py and SKILL.md.
Ask for a tour with a natural request
You do not need special syntax. The skill's description lists trigger phrases, so requests like these should activate it: 'create a tour', 'make a code tour', 'onboarding tour', 'tour for this PR', 'tour for this bug', 'RCA tour', 'architecture tour', 'explain how X works', 'PR review tour', 'contributor guide' and 'help someone ramp up'. Name the reader and the goal, because the agent chooses its persona and depth from your wording.
If you want a tour built from the README and docs, say 'generate from README' or 'use the docs'. The agent then runs generate_from_docs.py first and fills in each placeholder by reading the real files.
- Good: 'Make an onboarding tour for a new backend engineer who will work on the payments service.'
- Good: 'Tour for this PR, aimed at the reviewer, focusing on the auth changes.'
- Vague: 'Make a tour.' The agent may have to guess the reader and scope.
Run the validator and open the tour
After the agent writes a tour, run the validator from the repository root. The SKILL.md example uses the path ~/.agents/skills/code-tour/scripts/ for the scripts. If you installed to ~/.claude/skills/ instead, change the path to match your install location.
If the validator reports a missing file or an out-of-range line, ask the agent to fix that step and run the check again. When it passes, open the repo in VS Code with the CodeTour extension installed and start the tour from the .tours/ folder.
- Run from the repo root so --repo-root . resolves correctly.
- Fix every reported error before sharing the tour with your team.
python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .Limits to plan around
The agent can only describe code it can read. In very large monorepos it may not read enough files to build an accurate tour, and the result can miss important areas. The skill handles large repos by focusing on two or three relevant modules and listing other areas as out of scope, so review the intro step to see what was left out.
The skill's own guidance also says to read the tour's references before trusting them. Treat the tour as a draft that a maintainer checks, not a finished document.
- Very large repos: expect a focused tour, not full coverage.
- Check paths and claims against the code; the validator checks existence and bounds, not whether an explanation is correct.
- Do not expect code changes: the skill writes only .tour files.
What people use it for
- Onboarding a new engineer to an unfamiliar service by walking through its entry points and key modules.
- Giving a PR reviewer a guided path through the files changed in a specific pull request.
- Helping a bug fixer trace a failure from its entry point to the likely fault points and related tests.
- Writing a contributor guide for an open-source project so newcomers know where to start.
- Producing an architecture walkthrough for a team that needs to understand how a system is organised.
Frequently asked questions
Is the code-tour skill free to use?
The skill is published under the MIT licence, as stated on this page. Check the licence file in the source repository for the full terms before redistributing it.
What do I need to run the code-tour skill?
You need Python 3 to run the bundled validate_tour.py and generate_from_docs.py scripts. You also need VS Code with the CodeTour extension to view the resulting .tour files.
Where do I install the code-tour skill?
Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one repository. In the Claude apps, upload it under Settings → Capabilities → Skills.
Does the code-tour skill change my application code?
No. The skill is meant to write only .tour JSON files, and its instructions say not to create or modify any other files.
Does the skill need internet access?
The listing says it does not use the network. It works from the files in your repository.
My tour does not open or validation fails. What should I check?
Confirm the file is in .tours/ and has a .tour extension, run validate_tour.py from the repo root with --repo-root ., and fix any missing file paths or out-of-range line numbers it reports. Also confirm the CodeTour extension is installed in VS Code.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use code-tour if you want a repository-specific walkthrough for onboarding, PR review or bug fixing, and your team already works in VS Code with the CodeTour extension. Pick something else if you do not use VS Code, if the repo is very large and you need full coverage, or if you want an agent to change application code.
Download the skill