code-tour
/code-tour
Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
- Author
- mturac ↗
- Repository
- everything-openai-codex ↗
- Licence
- MIT
- Last repository change
- 31.05.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 31.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
Triggers from the description
Original author description
Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
How it works
- When to Use
- When NOT to Use
- Workflow
- Step Types
- Writing Rule: SMIG
- Narrative Shape
- Example
- Anti-Patterns
- Best Practices
- Related Skills
SKILL.md preview
---
name: code-tour
description: Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
origin: ecc
---
# 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:
```text
.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:
```json
{ "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:
```json
{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }
```
### File + line
This is the default step type:
```json
{ "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:
```json
{
"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:
```json
{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }
```
### URI
Use for PRs, issues, or docs when helpful:
```json
{ "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:
1. orientation
2. module map
3. core execution path
4. edge case or gotcha
5. closing / next move
The tour should feel like a path, not an inventory.
## Example
```json
{
"$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`
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mturac/everything-openai-codex | 100 | MIT |
| github/awesome-copilot | 100 | MIT |
| drvoss/everything-copilot-cli | 100 | MIT |
| borghei/Claude-Skills | 100 | MIT |
| alirezarezvani/claude-skills | 100 | MIT |
| SHRIJANAGAIN/Nemo-Cli | 100 | Apache-2.0 |
| karurosux/code-tours.nvim | 100 | MIT |
| richardgill/nix | 100 | MIT |
| tmj-90/gaffer | 100 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 4e9759a0b406 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100create-code-tours
Create CodeTour .tours/*.tour files for onboarding to a software domain or bounded context, explaining Git changes through cause and effect, or walking business logic in complete control-flow blocks. Use for navigable source-code tours. - 100doc-architect
Use when generating or repairing layered AGENTS.md project guidance, updating project documentation, CLAUDE.md files, and skill module headers after changes or at session close, writing CodeTour .tour onboarding walkthroughs, or fixing Markdown lint without changing meaning. Use… - 1003d-virtual-tour
Build guided and interactive virtual tours through a 3D environment with authored camera paths, room and floor-plan navigation, orbit inspection, smooth mode handoffs, and progressive loading. Use for architectural walkthroughs, real-estate tours, museums, showrooms, and… - 100add-product-tour
Add a product tour, onboarding walkthrough, guided tour, step-by-step UI tour, or feature introduction to a React or Next.js app. Use when the user asks for a "user tour", "onboarding tour", "product walkthrough", "guided tour", "step-by-step intro", "feature tour", "first-time… - 100code-walkthrough
Explain how a feature or a code location works as a numbered walkthrough: a Mermaid sequence diagram (UI → HTTP → app → route → auth → controller → service → store → database) and a matching VS Code CodeTour whose steps highlight the exact code, with real request/response and… - 100react-joyride
Guide for implementing, configuring, and debugging React Joyride v3 guided tours. Use this skill whenever the user mentions joyride, guided tour, onboarding tour, walkthrough, tooltip tour, step-by-step guide, product tour, or wants to highlight UI elements sequentially. Also…