SkillAgentSearch skills...

code-tour

Build ordered, annotated tours of an unfamiliar codebase and keep the anchors from rotting

Install / Use

npx skills add borghei/Claude-Skills --skill code-tour

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

88/100

Supported Platforms

Universal

Our assessment of code-tour

code-tour scores 88/100 on our quality scale, 606th of 1,156 Content & Media skills we index.

Its SKILL.md is 12 KB long, well organised into 20 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.

It has 817 GitHub stars, a meaningful sign that others use it.

Substance
30/30
Structure
18/20
Description
12/15
Adoption
12/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so code-tour is actively maintained.
  • Our last check on 2026-11-01 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

code-tour compared with similar skills

All 4 of these similar skills score higher than code-tour; compare them before choosing.

SkillScoreStarsUpdatedFormat
code-tour (this skill)by borghei8881757d agoSKILL.md
siyuanby siyuan-note10047.3ktodayMCP Server
x402by browser-use100121.0k4d agoSKILL.md
algorithmic-artby anthropics100177.9k56d agoSKILL.md
pptxby anthropics100177.9k56d agoSKILL.md

Frequently asked questions

How do I install code-tour?
Run npx skills add borghei/Claude-Skills --skill code-tour. The install tabs above show the steps for each supported agent.
Which AI agents does code-tour work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is code-tour safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is code-tour still maintained?
The repository was last updated about 2 months ago, so code-tour is actively maintained.

name: code-tour description: > Build ordered, annotated tours of an unfamiliar codebase and keep the anchors from rotting. Use when onboarding an engineer, handing off a service, or explaining a subsystem before a review. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: engineering domain: developer-experience updated: 2026-07-21 tags: [onboarding, code-reading, documentation, developer-experience, handoff]

Code Tour

A guided path through a codebase, ordered so each stop makes the next one legible, and annotated with why the code is the way it is rather than what it does. The what is already on screen; the why is what takes a new engineer three weeks to reconstruct and what the person who knows it will lose in six months. Tours rot faster than any other documentation because they point at line numbers, so anchoring and validation are half this skill.

When to use this skill

  • Onboarding an engineer onto a service where reading order determines whether week one is productive or archaeological
  • Handing off ownership of a system before its author changes team or leaves
  • Explaining a subsystem ahead of a design review, so reviewers arrive with shared context
  • Documenting a surprising design whose rationale lives only in a closed pull request
  • Auditing an existing tour that has silently rotted as files moved and functions were renamed
  • Re-entering your own code after six months away, which is functionally the same problem as onboarding

Inputs the skill expects

  • The repository root, and which directories are vendored or generated
  • The audience and their starting knowledge — a backend engineer and a frontend engineer need different first stops
  • The one question the tour must leave answered ("how does a request become a row?")
  • Time budget, which sets the stop count more than anything else
  • The design decisions worth explaining, especially the ones that look wrong at first glance
  • An existing tour definition, when validating or updating rather than authoring

Clarify First

Before building the tour, confirm these inputs. If any is unknown or vague, ASK — do not assume:

  • [ ] The question the tour answers — a tour of "the codebase" has no ordering principle; a tour of "how a request becomes a row" orders itself
  • [ ] Audience and their existing knowledge — decides which stops can be skipped and which concepts need a stop of their own
  • [ ] Time budget — 30 minutes is 5-7 stops; anything longer gets abandoned midway and never resumed
  • [ ] Which decisions are worth explaining — the why-notes are the entire value; without them the tour is a file listing

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Workflows

Workflow 1 — Propose candidate stops from the repository

  1. Run the analyzer against the repo root, excluding vendored and generated directories.
  2. Read the ranked candidates. Entry points come first, then config and boundaries, then high-fan-in internals — that ordering is the analyzer's opinion about reading order.
  3. Cut ruthlessly. Any candidate you cannot write a "why it is this way" note for is a file, not a stop.
  4. Add stops the analyzer cannot see: the surprising workaround, the module that looks redundant and is not, the abstraction whose absence would be worse.
python3 engineering/code-tour/scripts/tour_propose.py \
  --repo . --max-stops 7 --exclude vendor --exclude generated --format text

Fan-in for Python comes from the AST import graph and is reliable. For other languages it is a filename-reference heuristic and will over-count common names — treat those scores as a ranked shortlist to review, not a verdict.

Workflow 2 — Write the tour and audit the notes

  1. Fill in each stop's note, question, and gotcha in the tour JSON. The note explains why; the question forces the reader to look at the code before moving on.
  2. Anchor every stop to a symbol name, not a line number. Line numbers are recorded for convenience but resolved from the symbol on every validation.
  3. Run the renderer's audit. It flags notes that only restate what the code does, notes under 20 words, and notes with no causal language.
  4. Render the document once the why-ratio clears 0.8.
python3 engineering/code-tour/scripts/tour_render.py \
  --input engineering/code-tour/assets/sample_tour.json \
  --audit-only --min-why-ratio 0.8 --format text

The shipped sample scores 83% — stop 5 fails deliberately, so you can see what a what-only note looks like next to four that explain why.

Workflow 3 — Validate the tour against the current tree

  1. Run validation before every use of the tour, and in CI on the branch that owns the code.
  2. Read the statuses: deleted and moved are broken, drifted means the anchor's body changed and the note may now be wrong, shifted is cosmetic line movement.
  3. For moved anchors, take the suggested relocations — they come from searching the tree for the anchor name.
  4. Re-freeze line numbers and fingerprints with --update once you have re-read the drifted notes.
