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](https://github.com/microsoft/codetour).

## 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.

| User says | Persona | Depth |
|-----------|---------|-------|
| "tour for this PR" | pr-reviewer | standard |
| "why did X break" / "RCA" | rca-investigator | standard |
| "onboarding" / "new joiner" | new-joiner | standard |
| "quick tour" / "vibe check" | vibecoder | quick |
| "architecture" | architect | deep |
| "security" / "auth review" | security-reviewer | standard |
| (no qualifier) | new-joiner | standard |

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`.

```json
{
  "$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

| Type | When to use | Example |
|------|-------------|---------|
| **Content** | Intro/closing only (max 2) | `{ "title": "Welcome", "description": "..." }` |
| **Directory** | Orient to a module | `{ "directory": "src/services", "title": "..." }` |
| **File + line** | The workhorse | `{ "file": "src/auth.ts", "line": 42, "title": "..." }` |
| **Selection** | Highlight a code block | `{ "file": "...", "selection": {...}, "title": "..." }` |
| **Pattern** | Regex match (volatile files) | `{ "file": "...", "pattern": "class App", "title": "..." }` |
| **URI** | Link to PR, issue, doc | `{ "uri": "https://...", "title": "..." }` |

### Step count

| Depth | Steps | Use for |
|-------|-------|---------|
| Quick | 5-8 | Vibecoder, fast exploration |
| Standard | 9-13 | Most personas |
| Deep | 14-18 | Architect, RCA |

### 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

| Persona | Goal | Must cover |
|---------|------|------------|
| **Vibecoder** | Get the vibe fast | Entry point, main modules. Max 8 steps. |
| **New joiner** | Structured ramp-up | Directories, setup, business context |
| **Bug fixer** | Root cause fast | Trigger -> fault points -> tests |
| **RCA investigator** | Why did it fail | Causality chain, observability anchors |
| **Feature explainer** | End-to-end | UI -> API -> backend -> storage |
| **PR reviewer** | Review correctly | Change story, invariants, risky areas |
| **Architect** | Shape and rationale | Boundaries, tradeoffs, extension points |
| **Security reviewer** | Trust boundaries | Auth flow, validation, secret handling |
| **Refactorer** | Safe restructuring | Seams, hidden deps, extraction order |
| **External contributor** | Contribute safely | Safe areas, conventions, landmines |

## 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

| Anti-pattern | Fix |
|---|---|
| **File listing** — "this file contains the models" | Tell a story. Each step depends on the previous. |
| **Generic descriptions** | Name the specific pattern unique to this codebase. |
| **Line number guessing** | Never write a line you didn't verify by reading. |
| **Too many steps** for quick depth | Actually cut steps. |
| **Hallucinated files** | If it doesn't exist, skip the step. |
| **Recap closing** — "we covered X, Y, Z" | Tell the reader what they can now *do*. |
| **Content-only first step** | Anchor step 1 to a file or directory. |

## 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](https://github.com/microsoft/codetour)
- Real-world tours: [coder/code-server](https://github.com/coder/code-server/blob/main/.tours/contributing.tour)

{
  "format": "aiskill/v1",
  "skill": {
    "name": "code-tour",
    "slug": "code-tour",
    "version": "1.0.0",
    "description": "Use when the user asks to create a CodeTour .tour file — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger for: create a tour, onboarding tour, architecture tour, PR review tour, explain how X works, vibe check, RCA tour, contributor guide, or any structured code walkthrough request.",
    "category": "Development",
    "tags": [
      "dev-workflow"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Code Tour\r\n\r\nCreate **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](https://github.com/microsoft/codetour).\r\n\r\n## Overview\r\n\r\nA 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.\r\n\r\n## When to Use This Skill\r\n\r\n- User asks to create a code tour, onboarding tour, or architecture walkthrough\r\n- User says \"tour for this PR\", \"explain how X works\", \"vibe check\", \"RCA tour\"\r\n- User wants a contributor guide, security review, or bug investigation walkthrough\r\n- Any request for a structured walkthrough with file/line anchors\r\n\r\n## Core Workflow\r\n\r\n### 1. Discover the repo\r\n\r\nBefore asking anything, explore the codebase:\r\n\r\nIn parallel: list root directory, read README, check config files.\r\nThen: 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.\r\n\r\nIf 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.\r\n\r\n### 2. Infer the intent\r\n\r\nOne message should be enough. Infer persona, depth, and focus silently.\r\n\r\n| User says | Persona | Depth |\r\n|-----------|---------|-------|\r\n| \"tour for this PR\" | pr-reviewer | standard |\r\n| \"why did X break\" / \"RCA\" | rca-investigator | standard |\r\n| \"onboarding\" / \"new joiner\" | new-joiner | standard |\r\n| \"quick tour\" / \"vibe check\" | vibecoder | quick |\r\n| \"architecture\" | architect | deep |\r\n| \"security\" / \"auth review\" | security-reviewer | standard |\r\n| (no qualifier) | new-joiner | standard |\r\n\r\nWhen intent is ambiguous, default to **new-joiner** persona at **standard** depth — it's the most generally useful.\r\n\r\n### 3. Read actual files\r\n\r\n**Every file path and line number must be verified.** A tour pointing to the wrong line is worse than no tour.\r\n\r\n### 4. Write the tour\r\n\r\nSave to `.tours/<persona>-<focus>.tour`.\r\n\r\n```json\r\n{\r\n  \"$schema\": \"https://aka.ms/codetour-schema\",\r\n  \"title\": \"Descriptive Title — Persona / Goal\",\r\n  \"description\": \"Who this is for and what they'll understand after.\",\r\n  \"ref\": \"<current-branch-or-commit>\",\r\n  \"steps\": []\r\n}\r\n```\r\n\r\n### Step types\r\n\r\n| Type | When to use | Example |\r\n|------|-------------|---------|\r\n| **Content** | Intro/closing only (max 2) | `{ \"title\": \"Welcome\", \"description\": \"...\" }` |\r\n| **Directory** | Orient to a module | `{ \"directory\": \"src/services\", \"title\": \"...\" }` |\r\n| **File + line** | The workhorse | `{ \"file\": \"src/auth.ts\", \"line\": 42, \"title\": \"...\" }` |\r\n| **Selection** | Highlight a code block | `{ \"file\": \"...\", \"selection\": {...}, \"title\": \"...\" }` |\r\n| **Pattern** | Regex match (volatile files) | `{ \"file\": \"...\", \"pattern\": \"class App\", \"title\": \"...\" }` |\r\n| **URI** | Link to PR, issue, doc | `{ \"uri\": \"https://...\", \"title\": \"...\" }` |\r\n\r\n### Step count\r\n\r\n| Depth | Steps | Use for |\r\n|-------|-------|---------|\r\n| Quick | 5-8 | Vibecoder, fast exploration |\r\n| Standard | 9-13 | Most personas |\r\n| Deep | 14-18 | Architect, RCA |\r\n\r\n### Writing descriptions — SMIG formula\r\n\r\n- **S — Situation**: What is the reader looking at?\r\n- **M — Mechanism**: How does this code work?\r\n- **I — Implication**: Why does this matter for this persona?\r\n- **G — Gotcha**: What would a smart person get wrong?\r\n\r\n### 5. Validate\r\n\r\n- [ ] Every `file` path relative to repo root (no leading `/` or `./`)\r\n- [ ] Every `file` confirmed to exist\r\n- [ ] Every `line` verified by reading the file\r\n- [ ] First step has `file` or `directory` anchor\r\n- [ ] At most 2 content-only steps\r\n- [ ] `nextTour` matches another tour's `title` exactly if set\r\n\r\n## Personas\r\n\r\n| Persona | Goal | Must cover |\r\n|---------|------|------------|\r\n| **Vibecoder** | Get the vibe fast | Entry point, main modules. Max 8 steps. |\r\n| **New joiner** | Structured ramp-up | Directories, setup, business context |\r\n| **Bug fixer** | Root cause fast | Trigger -> fault points -> tests |\r\n| **RCA investigator** | Why did it fail | Causality chain, observability anchors |\r\n| **Feature explainer** | End-to-end | UI -> API -> backend -> storage |\r\n| **PR reviewer** | Review correctly | Change story, invariants, risky areas |\r\n| **Architect** | Shape and rationale | Boundaries, tradeoffs, extension points |\r\n| **Security reviewer** | Trust boundaries | Auth flow, validation, secret handling |\r\n| **Refactorer** | Safe restructuring | Seams, hidden deps, extraction order |\r\n| **External contributor** | Contribute safely | Safe areas, conventions, landmines |\r\n\r\n## Narrative Arc\r\n\r\n1. **Orientation** — `file` or `directory` step (never content-only first step — blank in VS Code)\r\n2. **High-level map** — 1-3 directory steps showing major modules\r\n3. **Core path** — file/line steps, the heart of the tour\r\n4. **Closing** — what the reader can now do, suggested follow-ups\r\n\r\n## Anti-Patterns\r\n\r\n| Anti-pattern | Fix |\r\n|---|---|\r\n| **File listing** — \"this file contains the models\" | Tell a story. Each step depends on the previous. |\r\n| **Generic descriptions** | Name the specific pattern unique to this codebase. |\r\n| **Line number guessing** | Never write a line you didn't verify by reading. |\r\n| **Too many steps** for quick depth | Actually cut steps. |\r\n| **Hallucinated files** | If it doesn't exist, skip the step. |\r\n| **Recap closing** — \"we covered X, Y, Z\" | Tell the reader what they can now *do*. |\r\n| **Content-only first step** | Anchor step 1 to a file or directory. |\r\n\r\n## Cross-References\r\n\r\n- Related: `engineering/codebase-onboarding` — for broader onboarding beyond tours\r\n- Related: `engineering/pr-review-expert` — for automated PR review workflows\r\n- CodeTour extension: [microsoft/codetour](https://github.com/microsoft/codetour)\r\n- Real-world tours: [coder/code-server](https://github.com/coder/code-server/blob/main/.tours/contributing.tour)",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The code-tour/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/code-tour",
    "exported_at": "2026-11-03T07:41:42.186Z"
  }
}

format: aiskill/v1
skill:
  name: code-tour
  slug: code-tour
  version: 1.0.0
  description: >-
    Use when the user asks to create a CodeTour .tour file — persona-targeted, step-by-step
    walkthroughs that link to real files and line numbers. Trigger for: create a tour, onboarding
    tour, architecture tour, PR review tour, explain how X works, vibe check, RCA tour, contributor
    guide, or any structured code walkthrough request.
  category: Development
  tags:
    - dev-workflow
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Code Tour\r\n\r\nCreate **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](https://github.com/microsoft/codetour).\r\n\r\n## Overview\r\n\r\nA 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.\r\n\r\n## When to Use This Skill\r\n\r\n- User asks to create a code tour, onboarding tour, or architecture walkthrough\r\n- User says \"tour for this PR\", \"explain how X works\", \"vibe check\", \"RCA tour\"\r\n- User wants a contributor guide, security review, or bug investigation walkthrough\r\n- Any request for a structured walkthrough with file/line anchors\r\n\r\n## Core Workflow\r\n\r\n### 1. Discover the repo\r\n\r\nBefore asking anything, explore the codebase:\r\n\r\nIn parallel: list root directory, read README, check config files.\r\nThen: 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.\r\n\r\nIf 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.\r\n\r\n### 2. Infer the intent\r\n\r\nOne message should be enough. Infer persona, depth, and focus silently.\r\n\r\n| User says | Persona | Depth |\r\n|-----------|---------|-------|\r\n| \"tour for this PR\" | pr-reviewer | standard |\r\n| \"why did X break\" / \"RCA\" | rca-investigator | standard |\r\n| \"onboarding\" / \"new joiner\" | new-joiner | standard |\r\n| \"quick tour\" / \"vibe check\" | vibecoder | quick |\r\n| \"architecture\" | architect | deep |\r\n| \"security\" / \"auth review\" | security-reviewer | standard |\r\n| (no qualifier) | new-joiner | standard |\r\n\r\nWhen intent is ambiguous, default to **new-joiner** persona at **standard** depth — it's the most generally useful.\r\n\r\n### 3. Read actual files\r\n\r\n**Every file path and line number must be verified.** A tour pointing to the wrong line is worse than no tour.\r\n\r\n### 4. Write the tour\r\n\r\nSave to `.tours/<persona>-<focus>.tour`.\r\n\r\n```json\r\n{\r\n  \"$schema\": \"https://aka.ms/codetour-schema\",\r\n  \"title\": \"Descriptive Title — Persona / Goal\",\r\n  \"description\": \"Who this is for and what they'll understand after.\",\r\n  \"ref\": \"<current-branch-or-commit>\",\r\n  \"steps\": []\r\n}\r\n```\r\n\r\n### Step types\r\n\r\n| Type | When to use | Example |\r\n|------|-------------|---------|\r\n| **Content** | Intro/closing only (max 2) | `{ \"title\": \"Welcome\", \"description\": \"...\" }` |\r\n| **Directory** | Orient to a module | `{ \"directory\": \"src/services\", \"title\": \"...\" }` |\r\n| **File + line** | The workhorse | `{ \"file\": \"src/auth.ts\", \"line\": 42, \"title\": \"...\" }` |\r\n| **Selection** | Highlight a code block | `{ \"file\": \"...\", \"selection\": {...}, \"title\": \"...\" }` |\r\n| **Pattern** | Regex match (volatile files) | `{ \"file\": \"...\", \"pattern\": \"class App\", \"title\": \"...\" }` |\r\n| **URI** | Link to PR, issue, doc | `{ \"uri\": \"https://...\", \"title\": \"...\" }` |\r\n\r\n### Step count\r\n\r\n| Depth | Steps | Use for |\r\n|-------|-------|---------|\r\n| Quick | 5-8 | Vibecoder, fast exploration |\r\n| Standard | 9-13 | Most personas |\r\n| Deep | 14-18 | Architect, RCA |\r\n\r\n### Writing descriptions — SMIG formula\r\n\r\n- **S — Situation**: What is the reader looking at?\r\n- **M — Mechanism**: How does this code work?\r\n- **I — Implication**: Why does this matter for this persona?\r\n- **G — Gotcha**: What would a smart person get wrong?\r\n\r\n### 5. Validate\r\n\r\n- [ ] Every `file` path relative to repo root (no leading `/` or `./`)\r\n- [ ] Every `file` confirmed to exist\r\n- [ ] Every `line` verified by reading the file\r\n- [ ] First step has `file` or `directory` anchor\r\n- [ ] At most 2 content-only steps\r\n- [ ] `nextTour` matches another tour's `title` exactly if set\r\n\r\n## Personas\r\n\r\n| Persona | Goal | Must cover |\r\n|---------|------|------------|\r\n| **Vibecoder** | Get the vibe fast | Entry point, main modules. Max 8 steps. |\r\n| **New joiner** | Structured ramp-up | Directories, setup, business context |\r\n| **Bug fixer** | Root cause fast | Trigger -> fault points -> tests |\r\n| **RCA investigator** | Why did it fail | Causality chain, observability anchors |\r\n| **Feature explainer** | End-to-end | UI -> API -> backend -> storage |\r\n| **PR reviewer** | Review correctly | Change story, invariants, risky areas |\r\n| **Architect** | Shape and rationale | Boundaries, tradeoffs, extension points |\r\n| **Security reviewer** | Trust boundaries | Auth flow, validation, secret handling |\r\n| **Refactorer** | Safe restructuring | Seams, hidden deps, extraction order |\r\n| **External contributor** | Contribute safely | Safe areas, conventions, landmines |\r\n\r\n## Narrative Arc\r\n\r\n1. **Orientation** — `file` or `directory` step (never content-only first step — blank in VS Code)\r\n2. **High-level map** — 1-3 directory steps showing major modules\r\n3. **Core path** — file/line steps, the heart of the tour\r\n4. **Closing** — what the reader can now do, suggested follow-ups\r\n\r\n## Anti-Patterns\r\n\r\n| Anti-pattern | Fix |\r\n|---|---|\r\n| **File listing** — \"this file contains the models\" | Tell a story. Each step depends on the previous. |\r\n| **Generic descriptions** | Name the specific pattern unique to this codebase. |\r\n| **Line number guessing** | Never write a line you didn't verify by reading. |\r\n| **Too many steps** for quick depth | Actually cut steps. |\r\n| **Hallucinated files** | If it doesn't exist, skip the step. |\r\n| **Recap closing** — \"we covered X, Y, Z\" | Tell the reader what they can now *do*. |\r\n| **Content-only first step** | Anchor step 1 to a file or directory. |\r\n\r\n## Cross-References\r\n\r\n- Related: `engineering/codebase-onboarding` — for broader onboarding beyond tours\r\n- Related: `engineering/pr-review-expert` — for automated PR review workflows\r\n- CodeTour extension: [microsoft/codetour](https://github.com/microsoft/codetour)\r\n- Real-world tours: [coder/code-server](https://github.com/coder/code-server/blob/main/.tours/contributing.tour)"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The code-tour/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/code-tour
  exported_at: "2026-11-03T07:41:42.186Z"