CtrlK
BlogDocsLog inGet started
Tessl Logo

update-docs

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

Quality

38%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/docs/skills/update-docs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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'.

DimensionReasoningScore

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.

DimensionReasoningScore

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.

Validation9 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

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

Repository
NeoLabHQ/context-engineering-kit
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.