code-documenter
Generates, formats, and validates technical documentation — including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. Use when adding docstrings to functions or classes, creating API documentation, building documentation sites, or writing tutorials and user guides. Invoke for OpenAPI/Swagger specs, JSDoc, doc portals, getting started guides.
93
92%
Does it follow best practices?
Impact
93%
1.10xAverage score across 6 eval scenarios
Passed
No known issues
Quality
Discovery
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.
This is a strong skill description that clearly defines its scope around technical documentation with specific formats and use cases. It includes both a 'Use when' and 'Invoke for' clause providing comprehensive trigger coverage. The description is concise yet thorough, listing concrete actions and natural trigger terms that developers would use.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'generates, formats, and validates technical documentation' with explicit subtypes including docstrings, OpenAPI/Swagger specs, JSDoc annotations, doc portals, and user guides. | 3 / 3 |
Completeness | Clearly answers both 'what' (generates, formats, validates technical documentation of various types) and 'when' with explicit 'Use when...' and 'Invoke for...' clauses listing specific trigger scenarios like adding docstrings, creating API docs, building doc sites, and writing tutorials. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'docstrings', 'OpenAPI', 'Swagger', 'JSDoc', 'API documentation', 'documentation sites', 'tutorials', 'user guides', 'getting started guides', 'doc portals'. These are terms developers naturally use when requesting documentation help. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly carved out niche around technical documentation with highly specific triggers like OpenAPI/Swagger, JSDoc, doc portals, and docstrings. Unlikely to conflict with general coding skills or content writing skills due to the precise technical documentation focus. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured skill with strong actionability, clear workflow with validation feedback loops, and excellent progressive disclosure via the reference table. Its main weakness is moderate verbosity — three full inline docstring examples and a constraints section that partially restates the workflow could be tightened. The 'Knowledge Reference' keyword list at the end adds little value.
Suggestions
Trim the inline examples to two (e.g., one Python style + JSDoc) and move the third to a reference file, reducing token cost while preserving clarity.
Remove or condense the 'Knowledge Reference' keyword list at the bottom — it's a low-value enumeration that Claude doesn't need as a reminder.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient but includes some redundancy. The MUST DO/MUST NOT DO constraints partially restate what's already implied by the workflow and examples. The 'Knowledge Reference' list at the bottom is a low-value keyword dump. The examples are useful but three full docstring examples inline is borderline verbose when references exist. | 2 / 3 |
Actionability | Provides fully concrete, copy-paste-ready docstring examples in multiple formats (Google, NumPy, JSDoc), specific validation commands for each language/tool (doctest, tsc, redocly), and a clear reference table for loading detailed guidance. The guidance is specific and executable. | 3 / 3 |
Workflow Clarity | The 6-step workflow is clearly sequenced with an explicit validation step that includes specific commands per language, a feedback loop ('if validation fails: fix and re-validate before proceeding'), and a clear gate before the final Report step. This is well-structured for a multi-step process. | 3 / 3 |
Progressive Disclosure | Excellent use of a reference table with 8 topic-specific files, each with clear 'Load When' conditions. The SKILL.md serves as a concise overview with quick-reference examples while deferring detailed guidance to one-level-deep references. Navigation is clear and well-signaled. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- jeffallan/claude-skills
- Commit
3d95bb1
- 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.