CtrlK
BlogDocsLog inGet started
Tessl Logo

skill-doc-sync

Post-ship doc sync across project markdown. Use when: sync docs, update docs, document changes, release notes.

60

Quality

71%

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/skill-doc-sync/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

The body is a well-organized, highly actionable workflow with concrete, mostly executable bash for every step and thoughtful safety rails (file cap, append-only CHANGELOG, risky-section approval). Its main weakness is verification: mechanical batch edits are committed without a review/validate checkpoint, and the PR-body update step's code does not actually perform the update it promises.

Suggestions

Add a validation checkpoint before committing: show the doc diff (git diff --cached) and require user confirmation or at least an explicit review pass, since this is a batch edit across up to 30 files followed by an automatic commit.

Fix the PR-body step so the snippet actually updates the body (e.g. gh pr edit --body with the appended doc-sync section) instead of only resolving and echoing the PR number.

Make the staging command cover everything the discovery step found (e.g. stage from the discovered DOC_FILES list rather than `git add *.md docs/*.md`, which misses nested files at depth 2).

DimensionReasoningScore

Conciseness

The body is efficient — terse bash snippets, bulleted rules, and short 'WHY:' rationale with no explanation of concepts Claude already knows — but minor padding remains (the fixed commit-message boilerplate, and the Integration section's near-duplicate invocation examples), matching "Efficient; minor instances of over-explanation that could be trimmed" rather than the every-token-earns-its-place of a 5.

4 / 5

Actionability

Most steps ship copy-paste-ready commands (doc discovery with exclusions, branch-aware diff logic, version-consistency greps, TODO diff greps), but there are real gaps: the PR-body snippet only echoes the PR number without ever updating the body, and `git add *.md docs/*.md` misses nested files that the maxdepth-2 discovery would have found — fitting "Mostly executable guidance; concrete code or commands with minor gaps" rather than the fully-executable coverage of a 5.

4 / 5

Workflow Clarity

The 9-step sequence is clearly ordered with a good risky-change approval gate, but this is a batch operation (auto-editing up to 30 files then auto-committing) with no verification of the mechanical edits — no review of the doc diff before commit and no post-commit check. The rubric's guideline caps batch workflows lacking validation at 3, which fits "Steps listed but validation gaps"; it stays above a 2 because the sequence and risky-change checkpoint are genuinely present.

3 / 5

Progressive Disclosure

A single well-sectioned file with clear step headers, no nested or dead-end references, and code colocated with its step — matching "Good structure; most content is appropriately placed". It falls short of a 5 because at ~250 lines some self-contained material (CHANGELOG voice rules and transformations, consistency-check scripts) could be split into reference files to keep SKILL.md a leaner overview.

4 / 5

Total

15

/

20

Passed

Description

73%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 compact and correctly structured, with an explicit trigger clause covering natural user phrasings and a distinct post-ship niche. Its main weakness is that the 'what' is a single generic action — it never states the concrete sub-actions the skill performs (factual corrections, consistency checks, changelog polish, PR body update).

Suggestions

Replace the generic 'doc sync' with the skill's concrete actions, e.g. 'Auto-update stale paths, counts, and version references in project markdown, verify cross-doc consistency, polish CHANGELOG entries, and update the PR body.'

Add trigger variations users would naturally say, such as 'update documentation after merge', 'update readme', or 'changelog', to widen keyword coverage and sharpen distinctiveness against generic doc-editing skills.

DimensionReasoningScore

Specificity

"Post-ship doc sync across project markdown" names the domain distinctly but the action is a single generic verb ("sync"), matching the anchor "Names the domain but actions are minimal or generic" ("Processes PDF files") rather than the 1-2 concrete actions of a 3.

2 / 5

Completeness

Both parts are explicitly answered: what ("Post-ship doc sync across project markdown") and when ("Use when: sync docs, update docs, document changes, release notes") with concrete trigger phrases, matching the anchor "Clearly and explicitly answers both what AND when with concrete trigger phrases"; a 4 would require the 'when' to be less explicit than it is here.

5 / 5

Trigger Term Quality

"Use when: sync docs, update docs, document changes, release notes" provides natural phrases a user would say, matching the anchor "Good keyword coverage; a few natural terms missing" — common variations like "update the documentation", "changelog", or "readme" are absent, so it falls short of the comprehensive synonym coverage of a 5.

4 / 5

Distinctiveness Conflict Risk

The "post-ship" framing carves out a clear niche, but the trigger "update docs" is broad enough to overlap generic documentation-editing skills, matching "Mostly distinct; minor overlap risk with closely related skills" rather than the minimal conflict risk of a 5.

4 / 5

Total

15

/

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

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository
nyldn/claude-octopus
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.