common-documentation
Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.
77
73%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.github/skills/common/common-documentation/SKILL.mdQuality
Discovery
82%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 solid description that clearly communicates both what the skill does and when to use it, with good trigger term coverage. Its main weakness is moderate specificity—the actions described are somewhat general categories rather than concrete operations. The distinctiveness could also be improved by narrowing the scope or adding more unique differentiators beyond 'intent-first principles'.
Suggestions
Add more specific concrete actions to improve specificity, e.g., 'Write inline code comments, generate function docstrings, create project READMEs with setup instructions, document API endpoints'.
Clarify what 'intent-first principles' means briefly to strengthen distinctiveness and help Claude differentiate this from generic documentation skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (documentation) and some actions ('Write effective code comments, READMEs, and technical documentation'), but the actions are somewhat general rather than listing multiple concrete specific operations like 'generate API reference docs, write inline code comments, create changelog entries'. | 2 / 3 |
Completeness | Clearly answers both 'what' (write code comments, READMEs, technical documentation following intent-first principles) and 'when' with an explicit 'Use when...' clause listing specific triggers: adding comments, writing docstrings, creating READMEs, updating documentation. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'comments', 'READMEs', 'docstrings', 'documentation', 'code comments', 'technical documentation'. These cover common variations of how users would phrase documentation-related requests. | 3 / 3 |
Distinctiveness Conflict Risk | While it focuses on documentation specifically, 'technical documentation' is broad enough to potentially overlap with skills for API docs, wiki pages, or general writing skills. The 'intent-first principles' adds some distinctiveness but could still conflict with other documentation-adjacent skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a concise, well-structured documentation standards skill that efficiently communicates key principles without unnecessary verbosity. Its main weakness is the lack of concrete, executable examples—particularly for docstrings, README templates, and API documentation—which would significantly improve actionability. The skill reads more like a checklist of principles than a hands-on guide Claude can directly apply.
Suggestions
Add a concrete docstring example showing the expected Args/Returns/Usage format (e.g., a Python or TypeScript function with a complete docstring)
Include a minimal README template skeleton that Claude can copy and fill in, rather than just listing section names
Add a concrete 'good vs bad' comment example pair to make the intent-first principle immediately actionable
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Very lean and efficient. Every line delivers actionable guidance without explaining concepts Claude already knows. No padding or unnecessary context. | 3 / 3 |
Actionability | Provides concrete guidelines and formats (e.g., TODO format, README structure) but lacks executable code examples. Docstring guidance mentions Args/Returns/Usage but doesn't show a concrete example. API docs section says 'provide copy-pasteable examples' without demonstrating one. | 2 / 3 |
Workflow Clarity | The skill covers multiple documentation types but doesn't sequence them into a clear workflow. For a guidelines-style skill this is acceptable, but the README section hints at a process ('Documentation ships with feature') without making the workflow explicit. No validation or verification steps are mentioned. | 2 / 3 |
Progressive Disclosure | Content is well-organized into clear sections with good headers, but everything is inline in a single file. For a skill of this scope (covering comments, READMEs, ADRs, API docs), it could benefit from linking to separate detailed references for each area rather than keeping all guidance at the same shallow depth. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 9 / 11 Passed | |
- Repository
- HoangNguyen0403/agent-skills-standard
- Commit
4c72e76
- 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.