Diffity Tour
Spin up a browser-guided code tour that answers how a feature works or walks a PR diff before you merge or onboard.
Overview
Diffity Tour is an agent skill most often used in Build (also Ship) that builds a step-by-step browser code tour from CLI commands to explain a feature or review a GitHub PR.
Install
npx skills add https://github.com/kamranahmedse/diffity --skill diffity-tourWhat is this skill?
- User-invocable `/diffity-tour` with a required topic or GitHub PR URL
- CLI workflow: `tour-start`, `tour-step`, `tour-done` with JSON responses for agent orchestration
- Browser UI with sidebar narrative and highlighted code ranges (optional end-line and annotations)
- Review mode auto-locks when the argument is a `github.com/owner/repo/pull/N` URL with PR-flags in the conclusion
- Three primary agent CLI commands documented: tour-start, tour-step, tour-done
- Review mode triggers on GitHub PR URLs matching github.com/owner/repo/pull/N
Adoption & trust: 541 installs on skills.sh; 687 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need to understand or explain how part of the codebase works, or what a PR changes, without manually clicking through dozens of unrelated files.
Who is it for?
Solo developers onboarding themselves to an unfamiliar repo, preparing merge reviews, or answering agent-driven how-does-this-work questions with a shareable tour.
Skip if: Greenfield projects with no local checkout, environments where the Diffity CLI cannot run, or teams that only need static markdown docs with no interactive navigation.
When should I use this skill?
User runs `/diffity-tour` with a question, concept, feature topic, branch walkthrough intent, or GitHub PR URL.
What do I get? / Deliverables
You get an interactive tour with ordered steps, annotations, and highlighted lines—and for PR URLs, a review-scoped narrative ending in explicit PR flags.
- Browser-openable guided tour with ordered steps
- PR review conclusion including PR-flags when started from a pull URL
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Primary shelf is build/docs because the default outcome is narrated understanding of the codebase—onboarding and feature explanation—not shipping a binary. Docs subphase fits step-by-step narratives tied to files and lines, which is how teams replace tribal knowledge with repeatable walkthroughs.
Where it fits
Tour how comments are stored and retrieved so future you does not re-discover the same files.
Step through the request lifecycle from router to persistence with line-accurate highlights.
Lock Review mode on a GitHub PR URL and end with a PR-flags checklist before merge.
How it compares
Use for narrated, line-anchored tours in the browser—not for generic architecture diagrams or MCP-only repo search without a guided step list.
Common Questions / FAQ
Who is diffity-tour for?
Developers using Claude Code, Cursor, or similar agents who want guided, file-and-line-accurate explanations of features or pull requests via the Diffity CLI.
When should I use diffity-tour?
In build/docs when documenting how authentication or data flow works; in build/backend when tracing request lifecycle; in ship/review when you pass a GitHub PR URL for a pre-merge walkthrough with PR flags.
Is diffity-tour safe to install?
The skill drives local CLI and may touch your filesystem and GitHub URLs; review the Security Audits panel on this Prism page and treat repo access like any shell-capable agent skill.
SKILL.md
READMESKILL.md - Diffity Tour
# Diffity Tour Skill You are creating a guided code tour — a narrated, step-by-step walkthrough of the codebase that answers the user's question or explains how a feature works. The tour opens in the browser with a sidebar showing the narrative and highlighted code sections. ## Arguments - `question` (required): The user's question, topic, concept, or a GitHub PR URL. Examples: - `/diffity-tour how does authentication work?` - `/diffity-tour explain the request lifecycle` - `/diffity-tour how are comments stored and retrieved?` - `/diffity-tour closures` - `/diffity-tour React hooks` - `/diffity-tour walk me through this branch before I merge` - `/diffity-tour https://github.com/owner/repo/pull/123` When the argument is a **GitHub PR URL** (matching `github.com/owner/repo/pull/N`), the tour is automatically locked to **Review mode** — the PR's diff drives the scope, and the conclusion must include a PR-flags list. See the **Review tours** section below. ## CLI Reference ``` diffity agent tour-start --topic "<text>" [--body "<text>"] --json diffity agent tour-step --tour <id> --file <path> --line <n> [--end-line <n>] --body "<text>" [--annotation "<text>"] --json diffity agent tour-done --tour <id> --json diffity list --json ``` ## Prerequisites 1. Check that `diffity` is available: run `which diffity`. If not found, install it with `npm install -g diffity`. 2. **If the argument is a GitHub PR URL**: - Check `gh` is installed and authenticated: run `gh auth status`. If not authenticated, stop and ask the user to run `gh auth login`. - Verify the current repo matches the PR's repo: run `gh repo view --json nameWithOwner -q .nameWithOwner` and confirm it matches the `owner/repo` in the URL. If it doesn't, stop and tell the user they need to be inside the PR's repository clone — diffity can't tour a PR for a repo you don't have checked out. - Start diffity against the PR: run `diffity --no-open <pr-url>` using the Bash tool with `run_in_background: true`. **The `--no-open` flag must come BEFORE the URL** — commander's `passThroughOptions()` will slurp any flag that appears after the positional URL into the refs array, skipping PR handling and producing an "unknown ref" error. This command checks out the PR's branch locally and starts a diff-scoped session. Wait 2 seconds, then run `diffity list --json` to get the port. You do **not** also need a tree instance — the diff session supports `agent tour-*` commands. 3. **Otherwise**, ensure a tree instance is running: run `diffity list --json`. - If no instance is running, start one: run `diffity tree --no-open` using the Bash tool with `run_in_background: true`, wait 2 seconds, then run `diffity list --json` to get the port. ## Instructions ### Pick a mode first Before doing anything else, decide which mode this tour belongs to. The rest of the skill branches on this choice — scope, research method, and output shape all differ by mode. Do this before any tool calls. **Shortcut:** if the argument is a GitHub PR URL (matches `github.com/owner/repo/pull/N`), skip the decision — it is locked to **Review mode**. | Mode | Use when the user asks... | Scoped by | Target steps | |---|---|---|---| | **Focused** | a narrow "how does X work?" question | one code path | 3-6 | | **Feature** | "how does this feature work?" | a feature boundary | 6-10 | | **System** | "how does the whole thing work?" | architecture | 8-15 | | **Concept** | about a programming concept | examples in the code | 3-8 | | **Review** | to audit a branch/PR/feature before merge | `git diff <base>..HEAD` | variable — cover every meaningful change | Trigger words that steer toward each mode: - **Focused**: "how does X validate", "walk me through th