update-docs

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

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

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

The body is highly actionable with concrete commands and templates, and the workflow is clearly sequenced with validation and a final checklist. Its main weaknesses are mild verbosity in inline reference-like material and limited use of separate reference files for progressive disclosure.

Suggestions

Move the new-page template block (Step 8a) and the docs.json group-to-group mapping into a separate reference file referenced one level deep, to improve progressive disclosure and reduce inline length.

Tighten the docs.json navigation group list and supported-services.mdx instructions, which read as inline reference data that could be condensed or externalized.

Add an explicit per-edit verification feedback loop (e.g., re-read the edited section and confirm it matches source) between Step 6 and the final Checklist to strengthen the batch-edit validation path.

Dimension	Reasoning	Score
Conciseness	The body is dense with task-specific procedural knowledge rather than concepts Claude already knows, but at roughly 330 lines the inline page template and docs.json group list could be tightened, so it is mostly efficient rather than fully lean.	2 / 3
Actionability	It provides concrete executable commands ('git diff main..HEAD --name-only', grep), exact path globs, and copy-paste-ready format templates like '<ParamField path="name" type="type">'.	3 / 3
Workflow Clarity	Nine clearly sequenced steps include a validation checkpoint in Step 1, gap detection in Step 8, and a comprehensive final Checklist, so verification is present for this batch operation and the cap-at-2 note does not apply.	3 / 3
Progressive Disclosure	There is one well-signaled one-level-deep reference ('.claude/skills/update-docs/SOURCE_DOC_MAPPING.md'), but no bundle files exist and substantial content such as the page template and group-to-group mapping is inline rather than split into reference files.	2 / 3
	Total	10 / 12 Passed

Description

57%

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 specific and occupies a clear niche, but it answers only 'what' and lacks an explicit 'when to use' trigger clause plus common keyword variations, which hold it at the 2-level on most dimensions.

Suggestions

Add a 'Use when...' clause with explicit triggers, e.g. 'Use when documentation has fallen behind source code changes on a feature branch.'

Include natural keyword variations users would actually say, such as 'sync docs', 'update API reference', or 'docs out of date'.

Optionally enumerate the concrete actions (map source to doc pages, edit sections, add new pages to docs.json) to lift specificity to 3.

Dimension	Reasoning	Score
Specificity	Names the domain and a concrete action ('Update documentation pages to match source code changes on the current branch') but lists a single action rather than multiple specific concrete actions, so it falls short of anchor 3.	2 / 3
Completeness	Clearly states what the skill does but omits any 'Use when...' trigger guidance, so 'when' is only implied — the missing trigger clause caps completeness at 2.	2 / 3
Trigger Term Quality	Relevant terms like 'documentation', 'source code', and 'branch' appear, but common user variations ('sync docs', 'docs out of date') are missing and no explicit trigger clause is present.	2 / 3
Distinctiveness Conflict Risk	The narrow niche of syncing documentation to source-code changes on the current branch is distinct and unlikely to trigger for unrelated skills.	3 / 3
	Total	9 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 suspicious	Warning

	Total	15 / 16 Passed

Repository: pipecat-ai/pipecat
Commit: 037ee5d

Reviewed: 4 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.