Code Tour
Define structured VS Code CodeTour files so agents and teammates get guided walkthroughs of unfamiliar repos.
Overview
Code Tour is an agent skill most often used in Build (also Ship, Operate) that produces valid CodeTour JSON tour files for guided in-repo walkthroughs.
Install
npx skills add https://github.com/github/awesome-copilot --skill code-tourWhat is this skill?
- JSON Schema for CodeTour files with required title and steps array
- Optional git ref, primary tour flag, nextTour chaining, and stepMarker conventions
- Per-step description with optional titles and conditional when expressions
- Supports multi-tour learning paths via isPrimary and nextTour metadata
- Tour files require title and steps per JSON Schema
- Steps require description on every step object
Adoption & trust: 536 installs on skills.sh; 34.6k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You inherit or ship a codebase where READMEs do not match how files actually connect, and new contributors get lost before they can safely change anything.
Who is it for?
Indie teams documenting module boundaries, onboarding flows, or agent-assisted repo explanations in VS Code-compatible workflows.
Skip if: Builders who only need a static architecture diagram with no in-editor stepping, or projects not using the CodeTour tour format.
When should I use this skill?
You need to create or validate CodeTour tour JSON with title, steps, refs, and optional tour chaining.
What do I get? / Deliverables
You get schema-valid tour files with ordered steps, optional chaining, and git refs that the CodeTour extension can render as interactive guidance in the editor.
- Valid CodeTour JSON tour file
- Optional multi-tour sequence via nextTour
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Build because tours are authored as repo documentation alongside the code they explain. Docs is the right subphase—the deliverable is tour JSON with titles, steps, refs, and narrative—not runtime feature code.
Where it fits
Author a primary tour from app entry through auth middleware before merging a large refactor.
Attach a short tour to release notes so a reviewer can click through risky changed paths.
Rebuild a tour around the payment module after an incident so the next fix starts with accurate file context.
How it compares
Use structured tour JSON instead of unstructured chat explanations that break when the repo layout changes.
Common Questions / FAQ
Who is code-tour for?
Solo and indie developers, plus small teams, who use AI coding agents or Copilot and want version-controlled, step-by-step codebase tours aligned with the CodeTour extension schema.
When should I use code-tour?
During Build when writing internal docs; at Ship when handing off a feature area; and in Operate when you need a refresher tour before fixing production code in an unfamiliar module.
Is code-tour safe to install?
Review the Security Audits panel on this Prism page for install risk and file integrity; the skill itself describes tour file structure and does not require network or shell by default.
SKILL.md
READMESKILL.md - Code Tour
{ "$schema": "http://json-schema.org/draft-04/schema#", "title": "Schema for CodeTour tour files", "type": "object", "required": ["title", "steps"], "properties": { "title": { "type": "string", "description": "Specifies the title of the code tour." }, "description": { "type": "string", "description": "Specifies an optional description for the code tour." }, "ref": { "type": "string", "description": "Indicates the git ref (branch/commit/tag) that this tour associate with." }, "isPrimary": { "type": "boolean", "description": "Specifies whether the tour represents the primary tour for this codebase." }, "nextTour": { "type": "string", "description": "Specifies the title of the tour that is meant to follow this tour." }, "stepMarker": { "type": "string", "description": "Specifies the marker that indicates a line of code represents a step for this tour." }, "when": { "type": "string", "description": "Specifies the condition (JavaScript expression) that must be met before this tour is shown." }, "steps": { "type": "array", "description": "Specifies the list of steps that are included in the code tour.", "default": [], "items": { "type": "object", "required": ["description"], "properties": { "title": { "type": "string", "description": "An optional title for the step." }, "description": { "type": "string", "description": "Description of the step. Supports markdown." }, "file": { "type": "string", "description": "File path (relative to the workspace root) that the step is associated with." }, "directory": { "type": "string", "description": "Directory path (relative to the workspace root) that the step is associated with." }, "uri": { "type": "string", "description": "Absolute URI (https://...) associated with the step. Use for PRs, issues, docs, ADRs." }, "line": { "type": "number", "description": "Line number (1-based) that the step is associated with." }, "pattern": { "type": "string", "description": "Regex to associate the step with a line by content instead of line number. Useful when line numbers shift frequently." }, "selection": { "type": "object", "required": ["start", "end"], "description": "Text selection range associated with the step. Use when a block of code (not a single line) is the point.", "properties": { "start": { "type": "object", "required": ["line", "character"], "properties": { "line": { "type": "number", "description": "Line number (1-based) where the selection starts." }, "character": { "type": "number", "description": "Column number (1-based) where the selection starts." } } }, "end": { "type": "object", "required": ["line", "character"], "properties": { "line": { "type": "number", "description": "Line number (1-based) where the selection ends." }, "character": { "type": "number", "description": "Column number (1-based) where the selection ends." } } } } }, "view": { "type": "string", "description": "VS Code view ID to auto-focus when navigating to this step (e.g. 'terminal', 'explorer', 'problems', 'scm')." }, "commands": { "type": "array", "description": "VS Code command URIs to execute when this step