reference-builder

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

Quality

39%

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 ./skills/reference-builder/SKILL.md

Quality

Content

28%Scale 1-5

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

This skill reads as a generic description of what good reference documentation looks like, rather than actionable instructions for Claude to follow when creating reference documentation. It extensively explains concepts Claude already understands (documentation structure, quality standards, navigation aids) without providing concrete, executable examples or specific workflows. The content would benefit greatly from being condensed and replaced with concrete examples of actual reference documentation generation.

Suggestions

Replace the generic descriptions of documentation types with 1-2 concrete, complete examples showing actual reference documentation output for a specific API or configuration, so Claude has a clear model to follow.

Condense the 'Core Capabilities', 'Quality Standards', 'Documentation Elements', and 'Best Practices' sections into a brief checklist—Claude already knows these principles and doesn't need them explained.

Add concrete validation steps to the 'Reference Building Process' workflow, such as specific checks to verify completeness (e.g., 'compare documented methods against actual public API surface') and accuracy verification commands.

Either provide the referenced `resources/implementation-playbook.md` bundle file or remove the reference and inline the most critical examples directly.

Dimension	Reasoning	Score
Conciseness	The skill is heavily padded with generic documentation advice that Claude already knows—how to write API references, what tables are, what warnings/notes are, etc. The 'Core Capabilities' and 'Quality Standards' sections describe obvious documentation principles. The entry format template and organizational hierarchy are standard knowledge for any documentation task.	2 / 5
Actionability	The content is almost entirely descriptive rather than instructive. It lists categories of things to document (API references, configuration guides, schema documentation) but provides no executable code, no concrete commands, and no specific examples of actual reference documentation being generated. The entry format template is the closest thing to actionable guidance, but it's a generic template rather than a concrete, executable example.	2 / 5
Workflow Clarity	The 'Reference Building Process' section lists 6 high-level steps (Inventory, Extraction, Enhancement, Validation, Organization, Cross-Reference) but they are vague labels without concrete actions, commands, or validation checkpoints. There are no feedback loops or error recovery steps. The process is more of a conceptual outline than an actionable workflow.	2 / 5
Progressive Disclosure	There is a reference to `resources/implementation-playbook.md` for detailed examples, which is a reasonable progressive disclosure pattern. However, no bundle files exist to support this reference, and the bulk of the content is inlined as a monolithic document that could benefit from being split into separate reference files for different documentation types.	3 / 5
	Total	9 / 20 Passed

Description

50%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 provides a reasonable overview of what the skill produces but lacks a 'Use when...' clause, which limits Claude's ability to know when to select it. The trigger terms are adequate but miss common synonyms and user phrasings. The specificity is moderate—it names output types but doesn't detail concrete actions like 'documents REST endpoints' or 'generates OpenAPI specs'.

Suggestions

Add an explicit 'Use when...' clause with trigger phrases like 'when the user asks for API docs, reference documentation, endpoint documentation, or SDK guides'.

Include more specific concrete actions such as 'documents REST endpoints, generates method signatures, creates type definitions' to differentiate from general documentation skills.

Add natural synonyms and file format references like 'API docs', 'SDK documentation', 'OpenAPI', '.yaml', 'swagger' to improve trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain (technical references, API documentation) and lists a few concrete outputs (parameter listings, configuration guides, searchable reference materials), but these are somewhat generic and not highly specific actions.	3 / 5
Completeness	Has a clear 'what' (creates technical references, API docs, parameter listings, etc.) but completely lacks a 'when' clause or any explicit trigger guidance for when Claude should select this skill.	3 / 5
Trigger Term Quality	Includes relevant terms like 'API documentation', 'technical references', 'parameter listings', and 'configuration guides', but misses common user phrases like 'API docs', 'reference docs', 'SDK documentation', 'endpoint documentation', or file format mentions.	3 / 5
Distinctiveness Conflict Risk	The focus on API documentation and technical references provides some distinction, but 'configuration guides' and 'reference materials' are broad enough to overlap with general documentation or writing skills.	3 / 5
	Total	12 / 20 Passed

Validation

90%

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 — 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

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/reference-builder/SKILL.md
Commit: 57c135b

Reviewed: 2 days 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.