update-docs
Update documentation pages to match source code changes on the current branch
68
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
32%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description communicates a clear purpose—syncing documentation with code changes—but lacks the explicit trigger guidance required for Claude to reliably select it from a large skill set. It would benefit from more specific actions and natural trigger terms users would actually say when needing this functionality.
Suggestions
Add a 'Use when...' clause with trigger terms like 'sync docs', 'update documentation', 'docs out of date', 'documentation doesn't match code'
Include specific concrete actions such as 'update API references', 'sync function signatures', 'update code examples', 'regenerate docstrings'
Add common keyword variations like 'docs', 'README', 'API documentation', '.md files' to improve trigger term coverage
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (documentation) and a general action (update to match source code changes), but lacks specific concrete actions like 'update API references', 'sync function signatures', or 'regenerate examples'. | 2 / 3 |
Completeness | Describes what it does (update documentation to match source code) but completely lacks a 'Use when...' clause or any explicit trigger guidance for when Claude should select this skill. | 1 / 3 |
Trigger Term Quality | Contains relevant keywords like 'documentation', 'source code', and 'branch', but misses common variations users might say such as 'docs', 'README', 'API docs', 'sync docs', or 'outdated documentation'. | 2 / 3 |
Distinctiveness Conflict Risk | The phrase 'current branch' and focus on documentation-source code synchronization provides some distinctiveness, but 'documentation' is broad enough to potentially conflict with general documentation writing or editing skills. | 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 skill for a complex multi-step documentation workflow. The workflow clarity is excellent with explicit validation steps and a final checklist. However, the skill could benefit from moving the template structure and some detailed guidance to external reference files to improve token efficiency.
Suggestions
Move the 'template structure' for new pages to a separate reference file (e.g., DOC_TEMPLATE.md) and link to it
Consider moving 'Section-specific guidance' to an external file since it's detailed reference material rather than core workflow
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some redundant explanations. The step-by-step format is appropriate for the complexity, but sections like 'Section-specific guidance' could be tightened. The template structure at the end adds bulk that could be referenced externally. | 2 / 3 |
Actionability | Provides fully executable bash commands, specific file paths, concrete examples of branch naming, and detailed section-specific guidance. The grep command, git commands, and output summary format are all copy-paste ready. | 3 / 3 |
Workflow Clarity | Excellent 9-step workflow with clear sequencing. Includes validation checkpoints (verify path exists, read before editing), explicit feedback loops (check guides after reference docs), and a comprehensive checklist at the end for verification. | 3 / 3 |
Progressive Disclosure | References external file SOURCE_DOC_MAPPING.md appropriately, but the skill itself is quite long with the full template structure inline. The section-specific guidance and template could be split into separate reference files for better organization. | 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.