code-documenter

Use when adding docstrings, creating API documentation, or building documentation sites. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, tutorials, user guides.

Quality

61%

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/code-documenter/SKILL.md

Quality

Content

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

A well-organized overview skill with excellent progressive disclosure via a clearly signaled reference table, but the body itself is light on executable detail and validation checkpoints, relying on bundle files for actionability.

Suggestions

Add an explicit validation checkpoint in the workflow (e.g., '4b. Validate: confirm examples run and OpenAPI spec parses; fix and re-validate before reporting') to lift workflow clarity past the batch-operation cap.

Include one compact inline example (e.g., a Google-style docstring or a minimal OpenAPI snippet) so the body is actionable without forcing a reference load for common cases.

Trim the persona padding in Role Definition and drop or merge the redundant 'Knowledge Reference' list into the reference table to tighten conciseness.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with no concept over-explanation, but includes unnecessary padding that could be tightened — the persona inflation ('8+ years of experience', 'guides that developers actually use') and the redundant flat 'Knowledge Reference' technology dump that overlaps the reference table.	3 / 5
Actionability	Offers concrete directives (MUST DO: 'Ask for format preference before starting', 'Generate coverage report') and a structured workflow, but the body gives no examples, code, or specific commands — executable detail is entirely deferred to reference files, leaving guidance incomplete in the overview itself.	3 / 5
Workflow Clarity	A clear 5-step sequence (Discover → Detect → Analyze → Document → Report) is present, but validation checkpoints are only implicit (the closing 'Report' step) rather than explicit verify-then-proceed gates; given this is a batch operation ('Document all public functions/classes'), the missing-validation cap holds it at 3.	3 / 5
Progressive Disclosure	Clear overview body with a well-signaled Reference Guide table whose 'Load When' column marks each of the 8 one-level-deep references, all of which exist as real files in ./references/, giving easy navigation — a clean match to the top anchor.	5 / 5
	Total	14 / 20 Passed

Description

66%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 concise, trigger-rich description that clearly signals when to invoke the skill across documentation tasks, but it omits an explicit statement of what the skill does, leaving the capability implied rather than stated.

Suggestions

Lead with an explicit 'what' clause (e.g., 'Generates and maintains inline documentation, API specs, and doc sites.') before the 'Use when' triggers so both what and when are explicit.

Add a couple of natural synonyms / file extensions users say ('comments', '.openapi.yaml', 'API docs') to round out trigger coverage.

Sharpen verbs from generic 'adding/creating/building' to distinctive actions like 'generates', 'formats', 'scaffolds' to lift specificity.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions and artifacts ('adding docstrings, creating API documentation, building documentation sites', 'OpenAPI/Swagger specs, JSDoc, doc portals, tutorials, user guides'), with only minor coverage gaps; not a 5 because the verbs themselves are generic ('adding/creating/building') rather than sharply distinctive.	4 / 5
Completeness	Provides strong, specific 'when' guidance via two clauses ('Use when...', 'Invoke for...') but never states an explicit 'what' — the skill's action is only implied by the trigger list, so it sits above the vague anchor 2 yet below the both-what-and-when anchor 4.	3 / 5
Trigger Term Quality	Includes natural terms users would say ('docstrings', 'API documentation', 'OpenAPI/Swagger', 'JSDoc', 'tutorials', 'user guides') with good synonym coverage; stops short of 5 because it lacks file extensions and a few common variations like 'comments' or 'API docs'.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear documentation niche with distinct triggers (docstrings, JSDoc, OpenAPI specs, doc portals) and minimal conflict risk; not 5 because 'creating API documentation' / 'building documentation sites' could overlap with closely related skills like spec-miner or fullstack-guardian.	4 / 5
	Total	15 / 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: zebbern/claude-code-guide
Path: skills/code-documenter/SKILL.md
Commit: 59c5fc4

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.