|
| 1 | +--- |
| 2 | +name: code-tour |
| 3 | +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. |
| 4 | +origin: ECC |
| 5 | +--- |
| 6 | + |
| 7 | +# Code Tour |
| 8 | + |
| 9 | +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. |
| 10 | + |
| 11 | +A good tour is a narrative for a specific reader: |
| 12 | +- what they are looking at |
| 13 | +- why it matters |
| 14 | +- what path they should follow next |
| 15 | + |
| 16 | +Only create `.tour` JSON files. Do not modify source code as part of this skill. |
| 17 | + |
| 18 | +## When to Use |
| 19 | + |
| 20 | +Use this skill when: |
| 21 | +- the user asks for a code tour, onboarding tour, architecture walkthrough, or PR tour |
| 22 | +- the user says "explain how X works" and wants a reusable guided artifact |
| 23 | +- the user wants a ramp-up path for a new engineer or reviewer |
| 24 | +- the task is better served by a guided sequence than a flat summary |
| 25 | + |
| 26 | +Examples: |
| 27 | +- onboarding a new maintainer |
| 28 | +- architecture tour for one service or package |
| 29 | +- PR-review walk-through anchored to changed files |
| 30 | +- RCA tour showing the failure path |
| 31 | +- security review tour of trust boundaries and key checks |
| 32 | + |
| 33 | +## When NOT to Use |
| 34 | + |
| 35 | +| Instead of code-tour | Use | |
| 36 | +| --- | --- | |
| 37 | +| A one-off explanation in chat is enough | answer directly | |
| 38 | +| The user wants prose docs, not a `.tour` artifact | `documentation-lookup` or repo docs editing | |
| 39 | +| The task is implementation or refactoring | do the implementation work | |
| 40 | +| The task is broad codebase onboarding without a tour artifact | `codebase-onboarding` | |
| 41 | + |
| 42 | +## Workflow |
| 43 | + |
| 44 | +### 1. Discover |
| 45 | + |
| 46 | +Explore the repo before writing anything: |
| 47 | +- README and package/app entry points |
| 48 | +- folder structure |
| 49 | +- relevant config files |
| 50 | +- the changed files if the tour is PR-focused |
| 51 | + |
| 52 | +Do not start writing steps before you understand the shape of the code. |
| 53 | + |
| 54 | +### 2. Infer the reader |
| 55 | + |
| 56 | +Decide the persona and depth from the request. |
| 57 | + |
| 58 | +| Request shape | Persona | Suggested depth | |
| 59 | +| --- | --- | --- | |
| 60 | +| "onboarding", "new joiner" | `new-joiner` | 9-13 steps | |
| 61 | +| "quick tour", "vibe check" | `vibecoder` | 5-8 steps | |
| 62 | +| "architecture" | `architect` | 14-18 steps | |
| 63 | +| "tour this PR" | `pr-reviewer` | 7-11 steps | |
| 64 | +| "why did this break" | `rca-investigator` | 7-11 steps | |
| 65 | +| "security review" | `security-reviewer` | 7-11 steps | |
| 66 | +| "explain how this feature works" | `feature-explainer` | 7-11 steps | |
| 67 | +| "debug this path" | `bug-fixer` | 7-11 steps | |
| 68 | + |
| 69 | +### 3. Read and verify anchors |
| 70 | + |
| 71 | +Every file path and line anchor must be real: |
| 72 | +- confirm the file exists |
| 73 | +- confirm the line numbers are in range |
| 74 | +- if using a selection, verify the exact block |
| 75 | +- if the file is volatile, prefer a pattern-based anchor |
| 76 | + |
| 77 | +Never guess line numbers. |
| 78 | + |
| 79 | +### 4. Write the `.tour` |
| 80 | + |
| 81 | +Write to: |
| 82 | + |
| 83 | +```text |
| 84 | +.tours/<persona>-<focus>.tour |
| 85 | +``` |
| 86 | + |
| 87 | +Keep the path deterministic and readable. |
| 88 | + |
| 89 | +### 5. Validate |
| 90 | + |
| 91 | +Before finishing: |
| 92 | +- every referenced path exists |
| 93 | +- every line or selection is valid |
| 94 | +- the first step is anchored to a real file or directory |
| 95 | +- the tour tells a coherent story rather than listing files |
| 96 | + |
| 97 | +## Step Types |
| 98 | + |
| 99 | +### Content |
| 100 | + |
| 101 | +Use sparingly, usually only for a closing step: |
| 102 | + |
| 103 | +```json |
| 104 | +{ "title": "Next Steps", "description": "You can now trace the request path end to end." } |
| 105 | +``` |
| 106 | + |
| 107 | +Do not make the first step content-only. |
| 108 | + |
| 109 | +### Directory |
| 110 | + |
| 111 | +Use to orient the reader to a module: |
| 112 | + |
| 113 | +```json |
| 114 | +{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." } |
| 115 | +``` |
| 116 | + |
| 117 | +### File + line |
| 118 | + |
| 119 | +This is the default step type: |
| 120 | + |
| 121 | +```json |
| 122 | +{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." } |
| 123 | +``` |
| 124 | + |
| 125 | +### Selection |
| 126 | + |
| 127 | +Use when one code block matters more than the whole file: |
| 128 | + |
| 129 | +```json |
| 130 | +{ |
| 131 | + "file": "src/core/pipeline.ts", |
| 132 | + "selection": { |
| 133 | + "start": { "line": 15, "character": 0 }, |
| 134 | + "end": { "line": 34, "character": 0 } |
| 135 | + }, |
| 136 | + "title": "Request Pipeline", |
| 137 | + "description": "This block wires validation, auth, and downstream execution." |
| 138 | +} |
| 139 | +``` |
| 140 | + |
| 141 | +### Pattern |
| 142 | + |
| 143 | +Use when exact lines may drift: |
| 144 | + |
| 145 | +```json |
| 146 | +{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" } |
| 147 | +``` |
| 148 | + |
| 149 | +### URI |
| 150 | + |
| 151 | +Use for PRs, issues, or docs when helpful: |
| 152 | + |
| 153 | +```json |
| 154 | +{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" } |
| 155 | +``` |
| 156 | + |
| 157 | +## Writing Rule: SMIG |
| 158 | + |
| 159 | +Each description should answer: |
| 160 | +- **Situation**: what the reader is looking at |
| 161 | +- **Mechanism**: how it works |
| 162 | +- **Implication**: why it matters for this persona |
| 163 | +- **Gotcha**: what a smart reader might miss |
| 164 | + |
| 165 | +Keep descriptions compact, specific, and grounded in the actual code. |
| 166 | + |
| 167 | +## Narrative Shape |
| 168 | + |
| 169 | +Use this arc unless the task clearly needs something different: |
| 170 | +1. orientation |
| 171 | +2. module map |
| 172 | +3. core execution path |
| 173 | +4. edge case or gotcha |
| 174 | +5. closing / next move |
| 175 | + |
| 176 | +The tour should feel like a path, not an inventory. |
| 177 | + |
| 178 | +## Example |
| 179 | + |
| 180 | +```json |
| 181 | +{ |
| 182 | + "$schema": "https://aka.ms/codetour-schema", |
| 183 | + "title": "API Service Tour", |
| 184 | + "description": "Walkthrough of the request path for the payments service.", |
| 185 | + "ref": "main", |
| 186 | + "steps": [ |
| 187 | + { |
| 188 | + "directory": "src", |
| 189 | + "title": "Source Root", |
| 190 | + "description": "All runtime code for the service starts here." |
| 191 | + }, |
| 192 | + { |
| 193 | + "file": "src/server.ts", |
| 194 | + "line": 12, |
| 195 | + "title": "Entry Point", |
| 196 | + "description": "The server boots here and wires middleware before any route is reached." |
| 197 | + }, |
| 198 | + { |
| 199 | + "file": "src/routes/payments.ts", |
| 200 | + "line": 8, |
| 201 | + "title": "Payment Routes", |
| 202 | + "description": "Every payments request enters through this router before hitting service logic." |
| 203 | + }, |
| 204 | + { |
| 205 | + "title": "Next Steps", |
| 206 | + "description": "You can now follow any payment request end to end with the main anchors in place." |
| 207 | + } |
| 208 | + ] |
| 209 | +} |
| 210 | +``` |
| 211 | + |
| 212 | +## Anti-Patterns |
| 213 | + |
| 214 | +| Anti-pattern | Fix | |
| 215 | +| --- | --- | |
| 216 | +| Flat file listing | Tell a story with dependency between steps | |
| 217 | +| Generic descriptions | Name the concrete code path or pattern | |
| 218 | +| Guessed anchors | Verify every file and line first | |
| 219 | +| Too many steps for a quick tour | Cut aggressively | |
| 220 | +| First step is content-only | Anchor the first step to a real file or directory | |
| 221 | +| Persona mismatch | Write for the actual reader, not a generic engineer | |
| 222 | + |
| 223 | +## Best Practices |
| 224 | + |
| 225 | +- keep step count proportional to repo size and persona depth |
| 226 | +- use directory steps for orientation, file steps for substance |
| 227 | +- for PR tours, cover changed files first |
| 228 | +- for monorepos, scope to the relevant packages instead of touring everything |
| 229 | +- close with what the reader can now do, not a recap |
| 230 | + |
| 231 | +## Related Skills |
| 232 | + |
| 233 | +- `codebase-onboarding` |
| 234 | +- `coding-standards` |
| 235 | +- `council` |
| 236 | +- official upstream format: `microsoft/codetour` |
0 commit comments