CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

update-docs

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

Quality

74%

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.

This is a strong instruction-only skill: a well-sequenced ten-step workflow with concrete commands, explicit validation and feedback loops, and precise editing rules that assume Claude's competence. Its main weaknesses are mild redundancy of key safety rules and a monolithic structure whose two referenced companion files (PROFILE_CONTRACT.md, REVIEW.md) are absent from the bundle.

Suggestions

Ship PROFILE_CONTRACT.md and REVIEW.md with the skill (or fold the needed contract details inline) so the body's references resolve within the bundle.

Move docs-repo-specific detail — the frontmatter conventions and the llms.txt regeneration procedure — into a reference file, keeping SKILL.md as the process overview.

State the never-drop-a-file and confirm-path-exists rules once (Step 4) and reference them from Steps 3 and 8 instead of repeating them, which would also trim tokens.

DimensionReasoningScore

Conciseness

Nearly every line is task-specific instruction with no explanation of concepts Claude already knows — concrete commands, thresholds, and decision rules throughout. Minor over-explanation could be trimmed: "Confirm every candidate path exists in DOCS_PATH before using it" is restated as "Never edit a path you haven't confirmed exists" in the same step, and the never-drop-a-file rule appears in Step 3 ("should reach Step 8 as a reported gap rather than disappear"), Step 4 ("Never resolve a file by dropping it"), and again in Step 8. That repetition keeps it below the score-5 lean anchor.

4 / 5

Actionability

Fully executable guidance: copy-paste commands ("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"), exact conventions ("title: 50 chars max", "description: 110-140 chars"), a six-step ordered mapping algorithm with fallbacks, and an exact output summary template cover the common cases.

5 / 5

Workflow Clarity

Ten explicitly sequenced steps with validation checkpoints and feedback loops throughout: "If it is missing, stop and say so", "Never edit a path you haven't confirmed exists", "Fix every finding on a page you edited", and "Fix anything that fails before continuing", plus the "Review every edited page" re-read pass and a final Checklist. Validation is present, so the batch-operation cap does not apply.

5 / 5

Progressive Disclosure

The bundle contains no references/, scripts/, or assets/ files, so the ~350-line body is monolithic; the body points to "PROFILE_CONTRACT.md" and "REVIEW.md", which are not present in the bundle, leaving those references unverifiable. Not 2 because sections are well-organized and external-by-design files (the repo's SOURCE_DOC_MAPPING.md profile and STYLE.md) are clearly explained and one level deep; not 4 because docs-repo-specific detail (frontmatter conventions, llms.txt regeneration) is inlined and two referenced files are dangling in this bundle.

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 third-person, concrete about what it does, and anchored to a specific context (the current branch's diff), but it names only one composite action and omits any explicit when-to-use clause. It reads as a clear niche skill that would benefit from a trigger clause and enumerated actions.

Suggestions

Add an explicit trigger clause, e.g. "Use when source code changes on the current branch need their documentation pages updated."

Enumerate the concrete actions the skill performs — e.g. "maps changed source files to doc pages, edits reference pages and guides, registers new pages, and regenerates llms.txt".

Include natural synonyms users would say when invoking it, such as "docs", "documentation update", or "keep the docs in sync with code changes".

DimensionReasoningScore

Specificity

"Update documentation pages to match source code changes on the current branch" names the domain and one composite action, matching the anchor for 1-2 concrete actions without comprehensive coverage. It does not list several distinct actions (map files to pages, edit guides, register new pages), which the score-4 anchor requires.

3 / 5

Completeness

The "what" is clear and concrete, but there is no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. "On the current branch" weakly implies timing but is not explicit usage guidance.

3 / 5

Trigger Term Quality

Relevant keywords are present ("documentation", "source code changes", "current branch") but common variations users would naturally say are missing — "docs", "update the docs", "keep docs in sync". This matches the score-3 anchor of some relevant keywords missing synonyms.

3 / 5

Distinctiveness Conflict Risk

"Documentation pages" tied to "source code changes on the current branch" carves a distinct docs-sync niche with minimal conflict against generic writing or doc-generation skills. Not 5 because without trigger phrases it could still fire on broad "update the docs" requests that don't involve a code diff.

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

Path

.claude/skills/update-docs/SKILL.md

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.