Code Tour

Create CodeTour .tour files for codebase walkthroughs that open directly to real files and line ranges. Tours live in .tours/ and are meant for the CodeTour format, not ad hoc Markdown notes.

A good tour is a narrative for a specific reader:

• what they are looking at
• why it matters
• what path they should follow next

Only create .tour JSON files. Do not modify source code as part of this skill.

When to Use

Use this skill when:

• the user asks for a code tour, onboarding tour, architecture walkthrough, or PR tour
• the user says "explain how X works" and wants a reusable guided artifact
• the user wants a ramp-up path for a new engineer or reviewer
• the task is better served by a guided sequence than a flat summary

Examples:

• onboarding a new maintainer
• architecture tour for one service or package
• PR-review walk-through anchored to changed files
• RCA tour showing the failure path
• security review tour of trust boundaries and key checks

When NOT to Use

Workflow

1. Discover

Explore the repo before writing anything:

• README and package/app entry points
• folder structure
• relevant config files
• the changed files if the tour is PR-focused

Do not start writing steps before you understand the shape of the code.

2. Infer the reader

Decide the persona and depth from the request.

3. Read and verify anchors

Every file path and line anchor must be real:

• confirm the file exists
• confirm the line numbers are in range
• if using a selection, verify the exact block
• if the file is volatile, prefer a pattern-based anchor

Never guess line numbers.

4. Write the .tour

Write to:

.tours/<persona>-<focus>.tour

Keep the path deterministic and readable.

5. Validate

Before finishing:

• every referenced path exists
• every line or selection is valid
• the first step is anchored to a real file or directory
• the ref points at a branch or commit that actually has every file the tour references (see below)
• the tour tells a coherent story rather than listing files

The ref Field

ref ties the tour to a git branch or commit. It matters more than it looks: when ref is not the branch the reader has checked out, CodeTour opens each step's file from that revision in git, not from the files on disk. If a file is not in that revision, the step will not open — the reader sees "The editor could not be opened because the file was not found" even though the file is sitting right there. The tour and its comments still show, so the real cause is easy to miss.

Pick ref by tour type:

The PR case is the common trap: a PR usually adds new files, and new files do not exist on the base branch yet. Point ref at the base (e.g. develop) and every step on a new file fails to open.

Before finishing, confirm each step's file actually exists at the ref you chose.

Step Types

Content

Use sparingly, usually only for a closing step:

{ "title": "Next Steps", "description": "You can now trace the request path end to end." }

Do not make the first step content-only.

Directory

Use to orient the reader to a module:

{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }

File + line

This is the default step type:

…