// Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
[HINT] Descarga el directorio completo de la habilidad incluyendo SKILL.md y todos los archivos relacionados
| name | code-tour |
| description | Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests. |
| origin | ECC |
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:
Only create .tour JSON files. Do not modify source code as part of this skill.
Use this skill when:
Examples:
| 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 |
Explore the repo before writing anything:
Do not start writing steps before you understand the shape of the code.
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 |
Every file path and line anchor must be real:
Never guess line numbers.
.tourWrite to:
.tours/<persona>-<focus>.tour
Keep the path deterministic and readable.
Before finishing:
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.
Use to orient the reader to a module:
{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }
This is the default step type:
{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }
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."
}
Use when exact lines may drift:
{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }
Use for PRs, issues, or docs when helpful:
{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }
Each description should answer:
Keep descriptions compact, specific, and grounded in the actual code.
Use this arc unless the task clearly needs something different:
The tour should feel like a path, not an inventory.
{
"$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-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 |
codebase-onboardingcoding-standardscouncilmicrosoft/codetour