# Tour Guide

> Plan a guided code tour for a repository topic. Use when invoking /tourguide followed by what the user wants to learn about the repo.

- Skill: `erhant/tour-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add erhant/tour-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/erhant/tour-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: erhant (https://skillmd.com/u/erhant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/erhant/tour-guide

---


Create a guided repository tour for this learning goal:

$ARGUMENTS

Your job is to research the codebase, choose the best tour stops, then present them ONE AT A TIME while building a persistent tour document with Mermaid diagrams.

Process:

1. Research the codebase: identify the main concepts, flows, or components relevant to the user's learning goal. Use the Agent tool with subagent_type "Explore" if needed.
2. Find the strongest entry points. Prefer implementation files, tests, config, and docs that clarify how the system works.
3. Build a tour plan with a reasonable number of stops, ordered from foundational context / entry points to deeper detail.
4. Choose a short kebab-case tour name derived from the learning goal (e.g. "modular-arithmetic", "auth-flow").
5. Create the tour file at `.claude/tours/{tour-name}.md` with the initial header (use Bash to mkdir -p .claude/tours first). The file should start with:

````markdown
# Tour: {Tour Title}

> {One-sentence learning goal}
>
> Date: {YYYY-MM-DD}
> Stops: {N planned}

## Overview

```mermaid
graph TD
S1["Stop 1: Title"] --> S2["Stop 2: Title"]
S2 --> S3["Stop 3: Title"]
...
```

(The overview diagram shows the full tour route as a simple flow.)
````

6. Present the tour goal, the planned stops (titles only), and the overview diagram to the user.
7. Then present ONLY the first stop:
   - Open the file in VS Code with `code -r -g '<file>:<line>'`
   - Show the stop number, title, file path, and line number
   - Explain why this stop matters and what to pay attention to
   - End with: "Press Enter to continue to the next stop, or type a question / direction to explore."
8. After presenting each stop, append it to the tour file using Edit. Each stop entry should include:
   - The stop heading, file path, and explanation
   - A Mermaid diagram that illustrates what was learned at this stop. Choose the most descriptive diagram type for the content:
     - `graph TD/LR` for architectural relationships, module dependencies, data flow
     - `classDiagram` for type hierarchies, struct fields, trait implementations
     - `sequenceDiagram` for call chains, request flows, protocol steps
     - `stateDiagram-v2` for state machines, lifecycle transitions
     - `flowchart` for algorithms, decision trees, control flow
   - The diagram should focus on what THIS stop reveals, not repeat prior diagrams.
   - Also update the overview diagram to highlight the current stop (e.g. mark visited stops with a different style).
9. STOP and wait for the user to respond. Do NOT present the next stop until the user sends a message.
10. When the user continues (Enter, "next", "continue", or any short acknowledgment), present the next stop the same way.
11. If the user asks a question or wants to explore a different angle, answer or adjust the tour accordingly.
12. After the final stop, append a summary section to the tour file and suggest follow-up questions.

Rules:

- CRITICAL: Only show ONE stop per message. Wait for user input before advancing.
- CRITICAL: Update the tour file after EVERY stop. The file should always reflect progress so far.
- Do not pick duplicate or near-duplicate stops.
- Prefer the most specific useful line, not just the top of the file.
- Keep the route coherent and minimize context switching.
- If tests explain behavior better than implementation, include them.
- If the repository does not contain enough information for a good tour, say that clearly and explain what is missing.
- If a stop depends on another stop, place the prerequisite earlier.
- Mermaid diagrams should be concise and readable (no more than ~15 nodes per diagram). Prefer clarity over completeness.

Stop format (shown to user):

### Stop N/Total — Title

**File:** `path/to/file.rs:LINE`

Why this stop matters and what to pay attention to.

```mermaid
(diagram for this stop)
```

> Press Enter to continue, or ask a question.

Tour file stop format (appended to .claude/tours/{tour-name}.md):

````markdown
## Stop N — Title

**File:** [`path/to/file.rs:LINE`](path/to/file.rs)

Explanation of what this stop covers.

```mermaid
(diagram for this stop)
```
````

Final stop format (after the last stop):

## Tour Complete

Brief summary of what was covered.

```mermaid
(A final "big picture" diagram that ties together the key concepts from the entire tour)
```

### Next Questions

List 2 to 4 useful follow-up questions the user could ask next.