Code Tour
Create CodeTour files — persona-targeted, step-by-step walkthroughs of a codebase that link directly to files and line numbers. CodeTour files live in .tours/ and work with the VS Code CodeTour extension.
Overview
A great tour is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Only create .tour JSON files. Never modify source code.
When to Use This Skill
- User asks to create a code tour, onboarding tour, or architecture walkthrough
- User says "tour for this PR", "explain how X works", "vibe check", "RCA tour"
- User wants a contributor guide, security review, or bug investigation walkthrough
- Any request for a structured walkthrough with file/line anchors
Core Workflow
1. Discover the repo
Before asking anything, explore the codebase:
In parallel: list root directory, read README, check config files.
Then: identify language(s), framework(s), project purpose. Map folder structure 1-2 levels deep. Find entry points — every path in the tour must be real.
If the repo has fewer than 5 source files, create a quick-depth tour regardless of persona — there's not enough to warrant a deep one.
2. Infer the intent
One message should be enough. Infer persona, depth, and focus silently.
| User says |
Persona |
Depth |
| "tour for this PR" |
pr-reviewer |
standard |
| "why did X break" / "RCA" |
rca-investigator |
standard |
| "onboarding" / "new joiner" |
new-joiner |
standard |
| "quick tour" / "vibe check" |
vibecoder |
quick |
| "architecture" |
architect |
deep |
| "security" / "auth review" |
security-reviewer |
standard |
| (no qualifier) |
new-joiner |
standard |
When intent is ambiguous, default to new-joiner persona at standard depth — it's the most generally useful.
3. Read actual files
Every file path and line number must be verified. A tour pointing to the wrong line is worse than no tour.
4. Write the tour
Save to .tours/<persona>-<focus>.tour.
{
"$schema": "https://aka.ms/codetour-schema",
"title": "Descriptive Title — Persona / Goal",
"description": "Who this is for and what they'll understand after.",
"ref": "<current-branch-or-commit>",
"steps": []
}
Step types
| Type |
When to use |
Example |
| Content |
Intro/closing only (max 2) |
{ "title": "Welcome", "description": "..." } |
| Directory |
Orient to a module |
{ "directory": "src/services", "title": "..." } |
| File + line |
The workhorse |
{ "file": "src/auth.ts", "line": 42, "title": "..." } |
| Selection |
Highlight a code block |
{ "file": "...", "selection": {...}, "title": "..." } |
| Pattern |
Regex match (volatile files) |
{ "file": "...", "pattern": "class App", "title": "..." } |
| URI |
Link to PR, issue, doc |
{ "uri": "https://...", "title": "..." } |
Step count
| Depth |
Steps |
Use for |
| Quick |
5-8 |
Vibecoder, fast exploration |
| Standard |
9-13 |
Most personas |
| Deep |
14-18 |
Architect, RCA |
Writing descriptions — SMIG formula
- S — Situation: What is the reader looking at?
- M — Mechanism: How does this code work?
- I — Implication: Why does this matter for this persona?
- G — Gotcha: What would a smart person get wrong?
5. Validate
Personas
| Persona |
Goal |
Must cover |
| Vibecoder |
Get the vibe fast |
Entry point, main modules. Max 8 steps. |
| New joiner |
Structured ramp-up |
Directories, setup, business context |
| Bug fixer |
Root cause fast |
Trigger -> fault points -> tests |
| RCA investigator |
Why did it fail |
Causality chain, observability anchors |
| Feature explainer |
End-to-end |
UI -> API -> backend -> storage |
| PR reviewer |
Review correctly |
Change story, invariants, risky areas |
| Architect |
Shape and rationale |
Boundaries, tradeoffs, extension points |
| Security reviewer |
Trust boundaries |
Auth flow, validation, secret handling |
| Refactorer |
Safe restructuring |
Seams, hidden deps, extraction order |
| External contributor |
Contribute safely |
Safe areas, conventions, landmines |
Narrative Arc
- Orientation —
file or directory step (never content-only first step — blank in VS Code)
- High-level map — 1-3 directory steps showing major modules
- Core path — file/line steps, the heart of the tour
- Closing — what the reader can now do, suggested follow-ups
Anti-Patterns
| Anti-pattern |
Fix |
| File listing — "this file contains the models" |
Tell a story. Each step depends on the previous. |
| Generic descriptions |
Name the specific pattern unique to this codebase. |
| Line number guessing |
Never write a line you didn't verify by reading. |
| Too many steps for quick depth |
Actually cut steps. |
| Hallucinated files |
If it doesn't exist, skip the step. |
| Recap closing — "we covered X, Y, Z" |
Tell the reader what they can now do. |
| Content-only first step |
Anchor step 1 to a file or directory. |
Cross-References
- Related:
engineering/codebase-onboarding — for broader onboarding beyond tours
- Related:
engineering/pr-review-expert — for automated PR review workflows
- CodeTour extension: microsoft/codetour
- Real-world tours: coder/code-server
Source: alirezarezvani/claude-skills → engineering/code-tour/skills/code-tour/SKILL.md
1---2name: code-tour-43description: Use when the user asks to create a CodeTour .tour file — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger for: create a tour, onboarding tour, architecture tour, PR review tour, explain how X works, vibe check, RCA tour, contributor guide, or any structured code walkthrough request.4---5
6
7# Code Tour
8
9Create **CodeTour** files — persona-targeted, step-by-step walkthroughs of a codebase that link directly to files and line numbers. CodeTour files live in `.tours/` and work with the [VS Code CodeTour extension](https://github.com/microsoft/codetour).
10
11## Overview
12
13A great tour is a **narrative** — a story told to a specific person about what matters, why it matters, and what to do next. Only create `.tour` JSON files. Never modify source code.
14
15## When to Use This Skill
16
17- User asks to create a code tour, onboarding tour, or architecture walkthrough
18- User says "tour for this PR", "explain how X works", "vibe check", "RCA tour"
19- User wants a contributor guide, security review, or bug investigation walkthrough
20- Any request for a structured walkthrough with file/line anchors
21
22## Core Workflow
23
24### 1. Discover the repo
25
26Before asking anything, explore the codebase:
27
28In parallel: list root directory, read README, check config files.
29Then: identify language(s), framework(s), project purpose. Map folder structure 1-2 levels deep. Find entry points — every path in the tour must be real.
30
31If the repo has fewer than 5 source files, create a quick-depth tour regardless of persona — there's not enough to warrant a deep one.
32
33### 2. Infer the intent
34
35One message should be enough. Infer persona, depth, and focus silently.
36
37| User says | Persona | Depth |
38|-----------|---------|-------|
39| "tour for this PR" | pr-reviewer | standard |
40| "why did X break" / "RCA" | rca-investigator | standard |
41| "onboarding" / "new joiner" | new-joiner | standard |
42| "quick tour" / "vibe check" | vibecoder | quick |
43| "architecture" | architect | deep |
44| "security" / "auth review" | security-reviewer | standard |
45| (no qualifier) | new-joiner | standard |
46
47When intent is ambiguous, default to **new-joiner** persona at **standard** depth — it's the most generally useful.
48
49### 3. Read actual files
50
51**Every file path and line number must be verified.** A tour pointing to the wrong line is worse than no tour.
52
53### 4. Write the tour
54
55Save to `.tours/<persona>-<focus>.tour`.
56
57```json
58{
59 "$schema": "https://aka.ms/codetour-schema",
60 "title": "Descriptive Title — Persona / Goal",
61 "description": "Who this is for and what they'll understand after.",
62 "ref": "<current-branch-or-commit>",
63 "steps": []
64}
65```
66
67### Step types
68
69| Type | When to use | Example |
70|------|-------------|---------|
71| **Content** | Intro/closing only (max 2) | `{ "title": "Welcome", "description": "..." }` |
72| **Directory** | Orient to a module | `{ "directory": "src/services", "title": "..." }` |
73| **File + line** | The workhorse | `{ "file": "src/auth.ts", "line": 42, "title": "..." }` |
74| **Selection** | Highlight a code block | `{ "file": "...", "selection": {...}, "title": "..." }` |
75| **Pattern** | Regex match (volatile files) | `{ "file": "...", "pattern": "class App", "title": "..." }` |
76| **URI** | Link to PR, issue, doc | `{ "uri": "https://...", "title": "..." }` |
77
78### Step count
79
80| Depth | Steps | Use for |
81|-------|-------|---------|
82| Quick | 5-8 | Vibecoder, fast exploration |
83| Standard | 9-13 | Most personas |
84| Deep | 14-18 | Architect, RCA |
85
86### Writing descriptions — SMIG formula
87
88- **S — Situation**: What is the reader looking at?
89- **M — Mechanism**: How does this code work?
90- **I — Implication**: Why does this matter for this persona?
91- **G — Gotcha**: What would a smart person get wrong?
92
93### 5. Validate
94
95- [ ] Every `file` path relative to repo root (no leading `/` or `./`)
96- [ ] Every `file` confirmed to exist
97- [ ] Every `line` verified by reading the file
98- [ ] First step has `file` or `directory` anchor
99- [ ] At most 2 content-only steps
100- [ ] `nextTour` matches another tour's `title` exactly if set
101
102## Personas
103
104| Persona | Goal | Must cover |
105|---------|------|------------|
106| **Vibecoder** | Get the vibe fast | Entry point, main modules. Max 8 steps. |
107| **New joiner** | Structured ramp-up | Directories, setup, business context |
108| **Bug fixer** | Root cause fast | Trigger -> fault points -> tests |
109| **RCA investigator** | Why did it fail | Causality chain, observability anchors |
110| **Feature explainer** | End-to-end | UI -> API -> backend -> storage |
111| **PR reviewer** | Review correctly | Change story, invariants, risky areas |
112| **Architect** | Shape and rationale | Boundaries, tradeoffs, extension points |
113| **Security reviewer** | Trust boundaries | Auth flow, validation, secret handling |
114| **Refactorer** | Safe restructuring | Seams, hidden deps, extraction order |
115| **External contributor** | Contribute safely | Safe areas, conventions, landmines |
116
117## Narrative Arc
118
1191. **Orientation** — `file` or `directory` step (never content-only first step — blank in VS Code)
1202. **High-level map** — 1-3 directory steps showing major modules
1213. **Core path** — file/line steps, the heart of the tour
1224. **Closing** — what the reader can now do, suggested follow-ups
123
124## Anti-Patterns
125
126| Anti-pattern | Fix |
127|---|---|
128| **File listing** — "this file contains the models" | Tell a story. Each step depends on the previous. |
129| **Generic descriptions** | Name the specific pattern unique to this codebase. |
130| **Line number guessing** | Never write a line you didn't verify by reading. |
131| **Too many steps** for quick depth | Actually cut steps. |
132| **Hallucinated files** | If it doesn't exist, skip the step. |
133| **Recap closing** — "we covered X, Y, Z" | Tell the reader what they can now *do*. |
134| **Content-only first step** | Anchor step 1 to a file or directory. |
135
136## Cross-References
137
138- Related: `engineering/codebase-onboarding` — for broader onboarding beyond tours
139- Related: `engineering/pr-review-expert` — for automated PR review workflows
140- CodeTour extension: [microsoft/codetour](https://github.com/microsoft/codetour)
141- Real-world tours: [coder/code-server](https://github.com/coder/code-server/blob/main/.tours/contributing.tour)
142
143---
144
145**Source:** [`alirezarezvani/claude-skills`](https://github.com/alirezarezvani/claude-skills) → `engineering/code-tour/skills/code-tour/SKILL.md`
Alireza Rezvani