Update and maintain project documentation for local code changes using multi-agent workflow with tech-writer agents. Covers docs/, READMEs, JSDoc, and API documentation.
49
38%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/docs/skills/update-docs/SKILL.mdQuality
Discovery
50%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 provides a reasonable overview of what the skill covers—documentation maintenance across several formats—but lacks explicit trigger guidance ('Use when...') and concrete action verbs beyond 'update and maintain'. The mention of multi-agent workflow is a distinguishing detail but doesn't help Claude decide when to select this skill.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to update documentation after code changes, sync docs with code, or generate missing JSDoc/API docs.'
Replace vague verbs like 'update and maintain' with specific actions such as 'generate JSDoc comments, sync README files with code changes, update API reference docs, and add missing documentation for new modules.'
Include more natural trigger terms users might say, such as 'docs out of date', 'README.md', 'docstrings', 'documentation generation', or 'missing docs'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (project documentation) and lists some specific targets (docs/, READMEs, JSDoc, API documentation), but the actions are vague—'update and maintain' doesn't describe concrete operations like 'generate', 'sync with code changes', or 'add missing docstrings'. | 2 / 3 |
Completeness | The 'what' is partially addressed (update/maintain documentation using multi-agent workflow), but there is no explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied by the description of what it covers, which caps this at 2 per the rubric guidelines. | 2 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'READMEs', 'JSDoc', 'API documentation', and 'docs/' that users might mention. However, it misses common variations like 'docstrings', 'markdown', 'changelog', 'README.md', or phrases like 'update docs' or 'documentation is outdated'. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'multi-agent workflow with tech-writer agents' and specific targets like JSDoc and docs/ folder adds some distinctiveness, but 'project documentation' is broad enough to potentially overlap with general documentation or code commenting skills. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill suffers from severe verbosity, attempting to be both an orchestration workflow and a comprehensive documentation philosophy guide. While the multi-agent workflow structure is reasonable and the agent templates provide useful scaffolding, the bulk of the content (documentation philosophy, tool comparisons, audit guidelines, pattern references) is general knowledge that Claude already possesses and should be removed or extracted to separate files. The skill would benefit enormously from being cut to ~25% of its current size.
Suggestions
Remove or extract to separate files the entire 'Core Documentation Philosophy', 'Documentation Tools and Their Sweet Spots', 'Documentation Audit Guidelines', and 'Documentation Patterns Reference' sections — these are general knowledge Claude already has and consume excessive tokens.
Add concrete validation commands or checks in the quality review step (e.g., link checking commands, specific criteria for PASS/FAIL) rather than abstract quality descriptions.
Include the referenced tech-writer.md agent file as a bundle file, or inline the essential instructions from it, since the skill depends on it multiple times.
Consolidate the agent instruction templates into a more compact format — the three templates repeat similar context-passing patterns and could be reduced to a single parameterized template with role-specific additions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Includes extensive philosophy sections ('Documentation Hierarchy', 'What NOT to Document', 'Red Flags'), tool comparisons (OpenAPI vs GraphQL vs Prisma sweet spots), README best practices, JSDoc best practices, and audit guidelines that Claude already knows. The 'Documentation Tools and Their Sweet Spots' section alone is pure padding. Much of this content explains general documentation principles rather than providing skill-specific instructions. | 1 / 3 |
Actionability | Provides concrete bash commands for discovery and agent instruction templates with clear structure, but the actual documentation writing guidance is largely abstract ('Focus on helping users accomplish tasks', 'Follow project conventions'). The agent templates use placeholders like {DOCUMENTATION_AREA} and {CHANGED_FILES_LIST} without showing how to populate them. Code examples exist but are mostly for discovery (find commands) rather than the core documentation task. | 2 / 3 |
Workflow Clarity | The multi-step workflow (Preparation → Analysis → Planning → Writing → Review) is clearly sequenced with numbered steps and a decision point for simple vs. multi-agent flow. However, validation is weak — the quality review step says 'PASS confirmation or list of issues to fix' but lacks concrete validation criteria or commands. The iteration step (step 10) is vague ('if any documentation areas have quality issues'). The workflow also lacks explicit checkpoints between phases. | 2 / 3 |
Progressive Disclosure | No bundle files are provided, yet the skill references external files like '@/plugins/sdd/agents/tech-writer.md' and a 'SADD skill' without including them. The content is a monolithic wall of text with massive inline sections (Documentation Philosophy, Documentation Tools, Audit Guidelines, Patterns Reference) that should be in separate referenced files. The skill tries to be both a workflow guide and a comprehensive documentation handbook, resulting in poor organization. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (661 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
dedca19
Table of Contents
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.