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.

55

Quality

61%

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

Quality

Content

61%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 genuinely actionable, well-sequenced skill whose bash snippets are copy-paste ready, but it carries rationale padding Claude doesn't need and, critically for a batch-editing skill, commits auto-generated changes without any verification checkpoint on the edited output. The dangling host-adapter reference is the main structural blemish in an otherwise clean single-file layout.

Suggestions

Add a verification step between auto-updates and commit: show `git diff --stat` / review the doc diff (or re-run the Step 6 consistency checks on the edited files) and fix-and-retry before committing, to lift the batch-operation workflow cap.

Remove the four 'WHY:' rationale blocks and the Codex host blockquote, or compress them to one clause each — Claude can infer why stale docs matter.

Make Step 9's PR-body update actually perform the update (e.g., `gh pr edit --body`) or explicitly state the edit is applied via the gh tool, since the current snippet only echoes the PR number.

DimensionReasoningScore

Conciseness

The body is mostly efficient — concrete bash snippets, tight rule lists, a caps section — but includes unnecessary explanation: four 'WHY:' rationale blocks (e.g., "Stale factual references erode trust in documentation", "The CHANGELOG is marketing copy for developers") that state things Claude already knows, plus a 4-line host-adapter blockquote. This matches 'mostly efficient but includes some unnecessary explanation or could be tightened'. Not score 4 because the over-explanation appears in ~6 places rather than minor isolated instances; not score 2 because there is no concept-explainer padding and the large majority of lines are executable guidance.

3 / 5

Actionability

Nearly every step ships copy-paste-ready bash (find with exclusions, branch-aware git diff, version-consistency greps, TODO extraction from the diff, staged-commit flow), matching 'mostly executable guidance with minor gaps'. Not score 5 because Step 9's PR-body update only fetches the PR number and echoes — it never actually updates the body, and risky-change presentation (Step 4) shows an example dialog rather than a runnable mechanism; not score 3 because no step relies on pseudocode or vague direction.

4 / 5

Workflow Clarity

The nine steps are clearly numbered and sequenced, and Step 4's user-confirmation gate is a real checkpoint, but this is a batch operation (auto-editing up to 30 files) with no verification of the mechanical auto-updates before committing — Step 9 commits directly without reviewing the produced diff or re-checking consistency. Per the rubric's judging guideline, a batch workflow lacking validation/verification is capped at 3. Not score 4 because the missing validate-the-batch-edits feedback loop is more than a minor gap under the explicit cap; not score 2 because the sequence itself is coherent with a genuine risky-change checkpoint.

3 / 5

Progressive Disclosure

Structure is good: a caps section up front, nine clearly headed steps, and no deep reference nesting, matching 'good structure; most content appropriately placed; minor organization gaps'. Not score 5 because everything lives inline in one ~235-line file — CHANGELOG style rules and integration notes could sit in a reference file — and the sole reference, `skills/blocks/codex-host-adapter.md`, is dangling since the bundle contains no other files; not score 3 because sections are clearly signaled and navigable, not poorly organized.

4 / 5

Total

14

/

20

Passed

Description

61%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 has an explicit and well-populated 'Use when' clause with natural trigger phrases, but the capability half is a single terse domain summary with no concrete actions listed. Expanding the 'what' with the skill's actual operations would raise specificity and distinctiveness together.

Suggestions

Replace the generic 'doc sync' summary with 2-3 concrete actions, e.g., 'Updates paths, counts, and version references across project markdown, polishes CHANGELOG entries, and verifies cross-doc consistency after a release.'

Add distinguishing trigger keywords such as 'CHANGELOG', 'release notes update', or 'documentation drift' to reduce overlap with general doc-writing skills.

Include the synonym 'documentation' alongside 'docs' in the Use-when list so users who say the full word still match.

DimensionReasoningScore

Specificity

The phrase "Post-ship doc sync across project markdown" names the domain (documentation synchronization) but offers only one generic action ("sync"); it never lists concrete actions such as updating paths/versions, polishing CHANGELOG entries, or checking cross-doc consistency, matching the 'Processes PDF files' anchor of domain-named but minimal actions. Not score 3 because that anchor requires 1-2 concrete actions, and none are enumerated; not score 1 because the domain is named rather than pure abstraction.

2 / 5

Completeness

Both halves are present: a 'what' ("Post-ship doc sync across project markdown") and an explicit 'when' clause with concrete trigger phrases. Not score 5 because the 'what' is a single terse clause that summarizes rather than describes what the skill concretely does; not score 3 because the 'when' is explicit, not weakly implied.

4 / 5

Trigger Term Quality

"Use when: sync docs, update docs, document changes, release notes" supplies four natural phrases a user would actually say, giving good keyword coverage. Not score 5 because common variations like "documentation" (vs "docs"), "changelog", or "README" are missing; not score 3 because several distinct natural trigger phrases are present, not just a couple of generic keywords.

4 / 5

Distinctiveness Conflict Risk

The description is anchored to a niche ("Post-ship", "release notes") but triggers like "sync docs" and "update docs" are broad enough to overlap with general documentation-writing or formatting skills. Not score 4 because no disambiguating capability terms (CHANGELOG, version consistency, PR body) appear; not score 2 because the post-ship/release framing does narrow it beyond generic document handling.

3 / 5

Total

13

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

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.