tdg-personal/code-tour
Create CodeTour `.tour` files — persona-targeted, step-by-step walkthroughs with real file and line anchors. Use for onboarding tours, architecture walkthroughs, PR tours, RCA tours, and structured "explain how this works" requests.
96
96%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that clearly communicates what the skill does (creates CodeTour `.tour` files with specific attributes) and when to use it (with five distinct use cases). The trigger terms are natural and varied, covering both specific terminology ('CodeTour', '.tour', 'RCA tours') and natural language ('explain how this works'). The description is concise yet comprehensive, with a clear niche that minimizes conflict risk.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: creating CodeTour `.tour` files, persona-targeted walkthroughs, step-by-step walkthroughs with real file and line anchors. The mention of specific output format (`.tour` files) and concrete attributes (persona-targeted, real file and line anchors) is highly specific. | 3 / 3 |
Completeness | Clearly answers both 'what' (create CodeTour `.tour` files with persona-targeted, step-by-step walkthroughs with real file and line anchors) and 'when' (onboarding tours, architecture walkthroughs, PR tours, RCA tours, and 'explain how this works' requests). The 'Use for...' clause serves as an explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'CodeTour', '.tour', 'onboarding tours', 'architecture walkthroughs', 'PR tours', 'RCA tours', and 'explain how this works'. These cover multiple natural phrasings a user might use when requesting this kind of skill. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — CodeTour `.tour` files are a very specific niche format. The combination of the file format, persona-targeting, and line anchors makes this unlikely to conflict with general documentation or code explanation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
92%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality skill that provides clear, actionable guidance for creating CodeTour files. It excels at conciseness (tables, compact examples), actionability (real JSON for every step type), and workflow clarity (explicit validation steps with 'never guess line numbers'). The only minor weakness is that all content is inline rather than split across files, though the length is borderline and the organization is strong enough to mitigate this.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is lean and efficient throughout. It assumes Claude's competence (no explanation of what JSON is, what CodeTour is at a basic level, etc.), uses tables for compact information delivery, and every section earns its place. The SMIG acronym and persona table pack a lot of guidance into minimal tokens. | 3 / 3 |
Actionability | Provides fully concrete JSON examples for every step type (file+line, selection, pattern, directory, URI, content-only), a complete tour example, specific file path conventions (.tours/<persona>-<focus>.tour), and exact step count ranges per persona. Everything is copy-paste ready. | 3 / 3 |
Workflow Clarity | The 5-step workflow (Discover → Infer reader → Read and verify anchors → Write → Validate) is clearly sequenced with explicit validation checkpoints. Step 3 emphasizes 'Never guess line numbers' and Step 5 provides a concrete validation checklist including file existence, line validity, and narrative coherence. The feedback loop of verify-before-write and validate-after-write is well-defined. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and tables, but it's all inline in a single file. At ~180 lines with detailed step type examples, the step types reference section and the full example could potentially be split into a separate reference file. However, the content is well-structured with headers making navigation easy. References to related skills are present but minimal. | 2 / 3 |
Total | 11 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents