doc-traceability-validator

Validate documentation traceability between code annotations (@implements), feature registry, business rules, and use cases. Detect ID collisions, undocumented features, broken cross-references, and namespace violations.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/doc-traceability-validator/SKILL.md

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with executable commands and clear validated workflows, and its scripts are properly bundled. Its main weakness is token efficiency and progressive disclosure: a long inline reference section plus a real-world audit narrative could be tightened or moved to reference files.

Suggestions

Trim or remove the "Real-World Example: Iterations 65-75" narrative, keeping only the concrete cross-cutting-duplicates rule, to reduce backstory padding.

Move the detailed per-script argument references and large sample-output blocks into a separate references file (e.g. SCRIPTS.md) and link to it one level deep from SKILL.md.

Condense the inline output samples (currently with "..." continuations) to the essential fields Claude needs to interpret results.

Dimension	Reasoning	Score
Conciseness	The body is mostly actionable, but the "Real-World Example: EdgeQuake Documentation Audit (Iterations 65-75)" narrative and lengthy sample report blocks are backstory/padding Claude does not need, fitting the mostly-efficient-but-could-be-tightened anchor rather than the lean anchor at 3.	2 / 3
Actionability	It provides exact executable commands with real script paths, complete argument lists, sample outputs, and a CI/CD YAML block that is copy-paste ready, and the referenced scripts exist in the bundle, matching the fully-executable anchor.	3 / 3
Workflow Clarity	Best-practices and troubleshooting sections give clearly sequenced steps with explicit validation checkpoints ("Run validation to confirm", "Re-run validation") and feedback loops for error recovery, matching the clear-sequence-with-validation anchor.	3 / 3
Progressive Disclosure	Scripts are correctly externalized one level deep and referenced by real paths, but SKILL.md itself is a monolithic inline reference (full script-arg docs, output samples, namespace tables, audit narrative) that could be split into separate reference files, fitting the some-structure-but-inline anchor rather than the well-split anchor at 3.	2 / 3
	Total	10 / 12 Passed

Description

67%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is specific and occupies a clear, non-conflicting niche, but it omits explicit "when to use" trigger guidance and leans on specialized jargon over natural user phrasings. Adding a "Use when..." clause with common trigger terms would raise completeness and trigger-term quality.

Suggestions

Append a "Use when..." clause (e.g., when auditing doc gaps, finding duplicate FEAT/BR/UC IDs, or setting up CI docs checks) to satisfy the completeness "when" requirement.

Add natural trigger terms users would say ("documentation gaps", "duplicate feature IDs", "broken doc links") alongside the technical jargon to improve trigger-term quality.

Keep the concrete action list but pair it with the trigger clause so the description hits the what-AND-when anchor at 3.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions: "Validate documentation traceability" and "Detect ID collisions, undocumented features, broken cross-references, and namespace violations", matching the multiple-specific-actions anchor rather than the single-domain anchor at 2.	3 / 3
Completeness	It clearly answers "what" the skill does but provides no "Use when..." clause or equivalent explicit trigger guidance, which the rubric caps at 2 rather than the what-and-when anchor at 3.	2 / 3
Trigger Term Quality	Terms like "documentation traceability", "@implements", "feature registry", and "namespace violations" are relevant but specialized jargon; it lacks the common natural phrasings a user might say and misses common variations, so it does not reach the broad coverage anchor at 3.	2 / 3
Distinctiveness Conflict Risk	The @implements / FEAT-BR-UC traceability niche is highly specific and unlikely to trigger for unrelated skills, matching the clear-niche anchor; it is well above the generic-overlap anchor at 2.	3 / 3
	Total	10 / 12 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
relative_links	Relative link issues: 5 suspicious	Warning

	Total	13 / 16 Passed

Repository: raphaelmansuy/edgequake
Path: .github/skills/doc-traceability-validator/SKILL.md
Commit: 62e6adb

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.