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
Instead of code-tour
Use
A one-off explanation in chat is enough
answer directly
The user wants prose docs, not a
.tour
artifact
documentation-lookup
or repo docs editing
The task is implementation or refactoring
do the implementation work
The task is broad codebase onboarding without a tour artifact
codebase-onboarding
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.
Request shape
Persona
Suggested depth
"onboarding", "new joiner"
new-joiner
9-13 steps
"quick tour", "vibe check"
vibecoder
5-8 steps
"architecture"
architect
14-18 steps
"tour this PR"
pr-reviewer
7-11 steps
"why did this break"
rca-investigator
7-11 steps
"security review"
security-reviewer
7-11 steps
"explain how this feature works"
feature-explainer
7-11 steps
"debug this path"
bug-fixer
7-11 steps
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/-.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 tour tells a coherent story rather than listing files
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:
{
"file"
:
"src/auth/middleware.ts"
,
"line"
:
42
,
"title"
:
"Auth Gate"
,
"description"
:
"Every protected request passes here first."
}
Selection
Use when one code block matters more than the whole file:
{
"file"
:
"src/core/pipeline.ts"
,
"selection"
:
{
"start"
:
{
"line"
:
15
,
"character"
:
0
}
,
"end"
:
{
"line"
:
34
,
"character"
:
0
}
}
,
"title"
:
"Request Pipeline"
,
"description"
:
"This block wires validation, auth, and downstream execution."
}
Pattern
Use when exact lines may drift:
{
"file"
:
"src/app.ts"
,
"pattern"
:
"export default class App"
,
"title"
:
"Application Entry"
}
URI
Use for PRs, issues, or docs when helpful:
{
"uri"
:
"https://github.com/org/repo/pull/456"
,
"title"
:
"The PR"
}
Writing Rule: SMIG
Each description should answer:
Situation
what the reader is looking at
Mechanism
how it works
Implication
why it matters for this persona
Gotcha
what a smart reader might miss
Keep descriptions compact, specific, and grounded in the actual code.
Narrative Shape
Use this arc unless the task clearly needs something different:
orientation
module map
core execution path
edge case or gotcha
closing / next move
The tour should feel like a path, not an inventory.
Example
{
"$schema"
:
"https://aka.ms/codetour-schema"
,
"title"
:
"API Service Tour"
,
"description"
:
"Walkthrough of the request path for the payments service."
,
"ref"
:
"main"
,
"steps"
:
[
{
"directory"
:
"src"
,
"title"
:
"Source Root"
,
"description"
:
"All runtime code for the service starts here."
}
,
{
"file"
:
"src/server.ts"
,
"line"
:
12
,
"title"
:
"Entry Point"
,
"description"
:
"The server boots here and wires middleware before any route is reached."
}
,
{
"file"
:
"src/routes/payments.ts"
,
"line"
:
8
,
"title"
:
"Payment Routes"
,
"description"
:
"Every payments request enters through this router before hitting service logic."
}
,
{
"title"
:
"Next Steps"
,
"description"
:
"You can now follow any payment request end to end with the main anchors in place."
}
]
}
Anti-Patterns
Anti-pattern
Fix
Flat file listing
Tell a story with dependency between steps
Generic descriptions
Name the concrete code path or pattern
Guessed anchors
Verify every file and line first
Too many steps for a quick tour
Cut aggressively
First step is content-only
Anchor the first step to a real file or directory
Persona mismatch
Write for the actual reader, not a generic engineer
Best Practices
keep step count proportional to repo size and persona depth
use directory steps for orientation, file steps for substance
for PR tours, cover changed files first
for monorepos, scope to the relevant packages instead of touring everything
close with what the reader can now do, not a recap