code-tour
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.
- Installs
- 551
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/alirezarezvani/claude-skills --skill code-tour- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads code-tour automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.
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:
In parallel: list root directory, read README, check config files. Then: 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.
If the repo has fewer than 5 source files, create a quick-depth tour regardless of persona — there's not enough to warrant a deep one.
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 |
| (no qualifier) | new-joiner | standard |
When intent is ambiguous, default to new-joiner persona at standard depth — it's the most generally useful.
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.
{
"$schema": "https://aka.ms/codetour-schema",
"title": "Descriptive Title — Persona / Goal",
"description": "Who this is for and what they'll understand after.",
"ref": "<current-branch-or-commit>",
"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
filepath relative to repo root (no leading/or./) - Every
fileconfirmed to exist - Every
lineverified by reading the file - First step has
fileordirectoryanchor - At most 2 content-only steps
-
nextTourmatches another tour'stitleexactly if set
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
- Orientation —
fileordirectorystep (never content-only first step — blank in VS Code) - High-level map — 1-3 directory steps showing major modules
- Core path — file/line steps, the heart of the tour
- 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/pr-review-expert— for automated PR review workflows - CodeTour extension: microsoft/codetour
- Real-world tours: coder/code-server
FAQ
What does the code-tour skill do?
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.
How do I install code-tour?
Run npx skills add https://github.com/alirezarezvani/claude-skills --skill code-tour in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/code-tour/ (personal) or .claude/skills/code-tour/ (project).
Which AI agents can use code-tour?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is code-tour safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains code-tour?
It is published by alirezarezvani in alirezarezvani/claude-skills. It has 551 recorded installs.
More from alirezarezvani/claude-skills
engineering-skills
alirezarezvani/claude-skills
Index of the engineering-team skills bundle for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw, and 6 more tools. Architecture, frontend, backend, QA, DevOps, security, AI/ML, data engineering, Playwright, Stripe, AWS, MS365 (stdlib-only Python tools). Use when browsing or choosing among engineering-team role skills — load only the one specialist SKILL.md you need, never bulk-load the bundle.
finance-skills
alirezarezvani/claude-skills
Router/index for the finance skills bundled in this plugin: financial-analyst (ratio analysis, DCF valuation, budget variance, rolling forecasts), saas-metrics-coach (ARR/MRR, churn, CAC/LTV, NRR, quick ratio) and month-end-close (close calendar, reconciliations, flux review). Use when a finance request doesn't obviously match one skill and you need to pick the right one (e.g., 'analyze these financials', 'how healthy are my SaaS metrics').
marketing-skills
alirezarezvani/claude-skills
Directory and router for the marketing skills library. Use when you need to find the right marketing skill for a task, see what marketing capabilities exist, or get oriented in this plugin. 44 specialist skills across 8 pods (content, SEO + AEO, CRO, channels, growth, intelligence, sales enablement, ops), 59 stdlib Python tools. Routes to one skill — it does not execute marketing work itself.
business-growth-skills
alirezarezvani/claude-skills
Router/index for the 4 business & growth skills bundled in this plugin: customer-success-manager (health scoring, churn risk, expansion), sales-engineer (RFP analysis, competitive matrices, PoC planning), revenue-operations (pipeline, forecast accuracy, GTM efficiency), and contract-and-proposal-writer. Use when a growth/revenue request doesn't obviously match one skill and you need to pick the right one (e.g., 'which accounts are at risk', 'should we bid on this RFP').
engineering-advanced-skills
alirezarezvani/claude-skills
Index of 37 advanced engineering agent skills for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw. Use when browsing or choosing among the POWERFUL-tier engineering skills: agent design, RAG, MCP servers, CI/CD, database design, observability, security auditing, changelog/release automation, reliability (SLO/chaos/flags/operators), platform ops.
product-skills
alirezarezvani/claude-skills
Use when coordinating product work across the 12 bundled product sub-skills (RICE, OKRs, UX research, design tokens, competitive teardown, analytics, experiments, discovery, roadmaps, spec-to-repo, landing pages, SaaS scaffolding) or the 4 standalone product-team plugins (user stories, Apple HIG, code-to-PRD, research summarizer). Triggers on 'help me prioritize', 'plan a product experiment', 'we ship features nobody uses', 'run the discovery loop', 'is our OST sound'. Forks context to route to one sub-skill via a deterministic signal router and returns a digest; can also drive a continuous-discovery loop (Torres cadence tracker + OST linter as machine gates) or a full goal→plan→execute→verify→close run through the repo-wide agent-harness. Distinct from project-management (how to deliver vs what to build), marketing/landing (from-scratch pages), and engineering/agent-harness (the generic loop engine this orchestrator plugs into).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.