CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

reference-builder

Creates exhaustive technical references and API documentation. Generates comprehensive parameter listings, configuration guides, and searchable reference materials.

Quality

56%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/reference-builder/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

38%Weight 40%Scale 1-5

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

The body presents a well-organized taxonomy of reference-documentation practices, but much of it is generic best-practice padding Claude already knows, the guidance stays at the template/abstract level with no executable examples, and its only progressive-disclosure pointer references a nonexistent file. Tightening to skill-specific specifics and fixing or removing the broken reference would raise quality substantially.

Suggestions

Fix or remove the dangling reference: `resources/implementation-playbook.md` does not exist in the bundle — either create the file (e.g., under references/) or delete the pointer and inline only what is needed.

Cut generic boilerplate Claude already knows (the tautological 'Use/Do not use this skill when' sections and the Quality Standards list) and keep only reference-building specifics such as the entry format and organization scheme.

Operationalize the Reference Building Process with explicit validation checkpoints and error recovery, e.g. "4. Validate: diff documented symbols against the public API; if any interface is undocumented, return to step 2 before publishing".

DimensionReasoningScore

Conciseness

Noticeably verbose with several padded sections that restate knowledge Claude already has: the tautological "Working on reference builder tasks or workflows" / "The task is unrelated to reference builder" sections, and generic quality bullets like "Completeness: Every public interface documented", "Accuracy: Verified against actual implementation", "Consistency: Uniform formatting and terminology". Matches anchor 2 (several unnecessary explanations or padded sections); not 1 because it does not tutorial-explain basic concepts, and the entry-format template is skill-specific; not 3 because the padding is widespread rather than isolated.

2 / 5

Actionability

The entry format template ("### [Feature/Method/Parameter Name] **Type**: ... **Parameters**: - `paramName` (type): Description") and the "Reference Building Process" steps ("1. Inventory: Catalog all public interfaces") provide some concrete guidance, but it is placeholder/pseudocode-level with no runnable examples, commands, or a finished sample entry. Matches anchor 3 (some concrete guidance but incomplete, pseudocode instead of executable); not 4 because most sections are abstract bullet lists with no executable specifics.

3 / 5

Workflow Clarity

"1. Inventory... 2. Extraction... 4. Validation: Verify accuracy and completeness... 6. Cross-Reference" gives a coherent sequence that names validation, but there is no explicit checkpoint or error-recovery loop — nothing about how to verify (e.g., diff against source, check every public symbol) or what to do on failure. Matches anchor 3 (steps listed but validation gaps, checkpoints implicit); not 4 because checkpoints are named but not operationalized; not 2 because the sequence is clear and well-ordered, not poorly defined.

3 / 5

Progressive Disclosure

The body is well-sectioned like the anchor-3 example (bulk guidance inlined plus a pointer), but the sole external reference — "If detailed examples are required, open `resources/implementation-playbook.md`" — points to a file that does not exist in the bundle (no references/, scripts/, or assets/ directories are present), so the one navigation path is broken and ~180 lines of detail remain inlined. Falls between anchors 2 and 3, and below 3 because a dangling reference plus inlined bulk content makes navigation effectively fail; not 1 because sections are clearly organized, not a monolithic wall of text.

2 / 5

Total

10

/

20

Passed

Description

53%Weight 40%Scale 1-5

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 gives a clear 'what' with a moderately specific niche in reference/API documentation, but it contains buzzword padding ('exhaustive', 'comprehensive'), lacks natural trigger-term synonyms, and omits any 'Use when' clause, capping completeness. Adding explicit trigger guidance with concrete phrases would lift most dimensions.

Suggestions

Append a trigger clause naming natural user phrases, e.g. "Use when asked to write API documentation, reference docs, or configuration guides, or when the user mentions documenting parameters, schemas, or endpoints."

Replace buzzwords ('exhaustive', 'comprehensive') with concrete actions such as "Documents every parameter, method, and configuration option with signatures, defaults, examples, and error codes".

Include natural synonyms and artifacts ("API docs", "reference docs", "OpenAPI specs") to improve trigger-term coverage.

DimensionReasoningScore

Specificity

"Creates exhaustive technical references and API documentation. Generates comprehensive parameter listings, configuration guides, and searchable reference materials" names the domain and several deliverables, but the actions are generic output categories padded with 'exhaustive'/'comprehensive' buzzwords rather than distinct concrete actions. Falls between anchor 3 (domain + 1-2 concrete actions, not comprehensive) and anchor 4 (several specific actions); closer to 3 since the deliverable labels lack actionable specificity.

3 / 5

Completeness

The 'what' is clear (creates technical references and API documentation) but there is no 'Use when...' clause or equivalent trigger guidance anywhere in the description, which caps completeness at 3 per the judging guidelines. Exact match for anchor 3: clear 'what', 'when' missing; not 4 because no 'when' is present even weakly.

3 / 5

Trigger Term Quality

Relevant keywords are present ("technical references", "API documentation", "configuration guides", "parameter listings") but common natural variations users would say — "API docs", "reference docs", "document this API", "write documentation" — are missing. Matches anchor 3 (some relevant keywords, missing common variations or synonyms); not 4 because coverage lacks synonyms and is not comprehensive.

3 / 5

Distinctiveness Conflict Risk

"Creates exhaustive technical references and API documentation" carves a recognizable niche (reference/API documentation generation) distinguishable from extraction, editing, or analysis skills, though it overlaps with general documentation-writing skills. Matches anchor 4 (mostly distinct, minor overlap risk with closely related skills); not 5 because 'technical references' is still fairly broad and no explicit triggers sharpen the niche.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

administrakt0r/AI-Agents-Safe-Coding-Skills

Path

skills/reference-builder/SKILL.md

Reviewed

Table of Contents

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.