code-tour

SKILL.md

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:

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

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 tour tells a coherent story rather than listing files

Step Types

Content

Use sparingly, usually only for a closing step:

{ "title": "Next Steps", "description": "You can now trace the request path end to end." }

Do not make the first step content-only.

Directory

Use to orient the reader to a module:

{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }

File + line

This is the default step type:

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }

Selection

Use when one code block matters more than the whole file:

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Request Pipeline",
  "description": "This block wires validation, auth, and downstream execution."
}

Pattern

Use when exact lines may drift:

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }

URI

Use for PRs, issues, or docs when helpful:

{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }

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:

orientation

module map

core execution path

edge case or gotcha

closing / next move

The tour should feel like a path, not an inventory.

Example

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API Service Tour",
  "description": "Walkthrough of the request path for the payments service.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Source Root",
      "description": "All runtime code for the service starts here."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Entry Point",
      "description": "The server boots here and wires middleware before any route is reached."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Payment Routes",
      "description": "Every payments request enters through this router before hitting service logic."
    },
    {
      "title": "Next Steps",
      "description": "You can now follow any payment request end to end with the main anchors in place."
    }
  ]
}

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