skill-doc-sync

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

Quality

80%

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

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is highly actionable with a well-sequenced, validated workflow and concrete code throughout. Its main weaknesses are mild verbosity from rationale blocks and a monolithic single-file structure with no progressive disclosure.

Suggestions

Trim or fold the "WHY:" rationale blocks into one-line notes to improve token efficiency without losing intent.

Move the large bash snippets or the CHANGELOG BAD/GOOD examples into a references file (e.g., references/changelog-examples.md) and link to it, giving the overview a clearer one-level-deep structure.

Note explicitly in the body that the referenced `skills/blocks/codex-host-adapter.md` is an external host-adapter file rather than a bundled reference, so the reader knows it is not part of this skill.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with concrete bash blocks per step, but the repeated "WHY:" rationale blocks (e.g., "The CHANGELOG is marketing copy for developers") and some restated guidance add length that could be tightened without losing clarity.	2 / 3
Actionability	Every step ships executable bash (find/git diff/grep/gh), exact paths, and concrete BAD/GOOD CHANGELOG transformations, making the guidance copy-paste ready.	3 / 3
Workflow Clarity	Nine steps are clearly sequenced with explicit checkpoints: a 30-file cap warning, risky-change detection that asks the user to approve/skip (Step 4), and a staged-change check before committing (Step 9).	3 / 3
Progressive Disclosure	No bundle files exist and the ~240-line skill is a single monolithic document with clear sections but no one-level-deep references to split out detail, so it is organized but not appropriately split across files.	2 / 3
	Total	10 / 12 Passed

Description

82%

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 concise, third-person, and cleanly answers both what and when with natural trigger terms. It is held back from the top level by a single summarized action and somewhat generic triggers that could overlap with broader doc-editing skills.

Suggestions

Replace the single verb "sync" with two or three concrete actions (e.g., "reads the diff, auto-updates stale facts, polishes CHANGELOG entries, and updates the PR body") to lift specificity.

Tighten trigger terms toward the post-ship context (e.g., "update docs after a PR", "sync release notes") to reduce overlap with general documentation skills.

Dimension	Reasoning	Score
Specificity	"Post-ship doc sync across project markdown" names the domain and a single summarized action ("sync"), but does not list multiple concrete actions like reading diffs, auto-updating facts, or polishing CHANGELOGs, so it stops at naming domain and some actions.	2 / 3
Completeness	It explicitly answers both what ("Post-ship doc sync across project markdown") and when (an explicit "Use when:" clause with triggers), matching the what-AND-when anchor.	3 / 3
Trigger Term Quality	"Use when: sync docs, update docs, document changes, release notes" gives natural phrases a user would actually say, with good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	The "post-ship" framing gives it a niche, but generic triggers like "update docs" and "document changes" could overlap with general documentation-editing skills, so it is somewhat specific but could still overlap.	2 / 3
	Total	10 / 12 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

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

Reviewed: 2 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.