CtrlK
BlogDocsLog inGet started
Tessl Logo

update-docs

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

59

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

85%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.

A strong, highly actionable workflow document: concrete commands, explicit validation and error-recovery loops, and nuanced judgment rules that consistently assume Claude's intelligence. Its weaknesses are structural — everything lives inline in one long file with a dangling PROFILE_CONTRACT.md reference — and mild redundancy in the proportionality guidance across three sections.

Suggestions

Split stable reference material out of the monolith into bundled files (e.g. references/frontmatter-conventions.md, references/llms-txt-regeneration.md, references/PROFILE_CONTRACT.md) and signal them clearly from the relevant steps.

Fix the dangling "See PROFILE_CONTRACT.md" reference — either ship the file in the skill's references/ directory or describe the profile contract inline.

Deduplicate the proportionality / write-for-a-future-reader guidance, which currently appears in Step 6's Proportionality section, the Guidelines, and the Checklist; state it once authoritatively and let the checklist reference it.

DimensionReasoningScore

Conciseness

The body is dense and almost every line encodes a non-obvious rule Claude could not infer (scope-as-exclusions, format-before-regenerate ordering, deprecation marking), with no explaining of concepts Claude already knows. It is not 5 because the proportionality/'write for a future reader' guidance is restated three times across Step 6's Proportionality section, the Guidelines, and the Checklist, and could be tightened into one place.

4 / 5

Actionability

Commands are copy-paste ready ("git diff main..HEAD --name-only", "cd DOCS_PATH && git checkout main && git pull && git checkout -b {branch-name}-docs", "npx prettier --ignore-unknown --write <edited files>", "node scripts/gen-llms-txt.mjs"), the mapping procedure is a concrete ordered 6-step decision procedure with existence checks, and the output summary is a literal template. The template placeholders that remain ({branch-name}, profile dirs) are explicitly justified flexibility, matching the top anchor.

5 / 5

Workflow Clarity

Ten clearly sequenced steps with explicit validation checkpoints and feedback loops: verify path contains docs.json (Step 1), stop-and-report on missing profile, confirm every candidate page exists before editing (Step 4), fall through to search when a candidate doesn't resolve, unmapped files surfaced as Step 8 findings rather than dropped, format-before-regenerate ordering, a lint script that reports what CI will, and a final checklist. This matches the anchor for clear sequence with explicit validation and error-recovery loops.

5 / 5

Progressive Disclosure

The body is one ~340-line monolith with good internal headers, but it is far past the size where stable reference material (frontmatter conventions, llms.txt regeneration procedure, deprecation rules) belongs in separate reference files, and "See PROFILE_CONTRACT.md for what a profile must provide" points to a file that is not in this bundle — a dangling, unsignaled reference. This fits 'Some structure but could be better organized; references present but not clearly signaled' rather than 4, whose references are mostly clear and content mostly appropriately split.

3 / 5

Total

17

/

20

Passed

Description

53%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 specific and clearly states what the skill does, but it omits any 'when to use it' trigger guidance and lacks the natural synonym phrasings (docs, stale, out of date) users would say. Adding an explicit trigger clause and one or two more concrete actions would lift it substantially.

Suggestions

Add an explicit trigger clause, e.g. "Use when the user asks to update, sync, or fix documentation after code changes on a branch, or mentions docs being out of date with source code."

Include natural user phrasings and synonyms such as "docs", "stale documentation", and "sync docs with code changes" so the description triggers on how users actually ask.

Mention one or two more concrete actions (e.g. "maps changed source files to doc pages and reports unmapped files") to broaden capability coverage without padding.

DimensionReasoningScore

Specificity

"Update documentation pages to match source code changes on the current branch" names the domain and one concrete, well-scoped action (updating doc pages against the branch diff), but lists no secondary actions (mapping files to pages, editing guides, reporting gaps). This matches the anchor 'Names domain and 1-2 concrete actions, but not comprehensive' — not 4, which requires several specific actions, and not 2, since the action is concrete rather than generic.

3 / 5

Completeness

The 'what' is clear (update doc pages to match branch changes), but there is no 'Use when...' or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 4 because the 'when' is entirely absent rather than present-but-imprecise.

3 / 5

Trigger Term Quality

Relevant keywords are present ("documentation", "source code changes", "current branch"), but common user phrasings are missing: "docs", "stale docs", "out of date", "sync docs with code". This fits 'Some relevant keywords but missing common variations or synonyms' rather than 4, whose keyword coverage includes the natural terms users would actually say.

3 / 5

Distinctiveness Conflict Risk

The niche — syncing documentation to a branch's source diff — is fairly distinct from generic doc-editing or writing skills, with differentiating terms like "source code changes" and "current branch". Minor overlap risk remains with general documentation-maintenance skills, so it fits 'Mostly distinct; minor overlap risk' rather than 5's 'clear niche with minimal conflict risk'.

4 / 5

Total

13

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 2 missing

Warning

Total

15

/

16

Passed

Repository
pipecat-ai/pipecat
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.