Code Tour
Generate reusable CodeTour `.tour` walkthroughs with real file and line anchors for onboarding, architecture, PR review, or RCA instead of one-off chat explanations.
Overview
Code Tour is an agent skill most often used in Build (also Ship review, Operate iterate) that creates persona-targeted CodeTour `.tour` files with real file and line anchors for guided codebase walkthroughs.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill code-tourWhat is this skill?
- Emits only CodeTour `.tour` JSON under `.tours/`—no source-code edits as part of the skill
- Persona-targeted steps: what to look at, why it matters, and what to open next
- Supports onboarding, service architecture, PR-review, RCA failure-path, and security boundary tours
- Anchors each step to real files and line ranges for IDE walkthrough UX
- Explicit routing table for when a flat chat answer or prose docs are enough instead
- Outputs only `.tour` JSON in `.tours/`
- Includes explicit when-NOT-to-use routing table
Adoption & trust: 3k installs on skills.sh; 210k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need someone to understand how a subsystem works, but a one-off chat summary disappears and does not open the right files in order.
Who is it for?
New contributors, solo maintainers handing off context, and reviewers who want a repeatable file-anchored story for one service or a focused PR.
Skip if: One-line explanations, replacing README/ADR prose, or tasks where modifying source code is the goal—use direct answers or documentation skills instead.
When should I use this skill?
User asks for a code tour, onboarding tour, architecture walkthrough, PR tour, or structured explain-how-X-works artifact better than a flat summary.
What do I get? / Deliverables
You get a committed `.tours/*.tour` narrative your agent or IDE can replay for onboarding, architecture, PR, or RCA paths without modifying application source.
- One or more `.tours/*.tour` JSON tour files
- Persona-scoped step narrative with file/line references
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build → docs because tours are durable onboarding and architecture artifacts stored under `.tours/`, even though reviewers also use them in ship and operate. Docs subphase fits guided narrative artifacts that explain how the codebase works; tours complement READMEs and ADRs without changing source.
Where it fits
Onboard yourself to a monorepo package with a maintainer-focused tour from entrypoint to data layer.
Walk a new API module’s request path with steps that jump to handlers, middleware, and tests.
Ship a PR tour that sequences only changed files so a reviewer follows intent before diving into diffs.
Document an RCA path from alert handler through retry logic for the next incident.
Tour trust boundaries, auth checks, and sensitive calls for a focused security review.
How it compares
Use instead of ad-hoc “let me explain in chat” when you need a reusable, line-anchored tour artifact rather than static Markdown alone.
Common Questions / FAQ
Who is code-tour for?
Solo and indie builders, new maintainers, and reviewers who want IDE-friendly walkthroughs anchored to real paths—not generic summaries.
When should I use code-tour?
Use it during Build docs work for onboarding and architecture tours; during Ship review for PR walkthroughs; and during Operate iterate for RCA or security boundary tours when a guided sequence beats a flat summary.
Is code-tour safe to install?
It is designed to write tour JSON only under `.tours/` without changing source; review the Security Audits panel on this page before installing in sensitive repos.
SKILL.md
READMESKILL.md - Code Tour
# 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 Pipel