code-tour
/code-tour
Create and launch a temporary JSON-driven code tour in the user's running Neovim, with highlighted ranges, contextual buffer annotations, and an indented location list. Use when asked for a code tour or a guided walkthrough of code in nvim/tmux.
- Author
- richardgill ↗
- Repository
- nix ↗
- Licence
- MIT
- Last repository change
- 11.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 11.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Create and launch a temporary JSON-driven code tour in the user's running Neovim, with highlighted ranges, contextual buffer annotations, and an indented location list. Use when asked for a code tour or a guided walkthrough of code in nvim/tmux.
Original author description
Create and launch a temporary JSON-driven code tour in the user's running Neovim, with highlighted ranges, contextual buffer annotations, and an indented location list. Use when asked for a code tour or a guided walkthrough of code in nvim/tmux.
How it works
- Prepare the tour
- JSON format
- Shape the walkthrough
- Find the socket and launch
- Navigate and stop
SKILL.md preview
---
name: code-tour
description: Create and launch a temporary JSON-driven code tour in the user's running Neovim, with highlighted ranges, contextual buffer annotations, and an indented location list. Use when asked for a code tour or a guided walkthrough of code in nvim/tmux.
---
# Code tour
Trace the requested behavior, generate a JSON tour, and open it in the correct running Neovim through `custom.code-tour`. Do not change source contents, save buffers, install plugins, or restart the editor unless requested. The renderer creates a dedicated temporary tab and preserves the original workspace.
## Prepare the tour
1. Find the intended tmux session and its Neovim socket. Confirm the editor's working directory before resolving filenames.
2. Read the relevant code and trace the behavior from the caller's perspective. Use live buffer contents when unsaved edits may differ from disk.
3. Write `overlay/branch/<topic>-tour.json` in the repository. Use the schema below, with current line numbers.
4. Launch synchronously through `--remote-expr`. Validation errors return a nonzero exit before changing an active tour. Correct the JSON rather than bypassing validation.
5. Confirm the location list and annotations are visible. Report the JSON path and remind the user of navigation and cleanup.
## JSON format
```json
{
"title": "Starting voice recording",
"entries": [
{
"filename": "flake/modules/home-manager/dot-files/Scripts/nixos/voxtype-record",
"line": 25,
"end_line": 30,
"location_list_text": "Start recording: lower playback volume, then signal Voxtype",
"buffer_annotation": "Keep playback subdued until recording stops, not just until this wrapper exits"
},
{
"filename": "flake/modules/home-manager/dot-files/Scripts/nixos/voxtype-record",
"line": 12,
"end_line": 16,
"location_list_text": " duck_sink(): preserve the current volume before lowering it",
"buffer_annotation": "Preserve the user's volume so recording doesn't leave audio permanently quieter"
}
]
}
```
| Field | Meaning |
|---|---|
| `title` | Required string, used as the location-list title. |
| `entries` | Required nonempty array, ordered as the reader should follow the code. |
| `filename` | Required file path, relative to the original Neovim window's working directory or absolute. |
| `line` | Required positive, 1-based starting line and jump target. The cursor lands on its first nonblank character. |
| `end_line` | Optional inclusive highlight end, at least `line`; defaults to `line`. |
| `location_list_text` | Required location-list description. Leading spaces are preserved verbatim. |
| `buffer_annotation` | Optional short, single-line virtual text beside the starting line. Omit it when it adds no useful context; the range still gets highlighted and listed. |
Do not add other fields, step numbers, anchors, explicit depths, or nested children. The example's line numbers are illustrative: verify them against the current source before using it.
## Shape the walkthrough
- Start at a user-facing entry point, then follow meaningful calls, branches, state transitions, and side effects. Separate setup and parallel status paths from actual nested calls.
- Indent `location_list_text` by two spaces per call depth when entering a callee. Dedent when returning to a sibling or the caller. Keep the array flat; indentation is presentation, not a generated call graph.
- Prefer repo-relative filenames. The renderer appends `basename:line` to each list row, so do not repeat the path there. Mention the subsystem or directory in the description when basenames would be ambiguous.
- Prefer fewer important, cohesive ranges: a function, branch, or meaningful block. Do not turn every statement in one file into a separate entry. Add a callee entry only when seeing its implementation explains something important.
- Use `location_list_text` to orient the reader: what role does this range play in the larger flow? Use `buffer_annotation` to reveal intent, an invariant, a tradeoff, a surprising consequence, or an external boundary.
- Avoid annotations that merely translate syntax, such as `save volume -> set output to 0.1`. Prefer context, such as `Preserve the user's volume so recording doesn't leave audio permanently quieter`. Ground claims in the code; do not invent motivation or repeat the list description.
- Keep annotations brief and insightful. Omit low-value annotations rather than filling every range with text. Do not add synthetic numbered labels or a repetitive `Tour:` prefix.
## Find the socket and launch
The main Neovim in a tmux session normally owns the session's `NVIM_SOCKET`. Use the requested session; do not assume the agent's session is the target.
```sh
# Example target: nix-private, editor in window 1.
SESSION=nix-private
SOCKET=$(tmux show-environment -t "$SESSION" NVIM_SOCKET | cut -d= -f2-)
test -S "$SOCKET"
# Confirm this is the intended repository/editor.
nvim --server "$SOCKET" --remote-expr 'getcwd()'
# The JSON path resolves against Neovim's current working directory.
nvim --server "$SOCKET" --remote-expr \
"luaeval(\"require('custom.code-tour').open('overlay/branch/example-tour.json')\")"
```
For the current tmux session, obtain its name with `tmux display-message -p '#{session_name}'`. An absolute JSON path avoids ambiguity if the editor's working directory differs from the shell's. Use safe quoting for paths; do not interpolate unescaped arbitrary strings into Lua expressions.
If `NVIM_SOCKET` is absent or stale, inspect the requested editor pane and match its process ancestry to a Neovim `--listen` socket. Do not use the first Neovim process you find:
```sh
tmux list-panes -t "$SESSION:1" -F '#{pane_pid} #{pane_current_command}'
ps -eo pid,ppid,args | rg '[n]vim.*--listen'
```
A successful launch returns the entry count. Opening a valid new tour replaces the active one rather than accumulating tabs. Invalid JSON leaves the existing tour untouched. External-file-change recovery is out of scope; regenerate a tour when its coordinates become stale.
## Navigate and stop
Inside the tour tab, in normal mode:
- `l` / `L`: next / previous entry, wrapping without an explicit count.
- `]l` / `[l`: the underlying location-list navigation, also available outside tours. Count-prefixed navigation keeps native behavior and does not wrap.
- `[L` / `]L`: first / last entry.
- Enter on a location-list row: jump to that entry.
- `q` or `:CodeTourClear`: remove annotations, close the temporary tab, and return to the original workspace. Prior global mappings are restored when leaving the tour tab; buffer-local mappings are left untouched.
- `:lclose` / `:lopen`: hide / reopen only the location-list window, without stopping the tour.
Stop programmatically:
```sh
nvim --server "$SOCKET" --remote-expr \
"luaeval(\"require('custom.code-tour').clear()\")"
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · richardgill/nix | 100 | MIT |
| github/awesome-copilot | 100 | MIT |
| drvoss/everything-copilot-cli | 100 | MIT |
| borghei/Claude-Skills | 100 | MIT |
| alirezarezvani/claude-skills | 100 | MIT |
| SHRIJANAGAIN/Nemo-Cli | 100 | Apache-2.0 |
| karurosux/code-tours.nvim | 100 | MIT |
| tmj-90/gaffer | 100 | Apache-2.0 |
| ysyecust/everything-claude-code | 100 | MIT |
Identical content appears in 5 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 39d180b3991c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100nvim-tour
Teach a codebase step by step as a live guided course inside the user's Neovim. The agent writes the course, the bundled plugin (loaded ad hoc, never installed) shows each step beside the code, and the user sends questions back from Neovim. Use when the user asks to be taught,… - 100take-tour
Runs the agent-guided tour of Microbus using examples. Use when the user asks to take the tour. - 100nvim-code-review
Read and answer code review comments a human left in Neovim (code-review.nvim). Use when the user says "check comments", "address my review comments", or mentions code-review threads. - 100nvim-install
Install Neovim and stand up the nvim-fredrik config in the Claude Code web sandbox (the cloud environment), where no Neovim exists. Use this before testing any Neovim config change in a web session, e.g. checking out a PR branch that touches nvim-fredrik and observing its… - 100add-onboarding-tour
Add a first-run guided tour, product walkthrough, coachmarks, or empty-state mock/example data to a Lightdash frontend feature. Use when the user wants to onboard users to a page, add a "Take the tour" flow, explain an unfamiliar UI, or show sample data on an empty page. - 100add-product-tour
Add a product tour, onboarding walkthrough, guided tour, step-by-step UI tour, or feature introduction to a React or Next.js app. Use when the user asks for a "user tour", "onboarding tour", "product walkthrough", "guided tour", "step-by-step intro", "feature tour", "first-time…