docs-update
Update user-facing documentation when code changes. Use when asked to update docs, review docs, handle documentation changes, run scheduled documentation tasks, or analyze recent commits for documentation needs.
76
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/skillValidation for skill structure
Discovery
82%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 a solid description that clearly communicates both purpose and trigger conditions. The explicit 'Use when...' clause with multiple trigger scenarios is a strength. However, the description could be more specific about what concrete actions it performs (e.g., updating READMEs, syncing changelogs, generating release notes) and could better distinguish itself from other documentation-related skills.
Suggestions
Add more specific concrete actions like 'sync READMEs with code changes', 'update API documentation', or 'generate changelog entries' to improve specificity
Include distinguishing context like 'user-facing docs in markdown' or specific file types to reduce potential conflicts with other documentation skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (documentation) and mentions actions like 'update', 'review', 'handle changes', 'run scheduled tasks', and 'analyze commits', but these are somewhat generic and don't describe concrete specific actions like 'generate API reference from code comments' or 'sync README with changelog'. | 2 / 3 |
Completeness | Clearly answers both what ('Update user-facing documentation when code changes') and when ('Use when asked to update docs, review docs, handle documentation changes, run scheduled documentation tasks, or analyze recent commits for documentation needs'). | 3 / 3 |
Trigger Term Quality | Good coverage of natural terms users would say: 'update docs', 'review docs', 'documentation changes', 'scheduled documentation tasks', 'analyze recent commits'. These are phrases users would naturally use when needing documentation help. | 3 / 3 |
Distinctiveness Conflict Risk | While it focuses on documentation, the term 'documentation' is broad and could overlap with API documentation skills, README generators, or general writing skills. The 'code changes' context helps but doesn't fully distinguish it from other doc-related skills. | 2 / 3 |
Total | 10 / 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 skill provides a well-structured workflow for documentation automation with clear sequencing and good coverage of edge cases. However, it lacks concrete executable examples (git commands, code snippets, template formats) that would make it immediately actionable, and could benefit from tighter prose and better progressive disclosure for platform-specific details.
Suggestions
Add concrete git commands for finding commits (e.g., `git log --since='24 hours ago' --oneline`) and example branch/commit operations
Include a sample PR description template and commit message format that can be copy-pasted
Add specific examples of platform detection (e.g., 'if mint.json exists -> Mintlify') rather than just listing platforms
Consider splitting platform-specific conventions into a separate reference file to keep the main skill leaner
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably efficient but includes some unnecessary elaboration. Lists like 'Skip documentation for' and 'Filter for significant changes' could be more compact, and some guidelines are somewhat verbose for what Claude would naturally understand. | 2 / 3 |
Actionability | Provides clear conceptual guidance but lacks concrete executable examples. No specific git commands, no code snippets for detecting platforms, no example commit message formats, and no sample PR description templates. The workflow describes what to do but not exactly how. | 2 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced with logical progression from identifying changes through execution. Testing vs execution modes are well-differentiated, and the workflow includes appropriate checkpoints like analyzing context before making changes. | 3 / 3 |
Progressive Disclosure | Content is reasonably organized with clear sections, but everything is in a single file. For a skill of this complexity, platform-specific guidance, example templates, and detailed multi-repo workflows could be split into referenced files for better navigation. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
93%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 15 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata' field is not a dictionary | Warning |
Total | 15 / 16 Passed | |
- 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.