Code Tour

Code tour

Create a persona-targeted CodeTour .tour file in .tours/ that links to verified repository files, line numbers, directories, selections, patterns, URIs, views, or VS Code commands and validates against the bundled schema and validator.

When to invoke

• "Create a tour for this repository."
• "Make an onboarding code tour for a new joiner."
• "Generate a PR review tour for this branch."
• "Explain how this feature works as a CodeTour."
• "Make a vibe check, bug tour, RCA tour, architecture tour, or contributor guide."

Prerequisites and context

• CodeTour files live in .tours/ and use the VS Code CodeTour extension: https://github.com/microsoft/codetour.
• Only create .tour JSON files. Never create, modify, or scaffold source files, .vscode/settings.json, docs, or any other files unless the user explicitly changes the task.
• Every path and line number in the tour must be verified by reading the actual file.
• Use references/codetour-schema.json as the authoritative field list.
• Run python harness/github-copilot/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root . after writing a tour in this repository. In installed skill locations, the same script may be under ~/.agents/skills/code-tour/scripts/validate_tour.py.

Progressive disclosure and bundled resources

Read or execute bundled resources only when needed.

Useful commands:

python harness/github-copilot/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour
python harness/github-copilot/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour
python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

Procedure

1. Discover the repo before asking questions: list the root, read the README, check key config files, map folders 1-2 levels deep, identify languages and frameworks, and find entry points.
2. Infer persona, depth, focus, ref, isPrimary, nextTour, uri, required files, and requested customizations from the user's first message. Ask only when the target bug, feature, or required file cannot be inferred.
3. Read every planned file and directory. Verify every file, directory, line, selection, and pattern before writing.
4. Write one .tours/<persona>-<focus>.tour JSON file. Use kebab-case names such as 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, or rca-login-outage.tour.
5. Validate with scripts/validate_tour.py. Fix every error. Use judgment on warnings, but never ignore invalid paths, invalid JSON, out-of-bounds lines, of-bounds validation wording, unmatched patterns, or broken nextTour references.
6. Summarize the tour path, persona, coverage, vscode.dev URL for public repos, suggested follow-up tours, and any requested files that did not exist.

Repository discovery

Start with entry points; do not read everything in large repositories.

For repos with 100+ files: read entry points and README, build a map of the top 5-7 modules, deeply read only the 2-3 modules that matter to the persona, mention out-of-scope areas in the intro, and use directory steps for areas you mapped but did not read. A focused 10-step tour beats a scattered 25-step tour.

Intent and persona mapping

Honor explicit customizations: required files such as src/auth.ts and config/db.yml, tags or commits such as v2.3.0 and abc123, PR URLs, nextTour titles, isPrimary: true, terminal focus via commands: ["workbench.action.terminal.focus"], and requested depth or step count.

Tour JSON structure

{
  "$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",
  "when": "workspaceFolders[0].name === 'api'",
  "stepMarker": "CT",
  "steps": []
}

Omit fields that do not apply. when is a JavaScript expression evaluated at runtime; it controls whether a tour is shown. stepMarker uses source comments such as // CT so CodeTour can find anchors when line numbers shift; do not suggest it unless the user asks because it requires editing source files.

Step design

All step types: content, directory, file + line, selection, pattern, uri, view, and commands.

Narrative arc

1. Orientation: must be a file, directory, or uri step, never content-only. Use README.md line 1 or a key directory and put welcome text in the description. A content-only first step renders blank in VS Code CodeTour.
2. High-level map: 1-3 directory or URI steps for major modules.
3. Core path: file/line, selection, pattern, and URI steps that tell the specific story.
4. Closing: a content step that says what the reader can now do, what to avoid, and 2-3 follow-up tours. If nextTour is set, reference it by exact title.

Step count calibration

Use the SMIG formula in every description: Situation, Mechanism, Implication, Gotcha. Tell the persona what matters, how it works, why it matters for their goal, and what a smart reader might get wrong.

