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.
64
51%
Does it follow best practices?
Impact
77%
1.50xAverage 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 ('always use when...') rather than a proper skill description. It tells Claude when to activate but fails to explain what the skill actually does — what specific guidance, formatting standards, or documentation practices it provides. The lack of concrete capabilities makes it hard to distinguish from a 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 more natural trigger terms users would say, such as 'markdown', 'documentation', 'README', 'docs site', 'technical writing', 'API docs'.
Rewrite to lead with what the skill does before stating when to use it, e.g., 'Guides documentation writing with consistent formatting, style, and structure for markdown files. 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 clear '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 just generic file operations. | 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 site', etc. | 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 coding/editing skills, and any skill that touches markdown files could conflict. | 2 / 3 |
Total | 7 / 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 writing skill with a well-structured four-phase workflow and good project-specific conventions. Its main weaknesses are verbosity in the style guide sections (much of which is standard technical writing knowledge Claude already possesses) and a monolithic structure that could benefit from splitting reference material into separate files. The actionability could be improved with more concrete examples of inputs and expected outputs.
Suggestions
Move the detailed style guide rules (voice/tone, language/grammar, formatting) into a separate reference file (e.g., STYLE_REFERENCE.md) and keep only project-specific conventions and deviations from standard practice in the main skill file.
Remove or drastically condense guidance Claude already knows (active voice, serial comma, avoid jargon, use 'you') and focus on project-specific rules like the Gemini CLI naming convention, callout formatting with prettier-ignore, and quota/limit terminology.
Add a concrete before/after example showing a documentation edit that applies the skill's standards, so Claude can see the expected transformation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is fairly well-organized but includes some content that Claude already knows (e.g., basic writing advice like 'use active voice,' 'avoid jargon,' 'use serial comma'). The voice/tone and language/grammar sections could be significantly condensed since much of this is standard technical writing knowledge. However, project-specific conventions (Gemini CLI naming, callout formatting, prettier-ignore comments) earn their place. | 2 / 3 |
Actionability | The skill provides concrete formatting examples (callouts, details tags) and specific commands (`npm run format`), but many instructions remain at the level of general guidance rather than executable specifics. For instance, the editing workflow says 'use replace for small edits and write_file for new files' but doesn't show concrete examples of when/how. The preparation and verification phases are procedural but lack concrete examples of what the output should look like. | 2 / 3 |
Workflow Clarity | The four-phase workflow (Standards → Preparation → Execution → Verification) is clearly sequenced with explicit validation steps in Phase 4 (accuracy check, self-review, link check, format command). The preparation phase includes a clear investigate-before-acting pattern, and the verification phase includes a feedback loop for link checking when headers change. This is a well-structured multi-step process with appropriate checkpoints. | 3 / 3 |
Progressive Disclosure | The content references external files (CONTRIBUTING.md, quota-limit-style-guide.md, sidebar.json) appropriately, but the skill itself is quite long and monolithic. The detailed style guide rules (voice, tone, grammar, formatting) could be split into a separate reference file, with SKILL.md serving as a concise overview pointing to those details. The inline content is well-sectioned but could benefit from better separation of reference material from workflow instructions. | 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
- google-gemini/gemini-cli
- Commit
9f76f34
- 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.