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, guidelines, or formatting standards it provides for documentation work. The lack of concrete actions and domain-specific detail makes it hard to distinguish from a generic file editing skill.
Suggestions
Add specific capabilities the skill provides, e.g., 'Applies documentation style guidelines, maintains consistent heading structure, ensures proper cross-linking between docs' instead of just 'writing, reviewing, or editing files'.
Include more natural trigger terms users would say, such as 'markdown', 'documentation', 'README', 'docs', 'technical writing', 'wiki'.
Restructure to separate 'what it does' from 'when to use it' — e.g., 'Enforces documentation standards, formatting conventions, and style guidelines for project documentation. Use when writing, reviewing, or editing files in /docs or any .md files.'
| 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 '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 broad enough that it could overlap with general code editing or writing skills, and any skill that touches markdown files could conflict. | 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 documentation writing skill with a clear four-phase workflow and highly actionable guidance, particularly for project-specific conventions like callout formatting, link management, and naming rules. Its main weakness is verbosity—many general technical writing principles (active voice, serial comma, avoid jargon) are things Claude already knows and inflate the token cost. The inline style guide could benefit from being extracted into a reference file for better progressive disclosure.
Suggestions
Extract general technical writing rules (voice/tone, grammar basics) into a separate reference file and keep only project-specific conventions inline to improve conciseness.
Remove or significantly condense universally-known writing advice (active voice, avoid jargon, use contractions) since Claude already follows these conventions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly detailed and well-organized, but includes some content Claude already knows (e.g., basic writing advice like 'use active voice,' 'avoid jargon,' serial comma rules). Some sections like voice/tone and grammar could be tightened since these are standard technical writing conventions. However, project-specific rules (Gemini CLI naming, prettier-ignore patterns, quota/limit terminology) earn their place. | 2 / 3 |
Actionability | The skill provides highly concrete, actionable guidance: specific formatting examples (callouts with prettier-ignore comments, details tags), exact commands (`npm run format`, `npm install`), specific tool choices (`replace` for small edits, `write_file` for new files), and clear rules with examples. The phases provide a structured, executable workflow. | 3 / 3 |
Workflow Clarity | The four-phase workflow (Standards → Preparation → Execution → Verification) is clearly sequenced with explicit validation checkpoints. Phase 2 includes investigation and planning before changes. Phase 4 includes accuracy checks, self-review, link verification, and formatting validation with a feedback loop (npm install if npm run format fails). The workflow handles the destructive nature of documentation edits well. | 3 / 3 |
Progressive Disclosure | The skill references external files appropriately (docs-auditing.md, CONTRIBUTING.md, quota-limit-style-guide.md), but the main body is quite long with all style guide rules inline. The formatting standards, voice/tone guidelines, and grammar rules could potentially be split into a separate reference file, with SKILL.md serving as a leaner overview pointing to them. | 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
0758a5e
- 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.