Code Tour

Code Tour

Use when the user asks to create a CodeTour .tour file — persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Trigger

Category: development Source: alirezarezvani/claude-skills

What Is Code Tour?

Code Tour is a specialized skill designed to generate step-by-step, persona-targeted walkthroughs of codebases, encapsulated in .tour files compatible with the VS Code CodeTour extension. Each Code Tour acts as an interactive narrative, guiding users through files, lines, and concepts within a repository. These tours live in the .tours/ directory and are structured as JSON files, linking directly to real files and specific line numbers. Rather than modifying source code, Code Tour provides a non-intrusive way to onboard new contributors, explain architectural decisions, review pull requests, or demystify complex subsystems via structured, context-rich guidance.

Why Use Code Tour?

Modern codebases are often intricate and intimidating, especially for newcomers or external reviewers. Documentation can quickly become outdated, and traditional onboarding often relies on tribal knowledge passed through chat or calls. Code Tour fills this gap by offering:

  • Contextual navigation: Each step in the tour references the actual files and lines, enabling direct exploration.
  • Persona targeting: Tours can be crafted for specific audiences—new hires, contributors, reviewers, or security auditors.
  • Narrative structure: Instead of static documentation, users experience a guided story, making it easier to grasp intent, architecture, and best practices.
  • Repeatable onboarding: Save time and reduce friction by capturing onboarding or review knowledge in a reusable format.

By integrating with VS Code’s CodeTour extension, these tours offer a seamless, interactive experience directly within the code editor, improving both knowledge transfer and codebase discoverability.

How to Get Started

To create a Code Tour, follow these steps:

  1. Explore the Repository: Start by listing the root directory, reading the README.md, and reviewing configuration files. Identify the languages, frameworks, and the project’s overall structure.

  2. Determine Entry Points: Map out the folder structure one to two levels deep, and locate the files and lines significant to your tour’s narrative. Every path referenced must exist within the repository.

  3. Construct the Tour File: Write a .tour JSON file that specifies each step’s title, description, file path, and line number anchors. For example:

    [
  {
    "title": "Project Entry Point",
    "description": "Let's start with the main application file.",
    "file": "src/index.js",
    "line": 1
  },
  {
    "title": "Configuration Overview",
    "description": "Here’s where environment variables are loaded.",
    "file": "config/env.js",
    "line": 5
  }
]

  4. Save and Share: Place your .tour file(s) in the .tours/ directory. Users with the CodeTour extension installed can now load and follow your walkthrough.

Key Features

  • Anchored Steps: Each step is tied to a specific file and line, ensuring users are always oriented within the codebase.
  • Persona Focus: Tours can be tailored for onboarding, architecture, security, review, or contributor guidance.
  • Non-Intrusive: Tours are stored separately from source code, avoiding clutter and merge conflicts.
  • Structured and Repeatable: Codifies best practices, explanations, and review protocols for repeat use.
  • Integration with VS Code: Fully compatible with the CodeTour extension, enabling a first-class, editor-native experience.

Best Practices

  • Tell a Story: Frame each tour as a narrative designed for a particular audience. Focus on what matters, why it matters, and actionable next steps.
  • Be Selective: Highlight critical files, architectural patterns, or problem areas rather than overwhelming users with every detail.
  • Validate Paths: Ensure every file and line referenced in the tour exists in the repository.
  • Keep Steps Concise: Each step should provide clear context and purpose—avoid unnecessary verbosity.
  • Iterate and Update: Review and revise tours as the codebase evolves to keep guidance relevant and accurate.

Important Notes

  • Code Tour produces only .tour JSON files; it never modifies source code or documentation.
  • All references must point to real files and lines—verify paths before finalizing tours.
  • Use Code Tour for any structured walkthrough request: onboarding, architecture overviews, PR reviews, RCA (root cause analysis), contributor guides, or security audits.
  • Place all tour files in the .tours/ directory at the repository root for compatibility with the VS Code CodeTour extension.
  • Tours are strictly narrative and persona-driven; tailor the experience to the intended audience for maximum impact.
  • Maintain tours as living documents—update steps when significant codebase changes occur to avoid stale guidance.