CtrlK
BlogDocsLog inGet started
Tessl Logo

update-changelog

Read this skill before updating changelogs

51

Quality

64%

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 ./skills/update-changelog/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

The content is a well-structured, actionable guide: concrete git commands, explicit content and style rules, good/bad entry examples, and thoughtful edge-case notes. Its only weaknesses are minor — a duplicated baseline command, no guidance on sourcing PR numbers, and no explicit post-edit verification step.

Suggestions

Remove the duplicated `git describe --tags --abbrev=0` between Step 1 and the Step 2 code block, or merge the two steps.

Add a one-liner on how to obtain PR numbers for entries (e.g., from merge-commit subjects or the repo's PR URL pattern), since '#NUMBER' is required by the style rules.

Add a lightweight verification step, e.g., 'After updating, re-read the Unreleased section to confirm entries follow the existing bullet style and ordering.'

DimensionReasoningScore

Conciseness

The body is efficient — every section (baseline detection, git commands, content/style rules, examples) carries information Claude does not already know, with no concept explanations or padding. One minor redundancy: Step 1 gives `git describe --tags --abbrev=0` and Step 2's code block repeats the same command with a '# Get the baseline version (if not provided)' comment, which could be trimmed.

4 / 5

Actionability

Concrete, executable commands are provided (`git describe --tags --abbrev=0`, `git log <baseline-version>..HEAD`), plus specific style rules and good/bad entry examples that make the output format unambiguous. Minor gap: PR numbers are required ('#NUMBER') but no command shows how to obtain them (e.g., from merge-commit messages), keeping it just below the fully copy-paste-ready anchor 5.

4 / 5

Workflow Clarity

The three-step sequence (determine baseline → collect commits → update changelog) is clearly ordered with concrete commands, and Notes cover edge cases (existing Unreleased section, alternate default branch, fallback changelog filename). There is no explicit verification step (e.g., re-reading the updated section or diffing), but since the operation is additive (append-only, preserve existing style) rather than destructive, the batch-validation cap does not apply — leaving a minor validation gap consistent with anchor 4.

4 / 5

Progressive Disclosure

With no bundle files present, the skill is a well-organized single file: clear section headers, an inline example format that is short enough to belong in the body, and no buried or nested references. At ~75 body lines it sits above the under-50-line threshold where well-organized sections alone earn a 5, and the 15-line example block could arguably be tightened, so anchor 4 ('good structure; most content appropriately placed') is the best fit.

4 / 5

Total

16

/

20

Passed

Description

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

The description is extremely terse — a single meta-instruction ("Read this skill before updating changelogs") that tells Claude when to read the skill but never what the skill does. It names the domain but omits capabilities, trigger variations, and concrete scope, leaving it weak on completeness and specificity despite its brevity.

Suggestions

Add a 'what' clause stating the concrete capability, e.g., 'Updates the repository changelog (CHANGELOG.md or CHANGELOG) with notable user-facing commits since the last git tag, appended to the Unreleased section.'

Add explicit trigger guidance with natural variations: 'Use when asked to update the changelog, add release notes, or document changes since the last release or version tag.'

Include concrete trigger keywords such as 'CHANGELOG.md', 'release notes', and 'version history' so it matches how users actually phrase the request.

DimensionReasoningScore

Specificity

"Read this skill before updating changelogs" names the domain (changelogs) but the only action is the generic "updating"; there is no concrete detail about what the update involves (e.g., summarizing commits since the last release, appending to an Unreleased section). This matches the anchor 'Names the domain but actions are minimal or generic' — not 3, which requires 1-2 concrete named actions.

2 / 5

Completeness

The description gives only a weak 'when' ('before updating changelogs') and entirely omits the 'what' — it never states what the skill actually does. This matches anchor 2 ('only "when" is present without "what"'); it cannot reach 3, which requires a clear 'what', and the missing explicit trigger clause also caps completeness at 3 per guidelines.

2 / 5

Trigger Term Quality

"updating changelogs" is a natural phrase a user would say, but common variations and synonyms are missing: "CHANGELOG.md", "release notes", "version history", "What's Changed". This is 'some relevant keywords but missing common variations or synonyms' rather than 4's 'good keyword coverage'.

3 / 5

Distinctiveness Conflict Risk

Changelog updating is a somewhat specific niche, but the bare phrase could plausibly overlap with adjacent skills like commit-message generation or release-notes tooling, and the description offers no scope cues to disambiguate. 'Somewhat specific but could still overlap with similar skills' fits better than 4's 'mostly distinct'.

3 / 5

Total

10

/

20

Passed

Validation

100%

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
mitsuhiko/agent-stuff
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.