update-docs

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

Quality

61%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/update-docs/SKILL.md

Quality

Content

77%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a highly actionable, well-sequenced workflow skill with strong validation and feedback loops. Its main weakness is progressive disclosure: a lot of reference-style material (page template, docs.json group tables) is inlined in SKILL.md rather than split into bundle files.

Suggestions

Move the Step 8a page template and the Step 8b docs.json navigation group table into a reference file (e.g. references/page-template.mdx and references/docs-json-groups.md) and link to them, leaving only the resolution logic inline.

Extract the Step 3 source-glob filters and Step 7 guide directory list into a reference file so the core workflow stays lean.

Consider moving the Guidelines and Checklist sections into a references/best-practices.md to reduce SKILL.md length while keeping the procedural steps front and center.

Dimension	Reasoning	Score
Conciseness	The body is largely efficient and directive, but at ~375 lines it carries some padded material (the full 8a page template, the 8b docs.json insertion example with ellipses, and the detailed guidelines/checklist) that could be moved to a reference file to trim context.	3 / 5
Actionability	Concrete, copy-pasteable commands and code throughout (git rev-parse, git diff filters, grep, prettier, gen-llms-txt), with specific file-glob filters, MDX template structures, and exact table/ParamField formats.	5 / 5
Workflow Clarity	Ten explicitly numbered steps with a clear sequence, validation checkpoints (confirm candidate paths exist before editing, verify docs path subdirectory), and a closing checklist; destructive/batch edits are guarded by 'never edit a path you haven't confirmed exists' and a regenerate-before-format ordering note.	5 / 5
Progressive Disclosure	No bundle files exist and the SKILL.md inlines a large amount of detail (full page template, docs.json navigation groups, supported-services table format) that would better live in separate reference files; the one external reference (SOURCE_DOC_MAPPING.md) is correctly signaled but the bulk is inline.	3 / 5
	Total	16 / 20 Passed

Description

46%Weight 40%Scale 1-5

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 is clear and third-person but reads as a 'what' statement with no explicit 'when to use' trigger guidance. Adding a 'Use when...' clause with natural trigger terms would lift both completeness and trigger_term_quality.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when docs are out of date with source changes on the current branch or the user asks to sync documentation.'

Include natural trigger terms and synonyms users would actually say ('docs', 'keep docs in sync', 'out of date', 'documentation').

Mention a second concrete action (e.g. maps changed source files to doc pages) to broaden the specificity of capabilities.

Dimension	Reasoning	Score
Specificity	Names the domain ('Update documentation pages') and one concrete action ('match source code changes'), but the single sentence does not enumerate multiple specific actions like analyzing diffs, mapping files, or making targeted edits.	3 / 5
Completeness	It states clearly what the skill does but lacks any 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	The phrase 'Update documentation pages' is a reasonable natural trigger but there are no synonyms or variations ('docs', 'keep docs in sync', 'docs out of date') and no trigger phrasing a user would naturally say.	2 / 5
Distinctiveness Conflict Risk	The scope (updating docs to match source changes on the current branch) is a fairly distinct niche with minor overlap risk against general documentation or writing skills.	4 / 5
	Total	12 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 suspicious	Warning
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	14 / 16 Passed

Repository: pipecat-ai/pipecat
Path: .claude/skills/update-docs/SKILL.md
Commit: 6659b78

Reviewed: 1 day 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.