changelog-automation
Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.
86
71%
Does it follow best practices?
Impact
97%
1.16xAverage score across 6 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/documentation-generation/skills/changelog-automation/SKILL.mdQuality
Discovery
100%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 strong skill description that clearly communicates its purpose, uses natural trigger terms, and includes an explicit 'Use when' clause. It follows third-person voice, names a specific standard (Keep a Changelog), and covers multiple concrete actions without being verbose. The description is well-differentiated from related skills like general git workflows or documentation generation.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'changelog generation from commits, PRs, and releases', 'setting up release workflows', 'generating release notes', 'standardizing commit conventions'. Also references a specific format standard (Keep a Changelog). | 3 / 3 |
Completeness | Clearly answers both 'what' (automate changelog generation from commits, PRs, and releases following Keep a Changelog format) and 'when' (explicit 'Use when' clause covering release workflows, release notes, and commit conventions). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'changelog', 'commits', 'PRs', 'releases', 'release notes', 'release workflows', 'commit conventions', 'Keep a Changelog'. These cover common variations of how users would describe this need. | 3 / 3 |
Distinctiveness Conflict Risk | Occupies a clear niche around changelog generation and release note automation. The specific mention of Keep a Changelog format, commits, PRs, and release workflows makes it highly distinguishable from general git or documentation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides comprehensive, executable configurations for multiple changelog automation tools, which is its primary strength. However, it is far too verbose for a SKILL.md—presenting 6 full implementation methods inline with templates and examples that should be split into separate reference files. It also explains concepts Claude already knows (Conventional Commits format, semantic versioning) and lacks a clear decision framework for choosing between methods.
Suggestions
Reduce to a concise overview with one recommended method inline, and move the other 5 methods to separate referenced files (e.g., methods/semantic-release.md, methods/git-cliff.md).
Remove explanations of Conventional Commits format, semantic versioning, and commit message examples—Claude already knows these. Keep only project-specific conventions or non-obvious mappings.
Add a decision matrix or brief selection guide at the top (e.g., 'Use semantic-release for full automation, git-cliff for speed, commitizen for Python projects') to improve workflow clarity.
Move release note templates and commit message examples to a separate TEMPLATES.md file referenced from the main skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Includes 6 different implementation methods (Node.js, standard-version, semantic-release, GitHub Actions, git-cliff, Python commitizen), release note templates, commit message examples, and best practices. Much of this is reference material Claude already knows or could derive. The Conventional Commits table, semantic versioning explanation, and best practices sections explain concepts Claude is well-versed in. | 1 / 3 |
Actionability | Provides fully executable, copy-paste ready configurations and commands for every method. Config files are complete (commitlint.config.js, .versionrc.js, release.config.js, cliff.toml, pyproject.toml) with real install commands and usage examples. | 3 / 3 |
Workflow Clarity | Individual methods have clear setup steps, but there's no guidance on which method to choose or a clear decision workflow. The 6 methods are presented without sequencing or selection criteria. No validation checkpoints for the release process itself (e.g., verify changelog before publishing, dry-run before actual release is mentioned only briefly). | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files. All 6 implementation methods, templates, examples, and best practices are inlined. This would benefit enormously from splitting methods into separate files and keeping SKILL.md as an overview with links. | 1 / 3 |
Total | 7 / 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 |
|---|---|---|
skill_md_line_count | SKILL.md is long (573 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
91fe43e
- 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.