docs-writer
Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. Use when creating docs, reviewing markdown files, writing READMEs, updating `/docs` directories, or when user says "write documentation", "review this doc", "improve this README", "create a guide", or "edit markdown". Do NOT use for code comments, inline JSDoc, or API reference generation.
80
75%
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 ./packages/skills-catalog/skills/(development)/docs-writer/SKILL.mdQuality
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 an excellent skill description that hits all the marks. It provides specific actions, comprehensive natural trigger terms, explicit 'Use when' and 'Do NOT use' clauses, and clear boundaries that distinguish it from adjacent skills. The inclusion of negative triggers (exclusions) is a particularly strong feature that reduces conflict risk.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Write, review, and edit documentation files' with qualifiers about 'consistent structure, tone, and technical accuracy'. Also specifies exclusions (code comments, inline JSDoc, API reference generation), which adds further specificity. | 3 / 3 |
Completeness | Clearly answers both 'what' (write, review, edit documentation with consistent structure/tone/accuracy) and 'when' (explicit 'Use when...' clause with multiple trigger scenarios). Also includes a 'Do NOT use' clause that further clarifies boundaries. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'docs', 'markdown files', 'READMEs', '/docs directories', 'write documentation', 'review this doc', 'improve this README', 'create a guide', 'edit markdown'. These are highly natural phrases users would actually use. | 3 / 3 |
Distinctiveness Conflict Risk | The description carves out a clear niche around documentation files specifically, and the explicit exclusions (code comments, inline JSDoc, API reference generation) actively prevent overlap with related skills like code commenting or API doc generation tools. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a competent but somewhat generic documentation writing skill. It provides a reasonable workflow with clear steps and references to project-specific files, but lacks concrete examples of expected output, executable commands, and explicit validation/feedback loops. Several instructions describe things Claude would naturally do (clarify requests, check grammar) rather than focusing on project-specific knowledge that adds unique value.
Suggestions
Add a concrete example showing expected documentation output format (e.g., a sample section with proper heading structure, tone, and style matching the project's style guide).
Include an explicit feedback loop in Step 4: 'If links are broken or formatting is off, return to Step 3 and fix before proceeding.'
Remove generic writing advice Claude already knows (e.g., 'Correct awkward wording, spelling, and grammar') and replace with project-specific conventions or patterns unique to this codebase.
Add concrete examples of tool usage, e.g., a sample `replace` call for a small edit and a `write_file` call for a new doc page.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably structured but includes some unnecessary elaboration that Claude would naturally handle (e.g., 'Fully understand the user's documentation request', 'Correct awkward wording, spelling, and grammar'). Some steps describe general good practices Claude already knows rather than project-specific guidance. | 2 / 3 |
Actionability | The skill provides a clear process with specific tool mentions (`replace`, `write_file`) and references to concrete files (`docs/sidebar.json`, `references/style-guide.md`, `CONTRIBUTING.md`), but lacks executable examples. No sample markdown output, no example of a well-structured doc section, and no concrete command beyond `npm run format`. | 2 / 3 |
Workflow Clarity | The four-step workflow is clearly sequenced and logically ordered, with a verification step at the end. However, there's no explicit validation checkpoint or feedback loop — Step 4 says 'review your work' but doesn't specify what to do if issues are found, and link verification has no concrete method described. | 2 / 3 |
Progressive Disclosure | The skill references external files (`CONTRIBUTING.md`, `references/style-guide.md`, `docs/sidebar.json`) which is good progressive disclosure, but the references aren't clearly signaled with links or formatted as a navigation section. The inline content could benefit from separating the editing sub-step checklist into a reference file. | 2 / 3 |
Total | 8 / 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
- tech-leads-club/agent-skills
- Commit
906a57d
- 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.