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 what the skill does and when to use it. It uses third person voice, includes specific concrete actions, references a well-known standard (Keep a Changelog), and provides an explicit 'Use when' clause with natural trigger terms. The description is concise yet comprehensive, covering the key use cases without unnecessary verbosity.
| 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 | Clearly occupies a distinct niche around changelog generation and release note automation. The specific mention of Keep a Changelog format, commits, PRs, and release workflows makes it unlikely to conflict with other skills like general git skills or CI/CD 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 is highly actionable with complete, executable configurations for multiple tools, but it severely suffers from being a monolithic reference dump rather than a focused, well-structured skill. It tries to cover six different implementation methods in full detail within a single file, making it extremely token-inefficient. The lack of a decision framework for choosing between methods and the absence of validation checkpoints further weaken its utility as a practical guide.
Suggestions
Restructure as a concise overview in SKILL.md with a decision table for choosing a method, then move each implementation method (standard-version, semantic-release, git-cliff, commitizen, etc.) into its own referenced file.
Remove the 'Core Concepts' sections on Keep a Changelog format, Conventional Commits, and Semantic Versioning—Claude already knows these standards; at most include a brief mapping table.
Add a clear workflow with validation steps: e.g., 1) Choose method → 2) Set up commit linting → 3) Verify with test commit → 4) Configure changelog generation → 5) Dry-run release → 6) Enable CI automation.
Remove the release note templates and commit message examples, or move them to a separate EXAMPLES.md file—they add significant length without being core to the automation setup task.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Includes 6 different implementation methods, multiple release note templates, commit message examples Claude already knows, and a best practices section with generic advice. Much of this is reference material that should be in separate files or omitted entirely. | 1 / 3 |
Actionability | Provides fully executable, copy-paste ready configurations and commands for every method: commitlint setup, standard-version config, semantic-release config, GitHub Actions workflows, git-cliff TOML, and commitizen pyproject.toml. All code is concrete and complete. | 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 methods are listed without sequencing or validation checkpoints—e.g., no step to verify commitlint is working after setup, no verification that the generated changelog is correct before publishing. | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with everything inline. Six full implementation methods, two release note templates, commit examples, and best practices are all crammed into one file. This content desperately needs to be split into separate files (e.g., one per method) with the SKILL.md serving 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
27a7ed9
- 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.