docstring
Document a Python module and its classes using Google style
70
55%
Does it follow best practices?
Impact
95%
1.43xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/docstring/SKILL.mdQuality
Discovery
32%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 is too terse and lacks an explicit 'when to use' clause, which is critical for skill selection. While it identifies a specific documentation style (Google) and target (Python modules/classes), it doesn't enumerate concrete actions or include sufficient trigger terms for reliable matching.
Suggestions
Add a 'Use when...' clause with trigger terms like 'docstrings', 'Google-style documentation', 'document Python code', 'module documentation', 'class documentation'.
List specific concrete actions such as 'Generate Google-style docstrings for modules, classes, methods, and functions, including parameter descriptions, return types, and usage examples'.
Include common file/format variations users might mention, such as '.py files', 'Python package', 'API docs', 'pydoc', or 'Sphinx-compatible docstrings'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Python module documentation) and a specific action (document classes), but doesn't list multiple concrete actions like generating docstrings, adding type hints, documenting parameters/returns, etc. | 2 / 3 |
Completeness | Describes what it does (document a Python module and its classes) but has no explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric caps completeness at 2, and the 'what' is also fairly thin, placing this at a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant keywords like 'Python module', 'classes', and 'Google style', but misses common variations users might say such as 'docstrings', 'Google-style docstrings', 'document functions', 'API documentation', or 'pydoc'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Google style' and 'Python module' provides some specificity, but it could overlap with general Python documentation skills, code commenting skills, or other docstring-related skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a solid, actionable skill with clear workflow sequencing and excellent concrete examples for every docstring format. Its main weakness is length—the extensive format examples and writing style guidelines make it verbose for a skill file, and some content could be split into reference files or trimmed. The checklist at the end is a strong validation mechanism.
Suggestions
Consider moving the detailed format examples (class, method, dataclass, enum, deprecation) into a separate REFERENCE.md file and keeping only the most essential example in SKILL.md to improve conciseness and progressive disclosure.
Trim the 'Writing Style Guidelines' section—items like 'No casual language' and 'Action-oriented' are things Claude already knows; keep only the project-specific conventions (backtick usage, no redundant type info).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly well-structured but includes some redundancy—multiple full examples for each docstring format (module, class, constructor, method, dataclass, enum) when fewer would suffice. The writing style guidelines section includes some obvious advice Claude already knows (e.g., 'No casual language or filler words'). However, the examples themselves are useful and not excessively padded. | 2 / 3 |
Actionability | The skill provides fully concrete, copy-paste-ready docstring formats with real examples for every category (module, class, __init__, method, dataclass, enum, deprecation). The step-by-step instructions for identifying what to document are specific and executable, including search commands and disambiguation logic. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced: identify the target → read the module → apply documentation in a specific order → skip certain items → verify with a checklist. The checklist at the end serves as an explicit validation checkpoint. The disambiguation step (multiple matches → ask user) is a good feedback loop for ambiguous inputs. | 3 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and headers, but it's a long monolithic document (~200 lines) with no references to external files. The numerous format examples for each docstring type could be split into a reference file, keeping the SKILL.md as a concise overview. However, given no bundle files exist, this is somewhat expected. | 2 / 3 |
Total | 10 / 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
- pipecat-ai/pipecat
- Commit
ea296ba
- 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.