CtrlK
BlogDocsLog inGet started
Tessl Logo

doc-maintenance

Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.

60

Quality

70%

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 ./packages/skills-catalog/catalog/bundled/docs/doc-maintenance/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

82%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 tight, high-signal instructional skill: an unambiguous 8-step workflow with real validation checkpoints, concrete positive and negative examples, and zero token waste. The only gaps are a missing command for establishing the commit range and the absence of an explicit error-recovery loop for mid-pass drift discoveries.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence: no explanation of what documentation is, no padding, and every line carries non-obvious judgment ("Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior."). It matches anchor 5 — every token earns its place — and is clearly above anchor 4, which reserves room for trimmable over-explanation that is absent here.

5 / 5

Actionability

Guidance is concrete and executable for an instruction-only skill: the item-to-reference mapping in step 5 ('New CLI flag → CLI reference entry. New env var → configuration reference entry'), the explicit good-vs-bad example ('Faster cold start (...) beats Refactor bootstrap loader'), and the drift checklist. It falls at anchor 4 rather than 5 only because step 1 ('Get the commit range') never shows the actual command (e.g. `git log v1.2.0..HEAD`), leaving a minor executable gap.

4 / 5

Workflow Clarity

The 8-step pass is clearly sequenced with explicit validation checkpoints (step 6: 'Re-run any example that touches new behavior'; step 8: 'Search the docs for the old behavior wording and remove or update stragglers') plus a drift-detection checklist. It does not reach anchor 5 because there is no error-recovery feedback loop — what to do when a re-run example fails or drift is discovered mid-pass is only implied by 'fix it in the same pass'.

4 / 5

Progressive Disclosure

Sections are well-organized and clearly navigable (When to use / When not to use / The pass / Style baseline / Drift detection / Release-note rules / Anti-patterns) with no nested references and no bundle files to misplace. It scores 4 rather than 5 because the body is ~62 lines — above the under-50-lines exception for a single-file skill — and the release-note rules and style baseline could plausibly live in a reference file.

4 / 5

Total

17

/

20

Passed

Description

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

A specific, third-person description with a clear "what" and a distinct niche, but it lacks any explicit "Use when" trigger clause and misses the natural phrases users would actually say ("release notes", "changelog", "out-of-date docs"). The awkward coinage "release-relevant notes" further weakens trigger-term quality.

Suggestions

Add an explicit 'when' clause, e.g. 'Use when a release is being cut, a PR changed user-visible behavior, or the user reports docs that no longer match the code.'

Replace 'release-relevant notes' with the natural term 'release notes' and add common synonyms such as 'changelog' and 'out-of-date' or 'stale docs' so the description triggers on real user phrasing.

Consider naming concrete doc artifacts users would mention — README, CLI reference, changelog — to sharpen both specificity and distinctiveness.

DimensionReasoningScore

Specificity

The description names several concrete actions — "detect drift, update affected pages, and add release-relevant notes" — with an explicit scope constraint ("without rewriting unchanged sections"). It sits at anchor 4: several specific actions with minor coverage gaps (no mention of changelogs, migration guides, or example updates); it is clearly above anchor 3's '1-2 concrete actions' but below anchor 5's comprehensive coverage.

4 / 5

Completeness

The 'what' is clear (detect drift, update pages, add notes), but there is no 'Use when...' clause or equivalent explicit trigger guidance — when to use it is only weakly implied by "recent code and feature changes". Per the rubric guideline, a missing 'Use when' clause caps completeness at 3, which also matches the anchor exactly.

3 / 5

Trigger Term Quality

Relevant keywords are present ("docs", "drift", "release-relevant notes", "code and feature changes") but common natural variations are missing: users would say "release notes" or "changelog", not "release-relevant notes", and phrases like "stale docs" or "docs out of date" are absent. This matches anchor 3 ('some relevant keywords but missing common variations or synonyms') rather than anchor 4, which requires broader natural-term coverage.

3 / 5

Distinctiveness Conflict Risk

The doc-drift-after-code-change niche ("Keep project docs aligned with recent code and feature changes — detect drift") is mostly distinct from general writing/editing skills, with only minor overlap risk against generic documentation tools. It fits anchor 4; it falls short of anchor 5 because 'docs' as a trigger word alone could still pull in unrelated doc-formatting requests.

4 / 5

Total

14

/

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
paperclipai/paperclip
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.