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

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 communicates a clear purpose—syncing documentation with code changes on the current branch—but lacks an explicit 'Use when...' clause and doesn't enumerate specific concrete actions beyond 'update.' It would benefit from richer trigger terms and clearer activation guidance to distinguish it from general documentation skills.

Suggestions

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

Include natural trigger term variations such as 'docs', 'API docs', 'README', 'sync documentation', 'outdated docs', 'docstrings'.

List more specific actions, e.g., 'Identifies changed functions and classes, updates corresponding doc pages, and flags documentation gaps.'

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.	2 / 3
Trigger Term Quality	Includes some relevant terms 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', or 'README'.	2 / 3
Distinctiveness Conflict Risk	The mention of 'documentation pages' and 'source code changes on the current branch' provides some specificity, but 'update documentation' could overlap with general documentation writing or editing skills.	2 / 3
	Total	8 / 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-crafted, highly actionable skill for a complex multi-step documentation update workflow. Its greatest strengths are the precise, executable commands and the thorough step-by-step sequencing with validation. The main weakness is its length — at ~300 lines it's quite dense, and some content (like the full page template and docs.json insertion instructions) could be offloaded to referenced files for better progressive disclosure.

Suggestions

Consider splitting the new page template (Step 8a), docs.json instructions (Step 8b), and supported-services instructions (Step 8c) into separate referenced 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 and specific to this workflow. Some sections could be tightened (e.g., the overview repeats the description, and some guidance like 'Don't rewrite working examples just to add new optional params' is somewhat obvious for Claude), but overall the length is justified by the complexity of the multi-step process.	2 / 3
Actionability	The skill provides fully executable bash commands, specific file paths, concrete code templates (MDX frontmatter, ParamField tags, table formats), exact grep patterns, and detailed section-specific editing guidance. Every step has concrete, copy-paste-ready instructions.	3 / 3
Workflow Clarity	The 9-step workflow is clearly sequenced with logical dependencies (resolve path → create branch → detect changes → map → analyze → edit → update guides → identify gaps → summarize). It includes validation checkpoints (verify path exists, read before editing, checklist at the end), feedback loops (Step 8 identifies gaps and offers remediation), and a comprehensive final checklist.	3 / 3
Progressive Disclosure	The skill references an external mapping file (`.claude/skills/update-docs/SOURCE_DOC_MAPPING.md`) which is good progressive disclosure, but no bundle files were provided to verify it exists. The main SKILL.md itself is quite long and monolithic — the section-specific guidance (Step 6), new page template (Step 8a), and docs.json/supported-services instructions (Steps 8b/8c) could potentially be split into separate reference files to keep the main skill leaner.	2 / 3
	Total	10 / 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: ea296ba

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.