CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

write-changelog

Writes a changelog from git commits and sprint data. Use for an internal or player-facing one.

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

Quality

Content

67%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 body is a well-structured, highly actionable procedure with genuine validation gates (provenance hard-stop, no-history branch, confirm-before-write) and complete output templates. Its weaknesses are moderate redundancy in the provenance rationale, a missing command for computing the metrics it requires, and a duplicated 'Phase 7' heading that muddies the phase sequence.

Suggestions

Fix the duplicate phase numbering — rename the second 'Phase 7: Next Steps' to 'Phase 8: Next Steps', and move the 'Guidelines' subsection out from under it to sit alongside the other top-level sections.

Tighten the provenance check to state the Game/Framework/Unclear taxonomy and the hard-stop consequence once; the harm rationale is currently repeated in the blockquote, the 'Why this is a hard stop' paragraph, and the 'preamble's existence' note.

Add the commands backing the Metrics template, e.g., `git diff --shortstat [last-tag]..HEAD` for files changed and lines added/removed, so every template field is computable.

DimensionReasoningScore

Conciseness

The phases, commands, and templates are mostly efficient and project-specific (the framework-vs-game commit taxonomy is knowledge Claude would not have), but the provenance section restates its rationale roughly four times — the harm of framework commits appears in the filter blockquote, again in 'Why this is a hard stop, not a warning', and again in 'Do not treat the preamble's existence as evidence'. This matches 'Mostly efficient but includes some unnecessary explanation or could be tightened'; it is not severely padded enough for a 2, but the repetition keeps it below 4.

3 / 5

Actionability

Concrete executable commands are given throughout — `git rev-parse --is-inside-work-tree`, `git log --oneline [last-tag]..HEAD`, the `-n 100` bound, the Grep pattern `^#` with offset/limit reading — and both changelog templates plus the exact user prompts are copy-paste ready. The gap that keeps it below 5: the Metrics section requires 'Files changed / Lines added / Lines removed' but no command (e.g., `git diff --shortstat`) is provided to compute them.

4 / 5

Workflow Clarity

The seven-phase sequence is clear with real validation checkpoints: the provenance hard-stop with an exact blocked message, the no-history branch, and the ask-before-write with explicit append/overwrite/decline options that gate the destructive overwrite. It falls short of 5 because two sections are both numbered 'Phase 7' (Offer File Write and Next Steps), and the pre-body 'Recent History' blocks plus the interleaved provenance instructions make the entry sequence slightly tangled.

4 / 5

Progressive Disclosure

There are no bundle files (references/, scripts/, assets/ are absent) and none of the body's inline content is dead-weight reference material, so the ~260 lines of working guidance — commands, templates, decision rules — are appropriately placed inline with clear section headings, and the automation-modes pointer is a well-signaled single-level reference. Minor organization gaps (the duplicate Phase 7 heading, and the guidelines section being nested under 'Next Steps' rather than standing alone) keep it at 4 rather than 5.

4 / 5

Total

15

/

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.

The description is concise, in third person, and answers both what the skill does and roughly when to use it, with natural trigger terms like 'changelog' and 'git commits'. Its main limitations are thin action coverage (one verb where the skill performs several) and a 'when' clause that names output variants rather than invocation situations, plus no synonyms such as 'release notes'.

Suggestions

List the concrete actions the skill performs, e.g., 'Categorizes commits into features, improvements, fixes, and balance changes, and generates both an internal changelog and a player-facing what's-new entry.'

Make the trigger explicit and situational: 'Use when the user asks for a changelog, release notes, or a what's-new list for a version tag or sprint.'

Add common synonyms such as 'release notes' or 'what's new' to broaden natural trigger coverage.

DimensionReasoningScore

Specificity

"Writes a changelog from git commits and sprint data" names the domain and a concrete action with its two input sources, but stops at one action — it does not mention the categorization (features, fixes, balance changes), the dual internal/player-facing output formats, or the file-write step the body actually performs. This matches 'Names domain and 1-2 concrete actions, but not comprehensive' rather than 4, which requires several specific actions listed.

3 / 5

Completeness

The 'what' is clear ("Writes a changelog from git commits and sprint data") and a trigger clause exists ("Use for an internal or player-facing one"), so both parts are present. The 'when' names the two output variants but not the situations that invoke it (e.g., 'when the user asks for a changelog or release notes for a version or sprint'), fitting 'when' could be more explicit or specific' rather than the concrete trigger phrases of a 5.

4 / 5

Trigger Term Quality

"changelog", "git commits", and "sprint" are natural terms a user would plausibly say, giving good keyword coverage. It misses common synonyms like "release notes" or "what's new", which keeps it below the comprehensive-synonym coverage of a 5.

4 / 5

Distinctiveness Conflict Risk

Changelog generation from git commits and sprint data is a distinct niche with low generic-conflict risk. However, the body itself references a sibling skill (/patch-notes) that reads the same history for public release copy, so there is minor overlap risk with a closely related skill — anchor 4, not the minimal-conflict 5.

4 / 5

Total

15

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

Donchitos/Claude-Code-Game-Studios

Path

.claude/skills/write-changelog/SKILL.md

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.