Use this skill to create CodeTour .tour files — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger for: "create a tour", "make a code tour", "generate a tour", "onboarding tour", "tour for this PR", "tour for this bug", "RCA tour", "architecture tour", "exp

Code Tour Skill You are creating a CodeTour — a persona targeted, step by step walkthrough of a codebase that links directly to files and line numbers. CodeTour files live in .tours/ and work with the [VS Code CodeTour extension](https://github.com/microsoft/codetour). Two scripts are bundled in scripts/ : scripts/validate tour.py — run after writing any tour. Checks JSON validity, file/directory existence, line numbers within bounds, pattern matches, nextTour cross references, and narrative arc. Run it: python ~/.agents/skills/code tour/scripts/validate tour.py .tours/<name .tour repo root . scripts/generate from docs.py — when the user asks to generate from README/docs, run this first to extract a skeleton, then fill it in. Run it: python ~/.agents/skills/code tour/scripts/generate from docs.py persona new joiner output .tours/skeleton.tour Two reference files are bundled: references/codetour schema.json — the authoritative JSON schema. Read it to verify any field name or type. Every field you use must conform to it. references/examples.md — 8 real world CodeTour tours from production repos with annotated techniques. Read it when you want to see how a specific feature ( commands , selection , view , pattern , isPrimary , multi tour series) is used in practice. Real world .tour files on GitHub These are confirmed production .tour files. Fetch one when you need a working example of a specific step type, tour level field, or narrative structure — don't write from memory when the real thing is one fetch away. Find more with the GitHub code search: https://github.com/search?q=path%3A %2F .tour+&type=code By step type / technique demonstrated What to study File URL directory + file+line (contributor onboarding) https://github.com/coder/code server/blob/main/.tours/contributing.tour selection + file+line + intro content step (accessibility project) https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code tour.tour Minimal tutorial — tight file+line narration for interactive learning https://github.com/lostintangent/rock paper scissors/blob/master/main.tour Multi tour repo with nextTour chaining (cloud native OCI walkthroughs) https://github.com/lucasjellema/cloudnative on oci 2021/blob/main/.tours/introduction.tour isPrimary: true (marks the onboarding entry point) https://github.com/nickvdyck/webbundlr/blob/main/.tours/getting started.tour pattern instead of line (regex anchored steps) https://github.com/nickvdyck/webbundlr/blob/main/.tours/architecture.tour Raw content tip: Prefix raw.githubusercontent.com and drop /blob/ for raw JSON access. A great tour is not just annotated files. It is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Your goal is to write the tour that the right person would wish existed when they first opened this repo. CRITICAL: Only create .tour JSON files. Never create, modify, or scaffold any other files. Step 1: Discover the repo Before asking the user anything, explore the codebase: List the root directory, read the README, and check key config files (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.) Identify the language(s), framework(s), and what the project does Map the folder structure 1–2 levels deep Find entry points: main files, index files, app bootstrapping Note which files actually exist — every path you write in the tour must be real If the repo is sparse or empty, say so and work with what exists. If the user says "generate from README" or "use the docs": run the skeleton generator first, then fill in every [TODO: ...] by reading the actual files: Entry points by language/framework Don't read everything — start here, then follow imports. Stack Entry points to read first Node.js / TS index.js/ts , server.js , app.js , src/main.ts , package.json (scripts) Python main.py , app.py , main .py , manage.py (Django), app/ init .py (Flask/FastAPI) Go main.go , cmd/<name /main.go , internal/ Rust src/main.rs , src/lib.rs , Cargo.toml Java / Kotlin Application.java , src/main/java/.../Main.java , build.gradle Ruby config/application.rb , config/routes.rb , app/controllers/application controller.rb PHP index.php , public/index.php , bootstrap/app.php (Laravel) Repo type variants — adjust focus accordingly The same persona asks for different things depending on what kind of repo this is: Repo type What to emphasize Typical anchor files Service / API Request lifecycle, auth, error contracts router, middleware, handler, schema Library / SDK Public API surface, extension points, versioning index/exports, types, changelog CLI tool Command parsing, config loading, output formatting main, commands/, config Monorepo Package boundaries, shared contracts, build graph root package.json/pnpm workspace, shared/, packages/ Framework Plugin system, lifecycle hooks, escape hatches core/, plugins/, lifecycle Data pipeline Source → transform → sink, schema ownership ingest/, transform/, schema/, dbt models Frontend app Component hierarchy, state management, routing pages/, store/, router, api/ For monorepos : identify the 2–3 packages most relevant to the persona's goal. Don't try to tour everything — open the tour with a step that explains how to navigate the workspace, then stay focused. Large repo strategy For repos with 100+ files: don't try to read everything. 1. Read entry points and the README first 2. Build a mental model of the top 5–7 modules 3. For the requested persona, identify the 2–3 modules that matter most and read those deeply 4. For modules you're not covering, mention them in the intro step as "out of scope for this tour" 5. Use directory steps for areas you mapped but didn't read — they orient without requiring full knowledge A focused 10 step tour of the right files beats a scattered 25 step tour of everything. Step 2: Read the intent — infer everything you can, ask only what you can't One message from the user should be enough. Read their request and infer persona, depth, and focus before asking anything. Intent map User says → Persona → Depth → Action "tour for this PR" / "PR review" / " 123" pr reviewer standard Add uri step for the PR; use ref for the branch "why did X break" / "RCA" / "incident" rca investigator standard Trace the failure causality chain "debug X" / "bug tour" / "find the bug" bug fixer standard Entry → fault points → tests "onboarding" / "new joiner" / "ramp up" new joiner standard Directories, setup, business context "quick tour" / "vibe check" / "just the gist" vibecoder quick 5–8 steps, fast path only "explain how X works" / "feature tour" feature explainer standard UI → API → backend → storage "architecture" / "tech lead" / "system design" architect deep Boundaries, decisions, tradeoffs "security" / "auth review" / "trust boundaries" security reviewer standard Auth flow, validation, sensitive sinks "refactor" / "safe to extract?" refactorer standard Seams, hidden deps, extraction order "performance" / "bottlenecks" / "slow path" performance optimizer standard Hot path, N+1, I/O, caches "contributor" / "open source onboarding" external contributor quick Safe areas, conventions, landmines "concept" / "explain pattern X" concept learner standard Concept → implementation → rationale "test coverage" / "where to add tests" test writer standard Contracts, seams, coverage gaps "how do I call the API" api consumer standard Public surface, auth, error semantics Infer silently: persona, depth, focus area, whether to add uri / ref , isPrimary . Ask only if you genuinely can't infer: "bug tour" but no bug described → ask for the bug description "feature tour" but no feature named → ask which feature "specific files" explicitly requested → honor them as required stops Never ask about nextTour , commands , when , or stepMarker unless the user mentioned them. PR tour recipe For PR tours: set "ref" to the branch, open with a uri step for the PR, cover changed files first, then unchanged but critical files, close with a reviewer checklist. User provided customization — always honor these User says What to do "cover src/auth.ts and config/db.yml " Those files are required stops "pin to the v2.3.0 tag" / "this commit: abc123" Set "ref": "v2.3.0" "link to PR 456" / pastes a URL Add a uri step at the right narrative moment "lead into the security tour when done" Set "nextTour": "Security Review" "make this the main onboarding tour" Set "isPrimary": true "open a terminal at this step" Add "commands": ["workbench.action.terminal.focus"] "deep" / "thorough" / "5 steps" / "quick" Override depth accordingly Step 3: Read the actual files — no exceptions Every file path and line number in the tour must be verified by reading the file. A tour pointing to the wrong file or a non existent line is worse than no tour. For every planned step: 1. Read the file 2. Find the exact line of the code you want to highlight 3. Understand it well enough to explain it to the target persona If a user requested file doesn't exist, say so — don't silently substitute another. Step 4: Write the tour Save to .tours/<persona <focus .tour . Read references/codetour schema.json for the authoritative field list. Every field you use must appear in that schema. Tour root Omit any field that doesn't apply to this tour. when — conditional display. A JavaScript expression evaluated at runtime. Only show this tour if the condition is true. Useful for persona specific auto launching, or hiding advanced tours until a simpler one is complete. stepMarker — embed step anchors directly in source code comments. When set, CodeTour looks for // <stepMarker comments in files and uses them as step positions instead of (or alongside) line numbers. Useful for tours on actively changing code where line numbers shift constantly. Example: set "stepMarker": "CT" and put // CT in the source file. Don't suggest this unless the user asks — it requires editing source files, which is unusual. Step types — full reference All step types: content (intro/closing, max 2), directory , file+line (workhorse), selection (code block), pattern (regex match), uri (external link), view (focus VS Code panel), commands (run VS Code commands). Path rule: "file" and "directory" must be relative to repo root. No absolute paths, no leading ./ . When to use each step type Situation Step type Tour intro or closing content "Here's what lives in this folder" directory One line tells the whole story file + line A function/class body is the point selection Line numbers shift, file is volatile pattern PR / issue / doc gives the "why" uri Reader should open terminal or explorer view or commands Step count calibration Match steps to depth and persona. These are targets, not hard limits. Depth Total steps Core path steps Notes Quick 5–8 3–5 Vibecoder, fast explorer — cut ruthlessly Standard 9–13 6–9 Most personas — breadth + enough detail Deep 14–18 10–13 Architect, RCA — every tradeoff surfaced Scale with repo size too. A 3 file CLI doesn't get 15 steps. A 200 file monolith shouldn't be squeezed into 5. Repo size Recommended standard depth Tiny (< 20 files) 5–8 steps Small (20–80 files) 8–11 steps Medium (80–300 files)

code-tour