Merge pull request #476 from vaddisrinivas/add-code-tour
feat(engineering): add code-tour skill
This commit is contained in:
Alireza Rezvani
GitHub
136
engineering/code-tour/SKILL.md
Normal file
136
engineering/code-tour/SKILL.md
Normal file
@@ -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/<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": "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)
|
||||||
Reference in New Issue
Block a user