Creates CodeTour .tour files for persona-targeted, step-by-step walkthroughs linking to files and line numbers. Supports 20 personas, all step types, for onboarding, PR reviews, bug tours, architecture overviews.
npx claudepluginhub ctr26/dotfiles --plugin awesome-copilotThis skill uses the workspace's default tool permissions.
You are creating a **CodeTour** — a persona-targeted, step-by-step walkthrough of a codebase
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.
Generates repo-specific orientation.md for learning-opportunities skill by detecting languages via manifests and exploring structure. Invoke via /orient:orient only.
Share bugs, ideas, or general feedback.
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.
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.tourTwo 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..tour files on GitHubThese 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
| 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.
Before asking the user anything, explore the codebase:
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:
python skills/code-tour/scripts/generate_from_docs.py \
--persona new-joiner \
--output .tours/skeleton.tour
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) |
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.
For repos with 100+ files: don't try to read everything.
directory steps for areas you mapped but didn't read — they orient without requiring full knowledgeA focused 10-step tour of the right files beats a scattered 25-step tour of everything.
One message from the user should be enough. Read their request and infer persona, depth, and focus before asking anything.
| 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:
Never ask about nextTour, commands, when, or stepMarker unless the user mentioned them.
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 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 |
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:
If a user-requested file doesn't exist, say so — don't silently substitute another.
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.
{
"$schema": "https://aka.ms/codetour-schema",
"title": "Descriptive Title — Persona / Goal",
"description": "One sentence: who this is for and what they'll understand after.",
"ref": "main",
"isPrimary": false,
"nextTour": "Title of follow-up tour",
"steps": []
}
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.
{ "when": "workspaceFolders[0].name === 'api'" }
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.
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./.
| 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 |
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) | 10–13 steps |
| Large (300+ files) | 12–15 steps (scoped to relevant subsystem) |
Every description should answer four questions in order. You don't need four paragraphs — but every description needs all four elements, even briefly.
S — Situation: What is the reader looking at? One sentence grounding them in context. M — Mechanism: How does this code work? What pattern, rule, or design is in play? I — Implication: Why does this matter for this persona's goal specifically? G — Gotcha: What would a smart person get wrong here? What's non-obvious, fragile, or surprising?
Descriptions should tell the reader something they couldn't learn by reading the file themselves. Name the pattern, explain the design decision, flag failure modes, and cross-reference related context.
Orientation — must be a file or directory step, never content-only.
Use "file": "README.md", "line": 1 or "directory": "src" and put your welcome text in the description.
A content-only first step (no file, directory, or uri) renders as a blank page in VS Code CodeTour — this is a known VS Code extension behaviour, not configurable.
High-level map (1–3 directory or uri steps) — major modules and how they relate. Not every folder — just what this persona needs to know.
Core path (file/line, selection, pattern, uri steps) — the specific code that matters. This is the heart of the tour. Read and narrate. Don't skim.
Closing (content) — what the reader now understands, what they can do next,
2–3 suggested follow-up tours. If nextTour is set, reference it by name here.
Don't summarize — the reader just read it. Instead, tell them what they can now do, what to avoid, and suggest 2-3 follow-up tours.
| Persona | Goal | Must cover | Avoid |
|---|---|---|---|
| Vibecoder | Get the vibe fast | Entry point, request flow, main modules. Max 8 steps. | Deep dives, edge cases |
| New joiner | Structured ramp-up | Directories, setup, business context, service boundaries. | Advanced internals |
| Bug fixer | Root cause fast | User action → trigger → fault points. Repro hints + test locations. | Architecture tours |
| RCA investigator | Why did it fail | Causality chain, side effects, race conditions, observability. | Happy path |
| Feature explainer | One feature end-to-end | UI → API → backend → storage. Feature flags, edge cases. | Unrelated features |
| PR reviewer | Review the change correctly | Change story, invariants, risky areas, reviewer checklist. URI step for PR. | Unrelated context |
| Security reviewer | Trust boundaries | Auth flow, input validation, secret handling, sensitive sinks. | Unrelated business logic |
| Refactorer | Safe restructuring | Seams, hidden deps, coupling hotspots, safe extraction order. | Feature explanations |
| External contributor | Contribute without breaking | Safe areas, code style, architecture landmines. | Deep internals |
| Tech lead / architect | Shape and rationale | Module boundaries, design tradeoffs, risk hotspots. | Line-by-line walkthroughs |
When a codebase is complex enough that one tour can't cover it well, design a series.
The nextTour field chains them: when the reader finishes one tour, VS Code offers to
launch the next automatically.
Plan the series before writing any tour. A good series has:
Set nextTour in each tour to the title of the next one (must match exactly). Each tour should be standalone enough to be useful on its own.
If asked for any of these, say clearly that it's not supported — do not suggest a workaround that doesn't exist:
| Request | Reality |
|---|---|
| Auto-advance to next step after X seconds | Not supported. Navigation is always manual — the reader clicks Next. There is no timer, delay, or autoplay step mechanic in CodeTour. |
| Embed a video or GIF in a step | Not supported. Descriptions are Markdown text only. |
| Run arbitrary shell commands | Not supported. commands only executes VS Code commands (e.g. workbench.action.terminal.focus), not shell commands. |
| Branch / conditional next step | Not supported. Tours are linear. when controls whether a tour is shown, not which step follows which. |
| Show a step without opening a file | Partially — content-only steps work, but step 1 must have a file or directory anchor or VS Code shows a blank page. |
| Anti-pattern | Fix |
|---|---|
| File listing — visiting files with "this file contains..." | Tell a story; each step should depend on the previous one |
| Generic descriptions | Name the specific pattern/gotcha unique to this codebase |
| Line number guessing | Never write a line number you didn't verify by reading the file |
| Ignoring the persona | Cut every step that doesn't serve their specific goal |
| Hallucinated files | If a file doesn't exist, skip the step |
file path is relative to the repo root (no leading / or ./)file path read and confirmed to existline number verified by reading the file (not guessed)directory is relative to the repo root and confirmed to existpattern regex would match a real line in the fileuri is a complete, real URL (https://...)ref is a real branch/tag/commit if setnextTour exactly matches the title of another .tour file if set.tour JSON files created — no source code touchedfile or directory anchor (content-only first step = blank page in VS Code)references/codetour-schema.jsonAlways run the validator immediately after writing the tour file. Do not skip this step.
python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
The validator checks:
file path exists and every line is within file boundsdirectory existspattern regex compiles and matches at least one line in the fileuri starts with https://nextTour matches an existing tour title in .tours/Fix every error before proceeding. Re-run until the validator reports ✓ or only warnings. Warnings are advisory — use your judgment. Do not show the user the tour until validation passes.
Common VS Code issues: Content-only first step renders blank (anchor to file/directory instead). Absolute or ./-prefixed paths silently fail. Out-of-bounds line numbers scroll nowhere.
If you can't run scripts, manually verify: step 1 has file/directory, all paths exist, all line numbers are in bounds, nextTour matches exactly.
Autoplay: isPrimary: true + .vscode/settings.json with { "codetour.promptForPrimaryTour": true } prompts on repo open. Omit ref for tours that should appear on any branch.
Share: For public repos, users can open tours at https://vscode.dev/github.com/<owner>/<repo> with no install.
After writing the tour, tell the user:
.tours/<name>.tour)vscode.dev URL if the repo is public (so they can share it immediately)<persona>-<focus>.tour — kebab-case, communicates both:
onboarding-new-joiner.tour
bug-fixer-payment-flow.tour
architect-overview.tour
vibecoder-quickstart.tour
pr-review-auth-refactor.tour
security-auth-boundaries.tour
concept-dependency-injection.tour
rca-login-outage.tour