AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

code-tour

Use when asked for a CodeTour .tour file or a step-by-step code walkthrough (onboarding, architecture, PR review, how X works). Writes persona-targeted steps that link to real files and line numbers, checked to exist.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--code-tour at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 1

SKILL.md

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 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

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/pr-review-expert — for automated PR review workflows
  • CodeTour extension: microsoft/codetour
  • Real-world tours: coder/code-server