update-docs

Update documentation pages to match source code changes on the current branch

1.17x

Quality

63%

Does it follow best practices?

Impact

100%

1.17x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/update-docs/SKILL.md

Quality

Content

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-crafted, highly actionable skill for a complex documentation synchronization workflow. Its greatest strengths are the precise, executable commands and the thorough step-by-step sequencing with clear decision logic. The main weakness is that the skill is quite long and could benefit from externalizing reference material (templates, category mappings) into supporting bundle files to improve progressive disclosure and reduce token cost.

Suggestions

Extract the doc page template (Step 8a), docs.json category mappings (Step 8b), and supported-services format (Step 8c) into separate bundle files to reduce the main skill's token footprint.

Provide the referenced SOURCE_DOC_MAPPING.md as a bundle file so the skill is self-contained and the reference can be validated.

Dimension	Reasoning	Score
Conciseness	The skill is quite long (~300 lines) but most content is genuinely instructional for a complex multi-step workflow. Some sections like the template in Step 8a and the detailed category mappings in 8b could be externalized. Minor verbosity in explaining obvious things like 'If DOCS_PATH was provided as an argument, use it.'	2 / 3
Actionability	Highly actionable with specific bash commands, exact file paths, concrete code examples, precise formatting templates (<ParamField> tags, markdown tables), and clear rules for each doc section type. The guidance is copy-paste ready throughout.	3 / 3
Workflow Clarity	Excellent 9-step sequential workflow with clear dependencies between steps. Includes validation via the final checklist, explicit decision points (e.g., 'If the user wants a new page, do all three'), and a tiered lookup system with 'first match wins' logic. The checklist at the end serves as a verification checkpoint.	3 / 3
Progressive Disclosure	References SOURCE_DOC_MAPPING.md as an external file (good), but the skill itself is monolithic with substantial inline content that could be split out — the doc page template (Step 8a), the docs.json category mapping (Step 8b), and the supported-services format (Step 8c) could all be separate reference files. No bundle files were provided to verify the referenced mapping file exists.	2 / 3
	Total	10 / 12 Passed

Description

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 communicates a clear purpose—syncing documentation with code changes on the current branch—but lacks explicit trigger guidance ('Use when...') and could benefit from more specific actions and natural keyword variations. It is functional but not optimally discoverable among a large set of skills.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to sync docs, update documentation after code changes, or ensure docs reflect the latest code on the current branch.'

Include natural keyword variations users might say: 'docs', 'API docs', 'sync documentation', 'outdated docs', 'doc updates'.

List more specific concrete actions, e.g., 'Updates documentation pages to reflect API changes, new functions, modified parameters, and removed features based on source code diffs on the current branch.'

Dimension	Reasoning	Score
Specificity	Names the domain (documentation pages, source code changes) and a single action (update), but doesn't list multiple concrete actions like 'sync API docs, update code examples, regenerate references'.	2 / 3
Completeness	Answers 'what' (update documentation to match source code changes) but lacks an explicit 'Use when...' clause or trigger guidance, which caps this dimension at 2 per the rubric guidelines.	2 / 3
Trigger Term Quality	Includes some relevant keywords like 'documentation', 'source code changes', and 'current branch', but misses common variations users might say such as 'docs', 'API docs', 'sync docs', 'outdated documentation', 'docstring'.	2 / 3
Distinctiveness Conflict Risk	Somewhat specific with the combination of documentation + source code changes + current branch, but could overlap with general documentation skills or code review skills. The 'current branch' qualifier adds some distinctiveness.	2 / 3
	Total	8 / 12 Passed

Validation

100%

Warnings & errors only

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.

Repository: pipecat-ai/pipecat
Commit: 8fe21bf

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.