python3 engineering/code-tour/scripts/tour_validate.py \
  --tour engineering/code-tour/assets/sample_tour.json \
  --repo engineering/code-tour --format text

Stop paths are relative to the tour's own repo root, so --repo points at the package the tour describes — here, this skill itself. Exit code is 1 when any stop is broken, which is what lets a tour live in CI. The shipped sample exits 1 on purpose: stop 6 points at a scripts/tour_export.py that was never shipped.

Decision frameworks

Choosing the first stop [PROVEN]

The first stop determines whether the reader builds a mental model or a list of facts.

| Tour purpose | First stop | Why | |--------------|-----------|-----| | "How does the system work?" | The entry point — main, the router, the CLI dispatcher | Execution order is the only ordering a newcomer already trusts | | "How do I add a feature like X?" | The most recent similar feature, end to end | Pattern-matching beats principles for a first change | | "Why is this designed this way?" | The constraint — the schema, the external contract, the SLA | Design decisions are unreadable without the constraint that forced them | | "How do I debug this?" | The observability seam — logging, error handler, trace entry | Debugging is navigation, and navigation starts at the signal |

Never open on the data model. It is where authors want to start, because it is where the domain lives, and it is where readers stall — a schema without a flow through it is a vocabulary list.

Stop count by time budget [RECOMMENDED]

| Budget | Stops | Words per note | |--------|-------|----------------| | 15 min | 3-4 | 40-60 | | 30 min | 5-7 | 50-80 | | 60 min | 8-10 | 60-100 | | Over 60 min | Split into two tours | — |

Beyond ten stops readers stop retaining and start skimming, and a skimmed tour teaches less than a well-chosen five-stop one. If the system genuinely needs fifteen stops, that is two tours with different questions, not one long one.

Anchoring strategy — what rots and what does not

| Anchor type | Rot rate | Use when | |-------------|----------|----------| | Symbol name (function, class) | Low | Default — survives every edit except a rename | | File path only | Low | The stop is about a file's existence or shape | | Distinctive string in a comment | Medium | Non-Python code with no stable symbol | | Line number | Very high | Never as the anchor; record it as a convenience only | | Line range | Very high | Never |

The tour format records line but resolves from anchor. A tour anchored on line numbers is broken by the next unrelated edit above it, which is why most tours in the wild are broken within a month of being written.

When a stop is drifted, what actually changed?

| Signal | Likely cause | Action | |--------|-------------|--------| | Fingerprint changed, name and shape same | Refactor inside the body | Re-read the note; usually still true | | Fingerprint changed, function much longer | Feature added inside the stop | Note is now incomplete — extend it or split the stop | | Anchor missing, found elsewhere in tree | Moved or extracted | Re-point the stop; check the ordering still holds | | Anchor missing everywhere | Renamed or deleted | Decide whether the concept still exists; delete the stop if not |

Anti-Patterns

The Line-Number Tour

Mistake: Anchoring stops to file paths and line numbers, so the tour points at parser.py:142. Why it happens: Line numbers are what the editor shows and what a link needs, so they are the obvious thing to record. They are also correct at the moment of writing, which makes the problem invisible until later. Instead: Anchor on the symbol name and resolve the line at validation time. Record the line as a convenience so readers can jump, but never let it be the identity of the stop. A tour that survives six months of refactoring is worth more than one that was slightly easier to write.

The What-Not-Why Tour

Mistake: Notes that describe what the code does — "this function validates the input and returns a normalized record." Why it happens: Describing behaviour is easy, feels informative, and can be done without remembering any history. Explaining why requires reconstructing a decision, which is genuinely harder. Instead: For every stop, answer one of: why is it here, why is it this way and not the obvious alternative, and what breaks if you change it. If none of the three has an interesting answer, the file does not need a stop. Run the renderer's audit — it catches notes that open by restating behaviour.

The Complete Tour

Mistake: Trying to cover every module so the reader is not left with gaps. Why it happens: Omitting things feels like negligence, especially for the author who knows what is being left out. The reader does not know, and would not have retained it anyway. Instead: Pick one question the tour answers and include only what serves it. Five stops that build one accurate mental model beat twenty that build a shallow index. Gaps get filled by the reader's first real task, which teaches better than any tour.

The Orphaned Tour

Mistake: Writing the tour in a wiki, a doc site, or an onboarding deck, separate from the repository. Why it happens: That is where onboarding material lives, and the tour is onboarding material. It also gets the tour in front of readers who never clone the repo. Instead: Keep the tour definition in the repository it describes, and validate it in CI on that repository. A tour that cannot be broken by a code change will not be updated by one either. Publish a rendered copy wherever readers look, generated from the definition rather than maintained separately.

Author-Order Stops

Mistake: Ordering stops the way the author thinks about the system — usually data model, then services, then interface. Why it happens: That is the order the system was built in and the order it lives in the author's head. It feels like the logical decomposition, and for someone who already understands it, it is. Instead: Order by what a newcomer can verify at each step. Start where execution starts, follow one real request or command through, and introduce each abstraction at the moment it first blocks understanding. The test: could the reader, after each stop, predict what the next file does? If not, a stop is missing before it.

Files

| File | Purpose | |------|---------| | scripts/tour_propose.py | Rank candidate stops by entry-point, fan-in, and boundary signals using AST and file analysis | | scripts/tour_validate.py | Resolve every anchor against the current tree; report deleted, moved, drifted, and shifted

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars817
CategoryContent
Updated1mo ago
Forks141

Languages

HTML

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium