Code Tour Skill

You are creating a CodeTour — a persona-targeted, step-by-step walkthrough of a codebase that links directly to files and line numbers. CodeTour files live in .tours/ and work with the VS Code CodeTour extension.

Two scripts are bundled in scripts/:

• scripts/validate_tour.py — run after writing any tour. Checks JSON validity, file/directory existence, line numbers within bounds, pattern matches, nextTour cross-references, and narrative arc. Run it: python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
• scripts/generate_from_docs.py — when the user asks to generate from README/docs, run this first to extract a skeleton, then fill it in. Run it: python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour

Two reference files are bundled:

• references/codetour-schema.json — the authoritative JSON schema. Read it to verify any field name or type. Every field you use must conform to it.
• references/examples.md — 8 real-world CodeTour tours from production repos with annotated techniques. Read it when you want to see how a specific feature (commands, selection, view, pattern, isPrimary, multi-tour series) is used in practice.

Real-world .tour files on GitHub

These are confirmed production .tour files. Fetch one when you need a working example of a specific step type, tour-level field, or narrative structure — don't write from memory when the real thing is one fetch away.

Find more with the GitHub code search: https://github.com/search?q=path%3A**%2F*.tour+&type=code

By step type / technique demonstrated

Raw content tip: Prefix raw.githubusercontent.com and drop /blob/ for raw JSON access.

A great tour is not just annotated files. It is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Your goal is to write the tour that the right person would wish existed when they first opened this repo.

CRITICAL: Only create .tour JSON files. Never create, modify, or scaffold any other files.

Step 1: Discover the repo

Before asking the user anything, explore the codebase:

• List the root directory, read the README, and check key config files (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
• Identify the language(s), framework(s), and what the project does
• Map the folder structure 1–2 levels deep
• Find entry points: main files, index files, app bootstrapping
• Note which files actually exist — every path you write in the tour must be real

If the repo is sparse or empty, say so and work with what exists.

If the user says "generate from README" or "use the docs": run the skeleton generator first, then fill in every [TODO: ...] by reading the actual files:

python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour

Entry points by language/framework

Don't read everything — start here, then follow imports.

…