docs-writer
Always use this skill when the task involves writing, reviewing, or editing files in the `/docs` directory or any `.md` files in the repository.
71
58%
Does it follow best practices?
Impact
91%
1.71xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.gemini/skills/docs-writer/SKILL.mdQuality
Discovery
40%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 description functions primarily as a trigger rule rather than a skill description. It tells Claude when to activate but fails to explain what the skill actually does — what specific capabilities, formatting standards, or documentation practices it provides. The lack of concrete actions and domain-specific detail makes it hard to distinguish from any generic file-editing skill.
Suggestions
Add specific capabilities the skill provides, e.g., 'Enforces documentation style guidelines, maintains consistent heading structure, generates table of contents, and ensures proper cross-linking between docs.'
Include natural trigger terms users would say, such as 'markdown', 'documentation', 'README', 'docs', 'technical writing', 'wiki'.
Restructure to lead with 'what it does' before 'when to use it', e.g., 'Writes and maintains project documentation following [specific standards]. Use when...'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions 'writing, reviewing, or editing files' which are generic actions. It does not describe any concrete, domain-specific capabilities — just broad file operations applied to a directory and file type. | 1 / 3 |
Completeness | It has a 'when' clause ('Always use this skill when...') but the 'what' is extremely weak — it only says 'writing, reviewing, or editing files' without explaining what the skill actually does or what value it provides. The 'when' is present but the 'what' is essentially missing. | 2 / 3 |
Trigger Term Quality | It includes some relevant keywords like '/docs directory', '.md files', 'writing', 'reviewing', 'editing', which are terms a user might naturally reference. However, it misses common variations like 'markdown', 'documentation', 'README', 'docs', or 'technical writing'. | 2 / 3 |
Distinctiveness Conflict Risk | The scope is narrowed to '/docs' directory and '.md' files, which provides some distinctiveness. However, 'writing, reviewing, or editing' is so broad that it could easily conflict with other skills that also handle markdown or documentation tasks. | 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 well-structured, highly actionable documentation writing skill with a clear four-phase workflow and good validation checkpoints. Its main weakness is length — the inline style guide content, while project-specific and necessary, makes the file long and could benefit from being split into a referenced style guide file. The skill excels at providing concrete, specific guidance with real examples rather than vague instructions.
Suggestions
Consider extracting the detailed style rules (voice/tone, language/grammar, formatting/syntax, links, structure) into a separate reference file like `docs-style-guide.md` and keeping only a brief summary in the main SKILL.md to improve progressive disclosure and reduce token usage.
Trim generic writing advice that Claude already knows (e.g., 'Use simple vocabulary', 'Write precisely to ensure your instructions are unambiguous') to improve conciseness — focus only on project-specific conventions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly long but most content is project-specific style guidance that Claude wouldn't inherently know (serial comma rules, project naming conventions, callout formatting with prettier-ignore). However, some sections explain concepts Claude already understands well (e.g., 'Use active voice and present tense,' 'Use simple vocabulary,' general writing advice), and the voice/tone section could be tightened significantly. | 2 / 3 |
Actionability | The skill provides highly concrete, specific guidance: exact formatting examples for callouts and details tags, specific tool recommendations (replace vs write_file), concrete commands (npm run format, npm install), specific file paths to check (docs/sidebar.json, packages/), and clear procedural steps. The callout examples with prettier-ignore comments are copy-paste ready. | 3 / 3 |
Workflow Clarity | The four-phase workflow (Standards → Preparation → Execution → Verification) is clearly sequenced with explicit validation checkpoints. Phase 2 has a numbered preparation checklist, Phase 4 includes verification steps (accuracy check, self-review, link check, format check), and there are feedback loops (e.g., if npm run format fails, run npm install first). The header-change → link-update validation is mentioned in multiple phases, reinforcing the checkpoint. | 3 / 3 |
Progressive Disclosure | The skill references external files like docs-auditing.md and quota-limit-style-guide.md for specialized topics, which is good progressive disclosure. However, the main SKILL.md itself is quite long (~200 lines) and the detailed style guide content (voice, grammar, formatting rules) could arguably be split into a separate reference file, keeping the SKILL.md as a leaner overview. No bundle files were provided to verify referenced paths exist. | 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
- google-gemini/gemini-cli
- Commit
77e65c0
- 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.