code-tour
by affaan-mcode-tour creates reusable CodeTour .tour files with real file and line anchors. Use the code-tour skill for onboarding tours, architecture walkthroughs, PR tours, RCA paths, and code-tour for Technical Writing when you need a guided sequence instead of a flat summary.
This skill scores 78/100, which means it is a solid directory listing candidate for users who want reusable, file-anchored code walkthrough artifacts rather than one-off chat explanations. The repository gives clear intent, trigger conditions, boundaries, and output format expectations, so an agent is likely to invoke it correctly and produce a more structured result than a generic prompt, though adoption would be easier with concrete examples and install/use instructions.
- Strong triggerability: the skill explicitly names when to use it for onboarding, architecture, PR, RCA, and security-review tours.
- Good operational boundaries: it says tours belong in `.tours/`, must be CodeTour `.tour` JSON, and must not modify source code.
- Useful agent leverage: it turns vague "explain how this works" requests into a reusable, persona-targeted walkthrough with real file and line anchors.
- No install command or support files are provided, so users must infer setup and integration details from the skill text alone.
- The evidence shows guidance-heavy documentation but no bundled example `.tour` files, schemas, or helper assets to reduce formatting guesswork.
Overview of code-tour skill
What the code-tour skill does
The code-tour skill creates reusable CodeTour .tour files that walk a reader through a repository using real file paths and line ranges. Instead of a one-off chat explanation, it produces an artifact in .tours/ that opens as a guided sequence in CodeTour-compatible tools.
Best-fit users and jobs-to-be-done
This skill fits maintainers, reviewers, and technical writers who need a structured path through code: onboarding tours, architecture tours, PR walkthroughs, RCA trails, or security review paths. The real job is not “summarize the repo,” but “guide a specific reader through the right files in the right order.”
Why choose code-tour over a generic prompt
A generic prompt usually returns prose detached from the code. code-tour is narrower but more useful when you need durable navigation: each step points to an actual file and line span, with narrative context and next-step flow. That makes it especially strong as code-tour for Technical Writing, onboarding, and repeatable review workflows.
Key constraints before you install
The code-tour skill only creates .tour JSON files; it is not for editing source code, broad documentation rewrites, or casual Q&A. It works best when the repository already has a clear file structure and the request is scoped to a service, feature, incident path, or PR diff rather than “explain everything.”
How to Use code-tour skill
Install context and what to read first
Install the parent skills repo in your usual skills workflow, then invoke code-tour from that environment. In this skill folder, SKILL.md is the only source file, so read it first. There are no helper scripts or references here, which means adoption is simple but you must provide good repo context yourself.
What input the code-tour skill needs
For strong code-tour usage, give:
- audience: “new backend engineer,” “security reviewer,” “technical writer”
- goal: onboarding, architecture, PR review, RCA, trust-boundary review
- scope: package, service, feature, or changed files
- output target:
.tours/<name>.tour - repo anchors: key files, entrypoints, modules, or commit/PR context
A weak request is: “Make a tour of this repo.”
A stronger request is: “Create a code-tour for Technical Writing that explains how auth requests flow through src/server.ts, middleware, token validation, and session storage. Keep it to 8–10 stops and optimize for a new doc writer.”
Turn a rough goal into a usable prompt
A good prompt for code-tour should specify reader, path, and exclusions. Example:
- “Create a
code-touronboarding tour for new maintainers of the billing service.” - “Anchor each stop to real files and line ranges.”
- “Start from the request entrypoint, then config loading, domain logic, persistence, and tests.”
- “Avoid unrelated admin tooling.”
- “Write concise step text that explains why this file matters and where to look next.”
This helps the skill choose sequence over summary. Without that framing, tours often become flat inventories of files.
Practical workflow and output checks
Suggested workflow:
- Identify the reader and exact question.
- Inspect the repo for entrypoints, core modules, and supporting tests.
- Draft a stop order that matches how the system is actually understood.
- Generate the
.tourfile in.tours/. - Validate every file path and line anchor.
- Open the tour and trim weak stops.
Quality checks that matter:
- each stop has a clear reason to exist
- the sequence tells a story, not just a list
- line anchors point to meaningful code, not import blocks
- the tour ends with “what to inspect next” or a synthesis step
code-tour skill FAQ
Is code-tour good for beginners?
Yes, if the scope is tight. Beginners benefit most from a tour of one flow, service, or PR. A repo-wide code-tour usually overwhelms them. If you are onboarding someone new, ask for a short path through the main execution path plus 1–2 supporting files.
When should I use code-tour instead of normal documentation?
Use code-tour when the reader needs file-by-file navigation tied to the source. Use normal docs when you need conceptual overviews, product behavior, or long-form prose. For technical writing teams, code-tour is best as a source-guided companion, not a replacement for polished docs.
What are the main limits of the code-tour skill?
It does not implement features, refactor code, or write broad documentation sets. It also depends on stable file paths and meaningful code structure. If the repo is chaotic, generated, or poorly named, the skill can still produce a tour, but the result will need heavier manual review.
When is this a bad fit?
Skip code-tour if a quick answer in chat is enough, if the user wants Markdown docs instead of a .tour artifact, or if the request is too broad to sequence well. It is also a weak fit when there is no clear audience; tours become much better once you know who they are for.
How to Improve code-tour skill
Give stronger repo-reading guidance
The biggest quality gain comes from supplying a discovery path before generation. Tell the skill where to start: entrypoints, routers, handlers, core services, tests, and config. If relevant, include PR diffs or incident notes. Better anchors lead to better tours.
Prevent common code-tour failure modes
Typical weak outputs:
- too many stops
- stops anchored to unimportant lines
- generic commentary that could fit any repo
- no clear audience
- no narrative transition between steps
Avoid these by setting a stop budget, naming the reader, and asking for “why this matters” plus “what to inspect next” in each stop.
Improve prompts with audience and intent
For code-tour for Technical Writing, ask for terminology, boundary definitions, and documentation-worthy concepts. For PR review, ask for changed-file sequencing and risk hotspots. For onboarding, ask for architecture-first ordering with tests last. Same repo, different prompt, very different tour quality.
Iterate after the first draft
Treat the first output as a map, not the final artifact. Open the .tour, remove redundant stops, tighten line ranges, and add one synthesis stop near the end. If the tour feels like a directory listing, narrow the scope and regenerate. The best code-tour skill results come from one focused revision, not one broad first pass.