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. (triggers: comment, docstring, readme, documentation)
80
74%
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
92%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 communicates its purpose, lists concrete actions, includes natural trigger terms, and explicitly states when to use it. The only minor weakness is that 'technical documentation' is somewhat broad and could overlap with other documentation-focused skills. The explicit trigger list in parentheses is a nice touch for disambiguation.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Write effective code comments, READMEs, and technical documentation' and specifies the methodology 'following intent-first principles'. These are concrete, identifiable deliverables. | 3 / 3 |
Completeness | Clearly answers both 'what' (write code comments, READMEs, technical documentation following intent-first principles) and 'when' (explicit 'Use when adding comments, writing docstrings, creating READMEs, or updating any documentation') with explicit trigger terms listed. | 3 / 3 |
Trigger Term Quality | Includes natural keywords users would say: 'comment', 'docstring', 'readme', 'documentation', plus variations in the body like 'comments', 'docstrings', 'READMEs'. These are terms users would naturally use when requesting help with documentation tasks. | 3 / 3 |
Distinctiveness Conflict Risk | While it carves out a clear niche around documentation and comments, there could be overlap with general coding skills or README-specific skills. The 'intent-first principles' methodology adds some distinctiveness, but 'technical documentation' is broad enough to potentially conflict with other writing or documentation skills. | 2 / 3 |
Total | 11 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a well-structured overview of documentation standards with good progressive disclosure and reasonable conciseness. Its main weakness is the lack of concrete, inline examples—no actual code comments, docstrings, or README snippets are shown, making it more of a guideline document than an actionable skill. The anti-patterns section adds value but duplicates content from earlier sections.
Suggestions
Add 2-3 inline concrete examples showing good vs bad comments/docstrings (e.g., a 'Why' comment vs a 'What' comment side by side) to improve actionability.
Include a minimal README template skeleton that Claude can directly adapt, rather than just listing what sections should contain.
Remove the duplicate 'Documentation ships with the feature, not after' guidance that appears in both Section 2 and Anti-Patterns.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient with bullet-point structure, but some points are somewhat generic and could be tightened. Phrases like 'Documentation ships with the feature, not after' appear twice (sections 2 and Anti-Patterns). Some guidance restates things Claude already knows (e.g., explaining what Swagger/OpenAPI is for). | 2 / 3 |
Actionability | Provides directional guidance with specific conventions (TODO format, ADR location, triple-slash style) but lacks concrete executable examples inline. No code snippets showing good vs bad comments, no README template, no docstring example. The reference link to implementation examples helps but the skill body itself is light on copy-paste-ready content. | 2 / 3 |
Workflow Clarity | The sections are logically organized and numbered, but there's no clear sequential workflow for when/how to apply these standards. For a documentation skill this is acceptable since it's more of a reference than a multi-step process, but the lack of any decision flow (e.g., 'when adding a new function, do X then Y') limits clarity. | 2 / 3 |
Progressive Disclosure | Clean overview structure with well-organized sections and a single clear reference link to implementation examples. Content is appropriately concise at the top level with one-level-deep reference for detailed patterns. For a skill of this size and scope, the organization is effective. | 3 / 3 |
Total | 9 / 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
- HoangNguyen0403/agent-skills-standard
- Commit
19a1140
- 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.