From 8be3cd56e8252ed7baf94b6ce7f8764dddaf9c48 Mon Sep 17 00:00:00 2001 From: Srinivas Vaddi Date: Fri, 3 Apr 2026 02:43:59 -0400 Subject: [PATCH] feat(engineering): add code-tour skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a skill for creating CodeTour .tour files — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Co-Authored-By: Claude Opus 4.6 (1M context) --- engineering/code-tour/SKILL.md | 136 +++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 engineering/code-tour/SKILL.md diff --git a/engineering/code-tour/SKILL.md b/engineering/code-tour/SKILL.md new file mode 100644 index 0000000..ab9ebf2 --- /dev/null +++ b/engineering/code-tour/SKILL.md @@ -0,0 +1,136 @@ +--- +name: "code-tour" +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." +--- + +# 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: +- List root directory, read README, check config files +- 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 + +### 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 | + +### 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/-.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": "main", + "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 + +## The 20 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/code-review-automation` — for automated PR review workflows +- Full skill with validation scripts and schema: [code-tour repo](https://github.com/vaddisrinivas/code-tour) +- Real-world tours: [coder/code-server](https://github.com/coder/code-server/blob/main/.tours/contributing.tour)