Maintain a clear and informative changelog for software releases. Use when documenting version changes, tracking features, or communicating updates to users. Handles semantic versioning, changelog formats, and release notes.
83
77%
Does it follow best practices?
Impact
94%
1.02xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.agent-skills/changelog-maintenance/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid skill description with explicit 'Use when' guidance and good trigger term coverage. The main weakness is that the specific capabilities could be more concrete - it describes the domain well but doesn't enumerate specific actions like generating entries, parsing existing changelogs, or validating version formats.
Suggestions
Add more concrete action verbs to specificity, e.g., 'Generate changelog entries, validate semantic version numbers, format release notes in Keep a Changelog style'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (changelog/releases) and mentions some actions like 'documenting version changes, tracking features, communicating updates', but lacks concrete specific actions like 'generate changelog entries, format release notes, validate semantic versions'. | 2 / 3 |
Completeness | Clearly answers both what ('Maintain a clear and informative changelog', 'Handles semantic versioning, changelog formats, and release notes') AND when ('Use when documenting version changes, tracking features, or communicating updates to users'). | 3 / 3 |
Trigger Term Quality | Good coverage of natural terms users would say: 'changelog', 'version changes', 'features', 'updates', 'semantic versioning', 'release notes'. These are terms users naturally use when discussing software releases. | 3 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on changelogs and release documentation. The combination of 'changelog', 'semantic versioning', and 'release notes' creates distinct triggers unlikely to conflict with general documentation or code skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides excellent actionable examples with complete, copy-paste ready templates for changelogs, release notes, and migration guides. However, it's overly verbose with lengthy inline examples that could be externalized, and lacks validation steps in the workflow. The empty example placeholders at the end suggest incomplete content.
Suggestions
Move the lengthy CHANGELOG.md and migration guide examples to separate reference files (e.g., examples/changelog-template.md) and link to them from the main skill
Add a validation step such as 'Review changelog entries against git history to ensure completeness' or 'Verify version number follows semver rules based on changes'
Complete or remove the empty 'Example 1' and 'Example 2' placeholder sections at the bottom
Trim the semantic versioning explanation - Claude already understands semver; focus only on project-specific conventions if any
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes substantial example content that demonstrates formats well, but is verbose with lengthy changelog examples that could be trimmed. The semantic versioning explanation is somewhat redundant given Claude's existing knowledge. | 2 / 3 |
Actionability | Provides fully executable, copy-paste ready examples including complete CHANGELOG.md format, release notes template, and migration guide with before/after code snippets. All examples are concrete and immediately usable. | 3 / 3 |
Workflow Clarity | Steps are numbered and sequenced (Step 1-4), but lacks validation checkpoints. No guidance on verifying changelog correctness, checking version number accuracy, or reviewing before publishing. For a documentation task, some review step would strengthen the workflow. | 2 / 3 |
Progressive Disclosure | Content is reasonably structured with clear sections, but the skill is monolithic with all content inline. The lengthy examples (especially the full CHANGELOG.md) could be split into separate reference files. The 'Examples' section at the bottom is empty placeholder content. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
c033769
Table of Contents
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.