Code Tour

Code Tour

Create CodeTour files — persona-targeted, step-by-step walkthroughs of a codebase that link directly to files and line numbers. CodeTour files live in .tours/ and work with the VS Code CodeTour extension.

Overview

A great tour is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Only create .tour JSON files. Never modify source code.

When to Use This Skill

• User asks to create a code tour, onboarding tour, or architecture walkthrough
• User says "tour for this PR", "explain how X works", "vibe check", "RCA tour"
• User wants a contributor guide, security review, or bug investigation walkthrough
• Any request for a structured walkthrough with file/line anchors

Core Workflow

1. Discover the repo

Before asking anything, explore the codebase:

In parallel: list root directory, read README, check config files. Then: identify language(s), framework(s), project purpose. Map folder structure 1-2 levels deep. Find entry points — every path in the tour must be real.

If the repo has fewer than 5 source files, create a quick-depth tour regardless of persona — there's not enough to warrant a deep one.

2. Infer the intent

One message should be enough. Infer persona, depth, and focus silently.

When intent is ambiguous, default to new-joiner persona at standard depth — it's the most generally useful.

3. Read actual files

Every file path and line number must be verified. A tour pointing to the wrong line is worse than no tour.

4. Write the tour

Save to .tours/<persona>-<focus>.tour.

{  "$schema": "https://aka.ms/codetour-schema",  "title": "Descriptive Title — Persona / Goal",  "description": "Who this is for and what they'll understand after.",  "ref": "<current-branch-or-commit>",  "steps": []}

Step types

Step count

Writing descriptions — SMIG formula

• S — Situation: What is the reader looking at?
• M — Mechanism: How does this code work?
• I — Implication: Why does this matter for this persona?
• G — Gotcha: What would a smart person get wrong?

5. Validate

• Every file path relative to repo root (no leading / or ./)
• Every file confirmed to exist
• Every line verified by reading the file
• First step has file or directory anchor
• At most 2 content-only steps
• nextTour matches another tour's title exactly if set

Personas

Narrative Arc

1. Orientation — file or directory step (never content-only first step — blank in VS Code)
2. High-level map — 1-3 directory steps showing major modules
3. Core path — file/line steps, the heart of the tour
4. Closing — what the reader can now do, suggested follow-ups

Anti-Patterns

Cross-References

• Related: engineering/codebase-onboarding — for broader onboarding beyond tours
• Related: engineering/pr-review-expert — for automated PR review workflows
• CodeTour extension: microsoft/codetour
• Real-world tours: coder/code-server