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.
76
64%
Does it follow best practices?
Impact
100%
1.25xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/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 explicit trigger guidance with natural keywords. The description is concise yet comprehensive, making it easy for Claude to select appropriately from a large skill set.
| 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 ('Use when setting up release workflows, generating release notes, or standardizing commit conventions') with an explicit 'Use when' clause. | 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 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 snippets and configurations are executable and complete, the skill suffers from extreme verbosity (6 methods when 1-2 would suffice), lack of workflow sequencing, and poor organization with everything crammed into one file. It reads more like a documentation aggregation page than a skill that teaches Claude how to perform a specific task.
Suggestions
Reduce to 1-2 recommended methods (e.g., semantic-release for full automation, git-cliff for lightweight) and move others to separate reference files linked from the main skill.
Add a clear numbered workflow for each method: install → configure → validate setup → first release → verify output, with explicit checkpoints.
Remove the Core Concepts section (Keep a Changelog format, Conventional Commits spec, semver explanation) — Claude already knows these standards. Keep only the mapping table between commit types and changelog sections.
Split into SKILL.md (overview + recommended quick start) with links to METHOD_SEMANTIC_RELEASE.md, METHOD_GIT_CLIFF.md, TEMPLATES.md etc.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Includes 6 different methods (standard-version, semantic-release, git-cliff, commitizen, GitHub Actions, conventional changelog) when 1-2 would suffice. Explains Conventional Commits format, semver, and Keep a Changelog format which Claude already knows. The release notes templates, best practices do's/don'ts, and commit message examples add significant bloat. | 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) and bash commands are specific and runnable. | 3 / 3 |
Workflow Clarity | Despite presenting 6 different methods, there is no clear workflow sequence for any of them. Steps are not numbered or sequenced within each method - they're just config dumps. No validation checkpoints, no 'verify this worked before proceeding' steps, no error recovery guidance. 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 everything inline. Six complete implementation methods, two release note templates, commit examples, best practices, and external resources are all dumped into a single file. This content desperately needs to be split into separate files (e.g., methods in their own files) with the SKILL.md serving as an overview with links. | 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 (581 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- Dicklesworthstone/pi_agent_rust
- Commit
47823e3
- 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.