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.
85
81%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
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 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 like code commenting or API doc generation. The third-person voice is used correctly throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple concrete actions: 'Write, review, and edit documentation files' with specific qualities mentioned ('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 for boundary clarity. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural user terms: 'docs', 'markdown files', 'READMEs', '/docs directories', 'write documentation', 'review this doc', 'improve this README', 'create a guide', 'edit markdown'. These are phrases users would naturally say. | 3 / 3 |
Distinctiveness Conflict Risk | The explicit exclusions ('Do NOT use for code comments, inline JSDoc, or API reference generation') sharply delineate this skill from related code documentation skills. The focus on documentation files, READMEs, and /docs directories creates a clear niche. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
62%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 documentation workflow skill with clear step sequencing and good references to project-specific files. Its main weaknesses are the lack of concrete examples (no sample markdown output, no template snippets) and some verbosity in describing practices Claude already knows, like clarifying requests and checking grammar. The workflow structure is its strongest aspect.
Suggestions
Add a concrete example showing expected documentation output format (e.g., a sample markdown section with the project's preferred heading style, admonition format, or code block conventions).
Remove generic writing advice Claude already knows (e.g., 'Correct awkward wording, spelling, and grammar') and replace with project-specific conventions or anti-patterns unique to this codebase.
Add a quick-reference summary at the top listing the key files and commands (style-guide.md path, sidebar.json path, npm run format) so Claude can quickly orient without reading the full workflow.
| 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 file paths (packages/, docs/, docs/sidebar.json) and tool recommendations (replace vs write_file), but lacks concrete examples of expected output, markdown templates, or executable commands beyond the single `npm run format` mention. References to style-guide.md and CONTRIBUTING.md are good but the skill itself doesn't show what good documentation looks like. | 2 / 3 |
Workflow Clarity | The four-step workflow is clearly sequenced with logical progression from understanding → investigation → writing → verification. It includes validation checkpoints (re-read files, verify links, run formatting) and handles the branching case of writing vs editing. The verification step provides a reasonable feedback loop. | 3 / 3 |
Progressive Disclosure | The skill references external files (CONTRIBUTING.md, references/style-guide.md, docs/sidebar.json) which is good progressive disclosure, but these references are embedded within steps rather than clearly signaled in a navigation section. The skill itself is somewhat long for what it conveys and could benefit from a quick-start summary with references to detailed sub-guides. | 2 / 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
- tech-leads-club/agent-skills
- Commit
81e7e0d
- 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.