skill-doc-sync

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

Quality

67%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/skill-doc-sync/SKILL.md

Quality

Content

65%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 thorough, mostly-executable 9-step doc-sync workflow with good structure, weakened by the absence of a validation feedback loop on its batch auto-updates and by a monolithic layout with no progressive disclosure.

Suggestions

Add an explicit validation step after Step 3 (auto-update) that re-verifies each changed factual reference against the diff and loops back on mismatches before proceeding to commit.

Actually update the PR body in Step 9 rather than only fetching the PR number (e.g. `gh pr edit --body`).

Split the CHANGELOG voice-polish rules and example transformations into a referenced file (e.g. references/CHANGELOG-VOICE.md) to improve progressive disclosure and trim the main body.

Dimension	Reasoning	Score
Conciseness	The body is mostly executable bash and action-oriented prose that respects Claude's competence, with only minor trimmable overhead (the re-stating intro and the 'WHY' rationale blocks).	4 / 5
Actionability	Concrete, copy-paste-ready bash covers discovery, diffing, version checks, TODO scanning, and committing, plus BAD/GOOD CHANGELOG examples; minor gaps remain (the PR body is fetched but never actually edited, and Steps 4 and 7 are prose-only).	4 / 5
Workflow Clarity	Nine steps are clearly sequenced with some checkpoints (cap warning, user-approval gate, staged-check before commit), but this batch/destructive skill lacks an explicit validate-then-fix-then-retry feedback loop for the auto-updated content, so the rubric cap of 3 applies.	3 / 5
Progressive Disclosure	The skill is well-sectioned (Caps, Steps 1-9, Integration) but monolithic: all content is inlined with no one-level-deep references, and material such as the CHANGELOG voice-polish guide and full bash scripts could reasonably live in separate files.	3 / 5
	Total	14 / 20 Passed

Description

70%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 cleanly answers both what and when with natural trigger phrases and a distinct post-ship niche, but the 'what' under-specifies the concrete actions the skill performs.

Suggestions

Expand the 'what' clause to name the core actions, e.g. 'cross-references the git diff, auto-updates stale paths/counts/versions, and polishes CHANGELOG entries'.

Add a couple of synonyms/file cues to the 'Use when' list (e.g. 'documentation', 'CHANGELOG', 'README') to broaden trigger coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('Post-ship doc sync across project markdown') and one concrete action (sync), but does not enumerate the specific operations the body performs (diff cross-reference, auto-update, consistency checks), so coverage is not comprehensive.	3 / 5
Completeness	Both a 'what' ('Post-ship doc sync across project markdown') and an explicit 'when' with concrete triggers are present; the 'what' is slightly generic about the actual operations, keeping it just below a 5.	4 / 5
Trigger Term Quality	The 'Use when' clause lists natural phrases users would say ('sync docs', 'update docs', 'document changes', 'release notes'), but misses common synonyms like 'documentation' and file extensions, so coverage is good rather than comprehensive.	4 / 5
Distinctiveness Conflict Risk	The 'post-ship doc sync' framing is a fairly distinct niche with dedicated triggers, with only minor overlap risk against general doc-editing skills.	4 / 5
	Total	15 / 20 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: nyldn/claude-octopus
Path: .claude/skills/skill-doc-sync/SKILL.md
Commit: f9b8c92

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.