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.
Install with Tessl CLI
npx tessl i github:google-gemini/gemini-cli --skill docs-writer67
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillAgent success when using this skill
Validation for skill structure
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 focuses almost entirely on when to trigger (file locations) while neglecting what the skill actually does. It lacks specific capabilities, concrete actions, and natural user language. The description reads more like a routing rule than a skill description.
Suggestions
Add specific capabilities the skill provides, e.g., 'Writes clear technical documentation, maintains consistent formatting, generates API references, creates README files'
Include natural trigger terms users would say: 'documentation', 'docs', 'markdown', 'README', 'technical writing', 'API docs'
Restructure to lead with capabilities, then follow with 'Use when...' clause that combines both file-based triggers and user intent triggers
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description mentions 'writing, reviewing, or editing files' which are generic actions, but provides no concrete capabilities specific to documentation work. It describes file locations rather than actual actions or features. | 1 / 3 |
Completeness | Has a clear 'when' clause ('Always use this skill when...') but the 'what' is extremely weak - it only says generic file operations without explaining what the skill actually does or what capabilities it provides. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like '/docs directory', '.md files', and 'repository', but misses common user phrases like 'documentation', 'markdown', 'README', 'docs', or 'write documentation'. | 2 / 3 |
Distinctiveness Conflict Risk | The file path triggers ('/docs', '.md') provide some distinctiveness, but 'writing, reviewing, or editing files' is generic enough to overlap with any code editing or file manipulation skill. | 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 skill with excellent workflow clarity and actionable guidance. The four-phase approach provides clear sequencing with validation checkpoints. However, the skill could be more concise by trimming explanations of writing principles that Claude already understands, and some detailed reference content could be moved to separate files for better progressive disclosure.
Suggestions
Condense the voice/tone and language/grammar sections to bullet-point rules only, removing explanatory context Claude already knows (e.g., remove 'Write precisely to ensure your instructions are unambiguous')
Consider extracting the detailed formatting and style rules into a separate STYLE_REFERENCE.md file, keeping only essential rules in the main skill
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some redundant explanations (e.g., detailed voice/tone guidance that Claude inherently understands). The formatting and grammar sections could be more condensed while preserving clarity. | 2 / 3 |
Actionability | Provides highly specific, actionable guidance with concrete examples throughout (e.g., exact phrasing like 'lets you' instead of 'allows you to', specific formatting rules, clear procedural steps). The four-phase workflow gives explicit instructions. | 3 / 3 |
Workflow Clarity | Excellent multi-phase workflow (Preparation → Execution → Verification) with clear sequencing and validation checkpoints. Phase 4 includes explicit verification steps (accuracy check, self-review, link check, format command) creating a proper feedback loop. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections and hierarchy, but everything is inline in a single file. References to external files (CONTRIBUTING.md, quota-limit-style-guide.md, sidebar.json) exist but the detailed style guide content could potentially be split into separate reference files. | 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.
- 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.