code-tour

What it does

The skill creates CodeTour JSON tours (.tour) that link to real files and line numbers, tailored to specific developer personas and goals. It uses two bundled scripts: scripts/validate_tour.py to validate tours after writing, and scripts/generate_from_docs.py to generate skeleton tours when generating from README/docs. Tours live in .tours/ and are designed to work with the VS Code CodeTour extension. The skill notes that CodeTour files are the only allowed outputs and that tours should reference real paths, lines, and narrative structure. It also provides reference files (references/codetour-schema.json and references/examples.md) to ensure conformance and practical examples. The trigger phrases include a variety of tour types such as onboarding, PR/tour, architecture, security, and explain-how-X tours. It mentions 20 developer personas (e.g., new joiner, bug fixer, architect, PR reviewer, vibecoder, security reviewer) and supports multiple step types (file/line, selection, pattern, uri, commands, view), plus tour-level fields like ref, isPrimary, and nextTour.

How it works

• You write a tour targeting a persona and goal; the tour is saved under .tours/ as a JSON file following the CodeTour schema.
• Two scripts reside in scripts/: validate_tour.py validates the tour JSON, existence of files/directories, line bounds, pattern matches, cross-referenced nextTour, and narrative arc; it is run with the command python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root ..
• If generating from docs, you first run generate_from_docs.py to extract a skeleton: python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour, then fill it in.
• The skill relies on two reference files: references/codetour-schema.json (the schema) and references/examples.md (production tour examples) to guide field usage and narrative structure.
• It explicitly restricts output to .tour JSON files only and advises verifying file existence and line positions for each planned step.

When to use it

Use this skill when you need a persona-targeted, narrative walkthrough of a codebase that points to real files and line numbers, such as onboarding a new joiner, reviewing a PR, conducting a security tour, architecture walkthrough, or an RCA tour. Trigger phrases include: "create a tour", "make a code tour", "generate a tour", "onboarding tour", "tour for this PR", "tour for this bug", "RCA tour", "architecture tour", "explain how X works", "vibe check", "PR review tour", "contributor guide", "help someone ramp up".

What it can touch

The skill relies on tools and scripts located under scripts/ and references the repository structure to assemble valid tour steps with fields defined in references/codetour-schema.json. It also uses .tours/ as the destination for generated tours. Steps can reference files, directories, code selections, patterns, URIs, and VS Code views, and tours may set fields like ref, isPrimary, and nextTour as part of the tour configuration.

Caveats

Tours must be JSON conforming to the codetour schema; every path/line must correspond to real files in the repository. The output is restricted to .tour JSON files. Use of stepMarker is optional and only relevant if the user asks, as it requires editing source files. The description notes that raw content and broad claims are avoided; outcomes are limited to the behavior stated (validation, skeleton generation, and generation of narrative tours).