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

78%

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%

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 well-organized overview with excellent progressive disclosure via the Load-When reference table, but its workflow is abstract and lacks inline examples or explicit validation feedback loops, leaving actionability and workflow_clarity at the mid anchor. Conciseness is good but softened by persona padding and a redundant knowledge list.

Suggestions

Add one concrete inline example per major output type (e.g., a Google-style Python docstring, a minimal OpenAPI 3.1 snippet, and a sample coverage-report format) so the guidance is copy-paste ready instead of being delegated entirely to references.

Insert an explicit validation/feedback loop after the Report step — e.g., "If coverage is below target or doc examples fail to run, return to Analyze/Document and regenerate" — to turn the linear workflow into a validate→fix→retry cycle.

Remove the persona padding in Role Definition ("8+ years of experience") and drop the redundant Knowledge Reference list, which restates technologies already covered by the reference table and frontmatter triggers.

Dimension	Reasoning	Score
Conciseness	Mostly efficient bullet/table layout with no basic-concept explanations, but the "8+ years of experience" persona in Role Definition and the terminal Knowledge Reference list (restating tech already covered by the reference table and frontmatter) are padding that could be tightened, fitting score 2 rather than the lean score-3 anchor.	2 / 3
Actionability	The MUST DO/MUST NOT DO rules and the Load-When reference table are concrete, but the workflow steps are abstract verbs ("Apply consistent format", "Generate coverage summary") with no inline executable example or template, so guidance is incomplete and not copy-paste ready — score 2, above the purely vague score-1 anchor.	2 / 3
Workflow Clarity	A clear 5-step sequence (Discover → Detect → Analyze → Document → Report) is present with an implicit coverage-report checkpoint, but there is no explicit validate→fix→retry feedback loop for this batch-style documentation operation, capping it at score 2 per the missing-validation guideline.	2 / 3
Progressive Disclosure	The Reference Guide table maps eight topics to real, verified one-level-deep reference files with a "Load When" column — a textbook clear-overview + well-signaled-references structure matching the score-3 anchor, with content appropriately split out of SKILL.md.	3 / 3
	Total	9 / 12 Passed

Description

100%

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 closely follows the rubric's good-example template: concrete capabilities plus an explicit "Use when/Invoke for" trigger clause, with no first/second-person pronouns to penalize. Its only mild weakness is that the "what" is embedded in trigger phrasing rather than stated as a standalone capability sentence, and its scope is broad, but both remain within the top anchor.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions and artifacts — "adding docstrings, creating API documentation, or building documentation sites" plus "OpenAPI/Swagger specs, JSDoc, doc portals, tutorials, user guides" — matching the score-3 anchor rather than the vague score-2 "Names domain and some actions".	3 / 3
Completeness	Explicit "Use when ..." and "Invoke for ..." trigger clauses answer "when", while the named actions answer "what"; the explicit trigger guidance means it is not capped at 2, and both what-and-when are present as in the score-3 example.	3 / 3
Trigger Term Quality	Natural developer-facing terms ("docstrings", "API documentation", "OpenAPI/Swagger", "JSDoc", "tutorials", "user guides") are exactly what a user would say when needing this skill, giving good coverage per the score-3 anchor; it is not jargon-only (score 1) nor missing common variations (score 2).	3 / 3
Distinctiveness Conflict Risk	It carves a clear code/developer-documentation niche with distinct triggers (docstrings, JSDoc, doc portals), making wrong-skill conflict unlikely; the breadth is within one domain, so it clears the score-3 "clear niche" bar rather than the overlapping score-2 anchor.	3 / 3
	Total	12 / 12 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: af7d491

Reviewed: about 9 hours 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.