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. Use when the user asks for a code tour, onboarding walkthrough, PR

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 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: 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: Tour type Set ref to PR tour the PR branch — never the base branch Onboarding / architecture the branch the reader will be on (often main ), or leave it out Not sure leave ref out, so CodeTour reads files straight from disk 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: Do not make the first step content only. Directory Use to orient the reader to a module: File + line This is the default step type: Selection Use when one code block matters more than the whole file: Pattern Use when exact lines may drift: URI Use for PRs, issues, or docs when helpful: 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: 1. orientation 2. module map 3. core execution path 4. edge case or gotcha 5. closing / next move The tour should feel like a path, not an inventory. Example 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 Related Skills codebase onboarding coding standards council official upstream format: microsoft/codetour

code-tour