CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

62

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/release-changelog/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

77%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 highly actionable, well-sequenced operational skill: copy-paste-ready commands, a complete template, an idempotency check, and a final review checklist with human sign-off. Its weaknesses are repetition of the versioning and file-location rules across sections and the inlined Case API contract in Step 5b that should live in a reference file, especially since no bundle files are provided alongside it.

Suggestions

Move the Step 5b Case API request/response bodies into a reference file (or defer fully to the already-cited skills/paperclip/references/cases.md), keeping only the endpoint, key facts, and the 409 retry rule in SKILL.md.

Deduplicate the version-derivation rules: state 'do not derive versions from semver bump types / major-minor-patch intent' once in the Versioning Model section and remove the restatement in Step 1.

Consolidate the beta file-location rules (Channel Process, Step 0, and Step 5 all restate releases/beta/v{beta-version}.md and the never-canary rule) into a single canonical statement with the other sections cross-referencing it.

DimensionReasoningScore

Conciseness

The body is dense and almost entirely project-specific, but rules are repeated across sections: 'do not derive versions from semver bump types' (line 32) restated as 'Do not derive major/minor/patch bumps from API intent' (line 113), and the beta file-location / never-canary rules appear in the Channel Process section, Step 0, and Step 5. Plus a rationale sentence ('This fields schema deliberately exercises every generic field value type...') that explains rather than instructs. Fits anchor 3 — mostly efficient but could be tightened — rather than 4, where over-explanation would be only minor.

3 / 5

Actionability

Fully executable throughout: exact commands ('git rev-parse "beta/v{beta-version}^{commit}"', 'gh pr list --state merged --search "merged:>={last-tag-date}"', './scripts/release.sh stable --date YYYY-MM-DD --print-version'), a copy-paste changelog template, complete HTTP request bodies for the case upsert and document PUT, and concrete error recovery ('On 409 stale_base_revision, refetch, merge intentionally, and retry once').

5 / 5

Workflow Clarity

Steps 0–6 are explicitly sequenced with an idempotency check up front ('A release-notes/v{beta-version} branch holding only the generated skeleton is the normal starting state, not a conflict — rewrite it in place'), a numbered review checklist ending in human sign-off ('confirm the H1 heading is # Paperclip {version}... present the draft for human sign-off'), and the skill is non-destructive by design ('This skill never publishes anything'). Feedback loops for the risky API step (409 stale_base_revision retry) are present.

5 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are all absent), and the body inlines roughly 40 lines of the Case API contract (the Step 5b JSON payload and its field-by-field rationale) that belongs in a reference file — one it already points to elsewhere ('skills/paperclip/references/cases.md'). This matches anchor 3 (content that should be separate is inline) rather than 2, since section structure is clear and the external references it does cite are signaled with explicit paths.

3 / 5

Total

16

/

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.

A specific, distinctive description with concrete actions and an exact output path, but it omits any 'Use when...' trigger guidance, which caps its completeness and slightly weakens natural triggering. Keyword coverage is good yet lacks common synonyms such as 'release notes'.

Suggestions

Append a trigger clause, e.g. 'Use when preparing or regenerating the stable Paperclip release changelog, or when the user mentions the Paperclip release, release notes, or promoting a beta to stable.'

Add the common synonym 'release notes' (and 'what's new' if that phrasing is used in the repo) so the description matches how users naturally refer to the artifact.

Mention the beta-to-stable promotion context ('when a soaked beta is being promoted to the stable channel') to strengthen the when-side of the description.

DimensionReasoningScore

Specificity

The description names several concrete actions — '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' — with an exact output path and three specific input sources. It falls short of anchor 5 because it describes one deliverable and its inputs rather than a comprehensive list of multiple distinct capabilities.

4 / 5

Completeness

The 'what' is fully explicit (generate the stable Paperclip changelog from commits, changesets, and merged PR context since the last stable tag), but there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. Not 2 because the 'what' is clear and concrete, not vague.

3 / 5

Trigger Term Quality

It includes natural, user-sayable terms like 'release changelog', 'stable', 'release', 'commits', 'changesets', and 'merged PR'. Not anchor 5 because common synonyms such as 'release notes' or 'what's new' are missing; not anchor 3 since keyword coverage goes well beyond a single generic term.

4 / 5

Distinctiveness Conflict Risk

'Stable Paperclip release changelog' and 'since the last stable tag' define a clear niche with distinct triggers — one product's stable release notes — with minimal overlap risk against generic changelog or commit-message skills.

5 / 5

Total

16

/

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

relative_links

Relative link issues: 2 missing

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.