code-tour

What this skill does

# Code Tour Skill

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

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

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

### Real-world `.tour` files on GitHub

These 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

#### By step type / technique demonstrated

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

---

## Step 1: Discover the repo

Before asking the user anything, explore the codebase:

- List the root directory, read the README, and check key config files
  (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
- Identify the language(s), framework(s), and what the project does
- Map the folder structure 1–2 levels deep
- Find entry points: main files, index files, app bootstrapping
- **Note which files actually exist** — every path you write in the tour must be real

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:

```bash
python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour
```

### Entry points by language/framework

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

### Repo type variants — adjust focus accordingly

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.

### Large repo strategy

For repos with 100+ files: don't try to read everything.

1. Read entry points and the README first
2. Build a mental model of the top 5–7 modules
3. For the requested persona, identify the **2–3 modules that matter most** and read those deeply
4. For modules you're not covering, mention them in the intro step as "out of scope for this tour"
5. Use `directory` steps for areas you mapped but didn't read — they orient without requiring full knowledge

A focused 10-step tour of the right files beats a scattered 25-step tour of everything.

---

## Step 2: Read the intent — infer everything you can, ask only what you can't

**One message from the user should be enough.** Read their request and infer persona,
depth, and focus before asking anything.

### Intent map

| 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, con