doc-generator

Generate comprehensive, accurate API documentation from source code. Use when creating or updating API documentation, generating OpenAPI specs, or when users mention API docs, endpoints, or documentation.

Quality

71%

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 ./03-skills/doc-generator/SKILL.md

Quality

Content

61%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 is a clean, actionable documentation template with good organization and no bundle-file sprawl. Its main weaknesses are a time-sensitive metadata footer that wastes tokens, and the absence of any generation workflow or verification step.

Suggestions

Remove or relocate the time-sensitive footer ('Last Updated', 'Claude Code Version', 'Compatible Models') out of the SKILL.md body to improve token efficiency, or place version-specific notes in a deprecated/old-patterns section.

Add a short sequenced workflow for generating docs (e.g. parse source → enumerate endpoints → fill template → verify examples compile), including a validation checkpoint confirming generated examples match the actual API.

Consider moving the full multi-language example template into a references/ file and keeping only one representative example inline to reduce body length and improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient — a lean 'Generates' list and a reusable markdown template with no over-explanation of concepts Claude knows. It drops to 3 rather than 4 because the footer carries time-sensitive metadata ('Last Updated: August 4, 2026', 'Claude Code Version: 2.1.220', 'Compatible Models: ...') that the guidelines say should penalize conciseness unless placed in a deprecated/old-patterns section.	3 / 5
Actionability	Provides a concrete, copy-paste-ready documentation template with executable cURL, JavaScript, and Python examples and a parameter table. It is not 5 because the examples illustrate output format rather than guiding the generation process itself, leaving minor gaps; not 3 because the provided code is genuinely executable rather than pseudocode.	4 / 5
Workflow Clarity	The content defines the output structure ('For Each Endpoint') but gives no sequenced generation workflow or validation checkpoints for verifying generated docs against the source. It is not 2 because the template implies a clear per-endpoint structure, and not 4 because there are no explicit process steps or verification feedback loops.	3 / 5
Progressive Disclosure	Well-organized with clear sections (Generates, Documentation Structure, For Each Endpoint) and no nested references — appropriate for a single-file skill with no bundle. It is not 5 because the body is slightly over ~50 lines and the full multi-language example template is borderline content that could be externalized into a reference file; not 3 because the structure is clean and navigable.	4 / 5
	Total	14 / 20 Passed

Description

82%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.

A strong, well-structured description that clearly states what the skill does and when to invoke it, with good trigger-term coverage and low conflict risk. The only weakness is modest specificity — it names just two concrete generation actions.

Dimension	Reasoning	Score
Specificity	Names the domain ('API documentation from source code') and 1-2 concrete actions ('Generate... API documentation', 'generating OpenAPI specs'), but coverage is not comprehensive — the 'comprehensive, accurate' phrasing is mild fluff rather than additional concrete actions. It sits at anchor 3 rather than 4 because it lists only two real actions, and not 2 because the domain plus concrete actions are clearly named.	3 / 5
Completeness	Explicitly answers both 'what' ('Generate comprehensive, accurate API documentation from source code') and 'when' ('Use when creating or updating API documentation, generating OpenAPI specs, or when users mention API docs, endpoints, or documentation') with concrete trigger phrases. It clearly matches the anchor 5 example rather than 4, where the 'when' is fully explicit.	5 / 5
Trigger Term Quality	Good keyword coverage with synonyms users would say: 'API documentation', 'OpenAPI specs', 'API docs', 'endpoints', 'documentation'. It is not 5 because file extensions and a few natural variants (e.g. 'Swagger' only appears in the body) are missing, and not 3 because the synonym set is broader than a single generic keyword.	4 / 5
Distinctiveness Conflict Risk	Clear niche (API documentation generation from source code) with distinct triggers ('API docs', 'endpoints', 'OpenAPI specs') giving minimal conflict risk. It is not 4 because the combination of source-code-derived API docs is more sharply scoped than the anchor 4 'PDF and Word' example.	5 / 5
	Total	17 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: luongnv89/claude-howto
Path: 03-skills/doc-generator/SKILL.md
Commit: 1c04dbf

Reviewed: 4 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.