code-tour

Overview of code-tour skill

What code-tour creates

The code-tour skill helps an AI agent produce CodeTour .tour JSON files for the VS Code CodeTour extension. A tour is a guided walkthrough that links explanation steps to real files and line numbers, usually stored under .tours/. The skill is designed for structured repository exploration, not code editing: its core boundary is to create tour files only and avoid modifying source code.

Best fit for Technical Writing and onboarding

Use code-tour for Technical Writing when you need an onboarding path, contributor guide, architecture walkthrough, PR review tour, security review path, root-cause analysis trail, or “explain how this works” walkthrough. It is strongest when the reader has a clear persona: new backend engineer, frontend maintainer, reviewer, incident responder, staff engineer, or non-code stakeholder who needs a curated path through implementation details.

What makes this better than a generic prompt

A generic prompt may summarize files loosely. The code-tour skill pushes the agent toward a usable artifact: persona-targeted narrative steps with concrete file and line anchors. That matters because a tour must be navigable in VS Code, must reference existing paths, and must explain why each stop matters rather than dumping a folder summary. The useful output is not “what the repo contains”; it is “where this reader should click first, next, and why.”

Adoption considerations before install

The skill has a focused SKILL.md and no extra scripts, rules, or reference packs. That makes code-tour install lightweight, but it also means quality depends heavily on repository access and prompt detail. It works best when the agent can inspect the file tree, README, config files, and source entry points. It is a poor fit if you only want prose documentation, Mermaid diagrams, source edits, or a tour for files the agent cannot read.

How to Use code-tour skill

code-tour install and repository context

Install from the source repository with your skills tooling, for example:

npx skills add alirezarezvani/claude-skills --skill code-tour

After installation, verify the skill path if needed: engineering/code-tour/skills/code-tour/SKILL.md. In the target project, the agent should first inspect the root directory, README.md, package or build config, and the top one or two folder levels before drafting. The tour should be saved as a .tour JSON file under .tours/, compatible with the VS Code CodeTour extension.

Inputs the skill needs

For strong code-tour usage, provide five things: the audience, the goal, the scope, the desired depth, and any files or feature names that must be included. Weak request: “make a tour of this repo.” Strong request: “Create a CodeTour for a new backend engineer explaining the request lifecycle for login, from route registration through validation, service logic, database access, and error handling. Keep it to 8–12 steps and anchor every step to real files and lines.”

If the tour is for Technical Writing, add the publishing purpose: onboarding doc, release note support, internal architecture guide, review aid, or incident learning artifact.

Suggested workflow for a first tour

Start with discovery, not writing. Ask the agent to identify project purpose, languages, frameworks, entry points, and important directories. Then choose a narrative path: setup-to-first-feature, request-to-response, UI-action-to-API, bug-symptom-to-root-cause, or PR-diff-to-risk. Only after that should it generate the .tour file. This sequence reduces broken anchors and prevents a shallow “folder tour” that names directories without teaching the reader how the system works.

Practical prompt pattern

Use a prompt like:

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

This works because it gives the agent a decision frame, not just a topic.

code-tour skill FAQ

When should I use code-tour instead of documentation?

Use code-tour when navigation through code is the product. Traditional documentation is better for concepts, policies, or API reference. A CodeTour is better when readers need to open files in sequence and understand relationships across routes, services, tests, configs, and entry points.

Can beginners use the code-tour skill?

Yes, but beginners should constrain the request. Ask for a small tour first: one feature, one bug path, or one architecture slice. Broad requests like “explain the entire codebase” often produce noisy tours unless the repository is tiny. For very small repositories with fewer than a handful of source files, a quick-depth tour is usually enough.

Does code-tour edit my application code?

No. The intended output is a .tour JSON file, normally placed in .tours/. The skill’s explicit boundary is to avoid source-code modification. If your workflow needs code fixes, tests, or refactors, use another engineering skill first, then use code-tour to document the resulting path.

What can block a good code-tour result?

The biggest blockers are missing repository access, vague audience, no scope limit, and unverified file paths. CodeTour steps depend on real anchors. If the agent cannot read the target files or line numbers shift heavily during active edits, generate the tour after the code stabilizes or ask for path-level anchors first and line refinement later.

How to Improve code-tour skill

Make code-tour prompts persona-specific

The fastest way to improve code-tour output is to name the reader. “New contributor” produces a different path than “security reviewer” or “technical writer preparing onboarding material.” Include what the reader already knows and what they must be able to do after the tour. This changes step selection, explanation depth, and vocabulary.

Ask for narrative, not inventory

A weak tour lists files. A strong tour tells a story: where execution starts, how data moves, where decisions happen, where risks live, and which tests prove behavior. Ask the agent to connect each stop to the previous one and to include a “why this matters” sentence per step. This is especially valuable for Technical Writing because the final artifact becomes teachable, not merely clickable.

Iterate after the first output

After the first .tour draft, review for three issues: broken or imprecise file paths, steps that are too broad, and missing transitions. Then ask for targeted revisions: “split step 4 into route and service steps,” “add the test that covers this behavior,” or “reduce frontend detail and focus on API error handling.” Iteration is usually more effective than requesting a perfect full-repo tour in one pass.

Validate anchors before sharing

Before publishing a CodeTour, open it in VS Code with the CodeTour extension and confirm that every path and line lands where expected. If the repository changes often, prefer tours tied to stable architecture files, tests, or entry points, and regenerate line numbers after large refactors. This keeps the code-tour skill useful as an onboarding asset rather than a stale map.