release-notes-generator
Generate release notes in 3 formats (CHANGELOG.md, PR body, Slack announcement) from git commits. Automatically categorizes changes and converts technical language to user-friendly messaging. Use for releases, changelogs, version notes, what's new summaries, or ship announcements.
82
78%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./examples/skills/release-notes-generator/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 an excellent skill description that clearly communicates specific capabilities (3 output formats, automatic categorization, language conversion), provides rich natural trigger terms, and explicitly states when to use it. It uses proper third-person voice throughout and carves out a distinct niche that would be easy to differentiate from other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: generating release notes in 3 named formats (CHANGELOG.md, PR body, Slack announcement), automatically categorizing changes, and converting technical language to user-friendly messaging. | 3 / 3 |
Completeness | Clearly answers both what (generate release notes in 3 formats, categorize changes, convert technical language) and when ('Use for releases, changelogs, version notes, what's new summaries, or ship announcements') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'release notes', 'changelogs', 'version notes', 'what's new', 'ship announcements', 'CHANGELOG.md', 'PR body', 'Slack announcement'. These are terms users would naturally use when requesting this kind of output. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive niche combining git commits with release note generation in specific formats. The mention of CHANGELOG.md, PR body, and Slack announcement creates a clear, unique identity unlikely to conflict with general git or documentation skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-organized skill with good structure and useful reference tables for tech-to-product transformation and commit categorization. Its main weaknesses are the lack of truly executable code tying the workflow together (the bash snippets are individual commands, not a cohesive process) and some verbosity in formatting and obvious tips. The migration alert system is a nice safety feature but could be expressed more concisely.
Suggestions
Add an executable script or step-by-step function that ties the individual bash commands into a complete workflow, rather than listing them separately under 'Commands Used'.
Remove obvious tips like 'Run from repository root' and 'Ensure gh CLI is authenticated' — Claude already knows these prerequisites.
Add explicit validation steps: verify the tag exists before proceeding, confirm PR details were fetched successfully, and include a review checkpoint before writing files.
Condense the ASCII box art migration alert into a simpler format description — Claude can generate formatted output without seeing the exact character-by-character layout.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately verbose. The tech-to-product transformation table and commit categories table add genuine value, but sections like 'Tips' contain obvious advice ('Run from repository root', 'Ensure gh CLI is authenticated'), and the elaborate ASCII box art for migration alerts consumes significant tokens for formatting that Claude can infer from a simpler description. | 2 / 3 |
Actionability | The skill provides concrete bash commands for git operations and clear output format templates, but the core workflow lacks executable code — there's no actual script or function that ties the steps together. The 'How to Use' section shows natural language prompts rather than executable commands, and key details like how to actually parse commits and generate the three formats are left implicit. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced (analyze → fetch → categorize → generate → transform → alert), and the migration detection includes a validation checkpoint. However, there are no explicit validation/verification steps for the generated outputs themselves — no step to verify PR details were fetched correctly, no error handling for missing tags, and no feedback loop for reviewing/correcting categorization before generating final outputs. | 2 / 3 |
Progressive Disclosure | The skill is well-structured with clear sections progressing from overview to details, and appropriately references external files (templates, mappings, categorization rules) at one level deep. The Reference Files section clearly signals where to find detailed materials without nesting references. | 3 / 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 |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Commit
4ef3dec
- 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.