Real-world references

Fetch a real .tour when you need a concrete example instead of writing from memory.

Raw content tip: prefix raw.githubusercontent.com and drop /blob/ for raw JSON access. For public repositories, users can open tours at https://vscode.dev/github.com/<owner>/<repo>.

Limits

isPrimary: true plus .vscode/settings.json containing { "codetour.promptForPrimaryTour": true } prompts on repo open, but this skill must not create or modify .vscode/settings.json unless the user explicitly requests it. Omit ref for tours intended to appear on any branch.

Gotchas

• Line number guessing is forbidden: a tour pointing to the wrong line is worse than no tour.
• No absolute or ./ paths: file and directory paths must be relative to repo root.
• A content-only first step renders blank: anchor step 1 to a real file, directory, or URI.
• A file listing is not a tour: each step should depend on the previous step and serve the persona's goal.
• nextTour must match exactly: it must equal the title of another .tour file in .tours/.
• Commands are not shell commands: use commands only for VS Code command IDs.
• Do not hallucinate files: if a user-requested file does not exist, report it explicitly.

Schema vocabulary and exact field examples

Keep these CodeTour field examples available when the user requests them: "file", "directory", "directory": "src", "file": "README.md", "line": 1, "ref", "ref": "v2.3.0", "isPrimary": true, "nextTour": "Security Review", "stepMarker": "CT", // <stepMarker>, and "commands": ["workbench.action.terminal.focus"].

Use these exact package and workflow terms when relevant: .tours/<name>.tour, <persona>-<focus>.tour, scripts/, skills/code-tour/scripts/generate_from_docs.py, README/docs, language/framework discovery, Flask/FastAPI, index.js/ts, package.json/pnpm-workspace, branch/tag/commit refs, tour-level fields, real-world examples, persona-specific auto-launching, intro/closing steps, function/class selection, deep-dive tours, end-to-end feature tours, ramp-up onboarding, step-by-step walkthroughs, by-line review, pattern/gotcha descriptions, non-obvious failure modes, non-existent files, out-of-bounds lines, and the CRITICAL rule that only .tour JSON files are created.

Output template

## CodeTour result - <tour title>

**Status:** created | blocked
**File:** `.tours/<persona>-<focus>.tour`
**Persona:** <persona>
**Depth:** quick | standard | deep

### Coverage
| Step range | Purpose | Anchors |
| --- | --- | --- |
| 1 | Orientation | `<file or directory>` |
| 2-<n> | Core path | `<files, directories, patterns, selections, URIs>` |
| <n> | Closing | content |

### Validation
- `python harness/github-copilot/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .`: pass | fail
- Paths and line numbers verified: pass | fail
- Patterns matched: pass | fail | not used
- `nextTour` cross-reference: pass | fail | not used

### Share and follow-up
- Public URL: `https://vscode.dev/github.com/<owner>/<repo>` or not available
- Suggested follow-up tours: <2-3 titles>
- Missing requested files: <none or list>

Quality gate

• Only one .tour JSON file was created or modified under .tours/.
• Every root field and step field conforms to references/codetour-schema.json.
• Every file path is relative to repo root, has no leading / or ./, was read, and exists.
• Every line number is verified and within bounds.
• Every directory path is relative to repo root and exists.
• Every pattern regex compiles and matches a real line.
• Every uri is a complete real URL beginning with https://.
• ref is a real branch, tag, or commit when set.
• nextTour exactly matches another tour title when set.
• Step 1 has a file, directory, or URI anchor.
• The tour has a narrative arc and at most 2 content-only steps.
• Every description follows SMIG and serves the selected persona.
• Step count matches requested depth and repo size.
• scripts/validate_tour.py was run and all errors were fixed.

References

• VS Code CodeTour extension
• CodeTour schema URL
• Code server contributing tour
• A11y project code tour
• Rock paper scissors main tour
• GitHub Code Search for tours