doc-maintenance

Audit README, SPEC, and PRODUCT docs against recent git history for drift and make minimal PR-ready edits. Use when asked to review docs for accuracy, after major feature merges, or on a schedule.

Quality

84%

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

Quality

Content

86%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 well-built instruction-only skill: every workflow step is backed by executable commands, the scope is sharply bounded (target docs table plus an explicit out-of-scope list), and detail is properly pushed into two real, well-signaled reference files. The main improvement opportunities are deduplicating the classification rules and adding an explicit pre-PR verification step.

Suggestions

Consolidate Step 2's inline keyword lists with the 'Change Classification Rules' table into a single source of truth to remove the duplicated classification guidance.

Add an explicit validation checkpoint before Step 6, e.g. 'Review `git diff` of doc changes and confirm each edit fixes a specific drift item before committing'.

Dimension	Reasoning	Score
Conciseness	The body is efficient — tables, exact commands, and rule lists with no explanation of concepts Claude already knows. Not a 5 because of genuine redundancy: change classification rules appear twice (Step 2 keyword lists and the 'Change Classification Rules' table) and roadmap-item handling is repeated between Step 5 and the Patch Style Guide.	4 / 5
Actionability	Fully executable, copy-paste-ready guidance: exact cursor-reading bash with a first-run fallback, git log range syntax, branch naming, a complete commit message template, and a full `gh pr create` heredoc command with PR body. This matches the anchor for complete executable commands covering the common cases.	5 / 5
Workflow Clarity	Seven clearly numbered steps with an explicit early exit ('If there are no notable changes, skip to Step 7'), a borderline-case checkpoint ('check the actual diff'), and a checklist reference for the audit. Not a 5 because there is no explicit validation of the edits themselves before the PR (e.g., reviewing `git diff` of the doc changes), leaving a minor checkpoint gap for a multi-document batch edit pass.	4 / 5
Progressive Disclosure	Verified against the actual bundle: both referenced files exist (references/audit-checklist.md, references/section-map.md), are explicitly signaled with their purpose in Step 4, and are one level deep. The workflow stays inline while per-section checklists and feature-to-section mapping are correctly split out — a clean overview-plus-references structure matching the top anchor.	5 / 5
	Total	18 / 20 Passed

Description

82%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 strong description that explicitly covers what it does and when to use it with concrete, natural trigger phrases and a well-defined niche. Its only weakness is action coverage: it states two actions (audit for drift, make minimal edits) rather than the fuller set of concrete operations the skill actually performs.

Suggestions

Enumerate one or two more concrete audit actions in the description, e.g., 'verify quickstart commands, update feature tables, and move shipped items off the roadmap' to lift specificity.

Add natural synonym trigger phrases such as 'documentation', 'up to date', or 'stale docs' alongside 'docs for accuracy'.

Dimension	Reasoning	Score
Specificity	The description names the domain precisely ('Audit README, SPEC, and PRODUCT docs against recent git history for drift') and lists two concrete actions ('audit ... for drift', 'make minimal PR-ready edits'), matching the anchor for 1-2 concrete actions without comprehensive coverage. It is not a 4 because it does not list several distinct actions (e.g., verifying quickstart commands, updating feature tables, moving shipped roadmap items).	3 / 5
Completeness	Clearly and explicitly answers both what ('Audit README, SPEC, and PRODUCT docs ... for drift and make minimal PR-ready edits') and when ('Use when asked to review docs for accuracy, after major feature merges, or on a schedule') with three concrete trigger phrases, in third person. This matches the anchor 5 example structure exactly.	5 / 5
Trigger Term Quality	Good natural keyword coverage: 'review docs for accuracy', 'after major feature merges', 'on a schedule', plus named files (README, SPEC, PRODUCT). Not a 5 because common variations users would say are missing — e.g., 'documentation', 'up to date', 'stale', 'outdated'.	4 / 5
Distinctiveness Conflict Risk	A clear niche — drift auditing of three named documents against git history — with distinct triggers (post-merge, scheduled, accuracy review). Minimal overlap risk with general doc-editing or commit-message skills; not generic enough to fit anchor 4's 'minor overlap' description.	5 / 5
	Total	17 / 20 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: paperclipai/paperclip
Path: .agents/skills/doc-maintenance/SKILL.md
Commit: 1c07b59

Reviewed: 1 day 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.