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.
84
64%
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 what the skill does (automates changelog generation following a specific format) and when to use it (release workflows, release notes, commit conventions). It uses third person voice, includes natural trigger terms, and occupies a distinct niche that minimizes conflict with other skills.
| 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
29%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive reference dump rather than an actionable guide. While the individual code examples are executable and complete, the sheer volume (6 methods, 2 templates, examples, best practices) makes it extremely token-inefficient and poorly organized. It lacks workflow sequencing, validation checkpoints, and progressive disclosure—presenting everything inline without helping Claude decide which method to use or how to verify the setup works.
Suggestions
Reduce to 1-2 recommended methods in the main file, moving others to separate referenced files (e.g., methods/semantic-release.md, methods/git-cliff.md) with a brief comparison table to guide selection.
Remove explanations of Conventional Commits format, semantic versioning, and best practices—Claude already knows these concepts well.
Add a clear sequential workflow with validation steps, e.g.: '1. Choose method based on ecosystem → 2. Install tools → 3. Configure → 4. Dry-run to verify → 5. Test with a sample commit → 6. Enable CI enforcement'.
Fix the GitHub Actions workflow bug where steps.version.outputs.tag is referenced but never defined, and add dry-run/validation steps before actual releases.
| 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 (.versionrc.js, release.config.js, cliff.toml, pyproject.toml), GitHub Actions workflows, and bash commands are all concrete and complete. | 3 / 3 |
Workflow Clarity | Despite covering complex multi-step processes (release workflows, CI/CD pipelines), there are no clear sequential workflows with validation checkpoints. The content presents configuration dumps without guiding through the setup process step-by-step. No verification steps like 'run dry-run first' are integrated into workflows, and the GitHub Actions workflow has a bug (references steps.version.outputs.tag which is never defined). | 1 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files. Six complete implementation methods, two release note templates, commit examples, and best practices are all inlined. This should be split into separate files per method (e.g., SEMANTIC-RELEASE.md, GIT-CLIFF.md) with the main skill providing an overview and decision guidance. | 1 / 3 |
Total | 6 / 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
70444e5
- 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.