release-changelog

Generate the stable Paperclip release changelog at releases/vYYYY.MDD.P.md by reading commits, changesets, and merged PR context since the last stable tag.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/release-changelog/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 commands/templates. It loses points mainly on repetition of versioning rules and the lack of real progressive disclosure into bundled reference files.

Suggestions

State the calver/'do not derive from canary or semver' rule once in the Versioning Model section and reference it from later steps instead of repeating it.

Move the Step 5b API contract details into a bundled references file (e.g. references/cases.md) referenced from the body, so the contract lives one level deep rather than inline.

Ensure any referenced reference file (cases.md) is actually included in the bundle so the navigation is real.

Dimension	Reasoning	Score
Conciseness	The body is dense with actionable commands and avoids concept explanations, but calver/'do not derive from canary or semver' rules are restated across the Versioning Model, Step 1, and Step 6 review checklist, so it could be tightened.	2 / 3
Actionability	Concrete git/gh commands, exact file paths, a full markdown template, and exact HTTP requests with complete JSON bodies make the guidance copy-paste ready.	3 / 3
Workflow Clarity	Numbered Steps 0–6 are clearly sequenced with explicit checkpoints — Step 0 idempotency check, Step 3 breaking-change detection, Step 5b refetch/retry on 409, and a Step 6 review checklist — satisfying the validation requirement for a file-overwriting operation.	3 / 3
Progressive Disclosure	The skill is well-sectioned but monolithic in a single ~250-line file with no actual bundle files; it references 'skills/paperclip/references/cases.md' (not present in the bundle) and keeps the large API contract inline.	2 / 3
	Total	10 / 12 Passed

Description

67%

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 specific and well-scoped to a clear niche, with concrete inputs and output named. Its weakness is the absence of explicit 'when to use' trigger guidance and reliance on somewhat internal trigger terms.

Suggestions

Add a 'Use when...' clause naming natural triggers, e.g. 'Use when preparing or regenerating the stable Paperclip release changelog or release notes.'

Include common user-facing phrasings like 'release notes' alongside 'changelog' to broaden trigger-term coverage.

Keep the third-person voice while surfacing the key trigger ('release changelog'/'release notes') earlier in the sentence.

Dimension	Reasoning	Score
Specificity	The description enumerates concrete actions — 'reading commits, changesets, and merged PR context since the last stable tag' and writing to a named path 'releases/vYYYY.MDD.P.md' — matching the anchor for multiple specific concrete actions.	3 / 3
Completeness	The 'what' is clearly stated, but there is no 'Use when...' clause or equivalent explicit trigger guidance, so 'when' is only implied — capping completeness at 2 per the judging guidelines.	2 / 3
Trigger Term Quality	'release changelog' is a natural user term, but 'changesets' and 'merged PR context' skew internal/technical and common user variations such as 'release notes' or 'what changed' are absent, so coverage is partial.	2 / 3
Distinctiveness Conflict Risk	The niche is narrow and specific — generating the stable Paperclip release changelog — making it unlikely to trigger for unrelated skills.	3 / 3
	Total	10 / 12 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
relative_links	Relative link issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: paperclipai/paperclip
Path: .agents/skills/release-changelog/SKILL.md
Commit: 14f20be

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.