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.
79
75%
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, change 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: generate release notes in 3 named formats (CHANGELOG.md, PR body, Slack announcement), automatically categorizes changes, and converts 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 documentation or git skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a well-structured overview of a release notes generation workflow with useful transformation tables and clear output format specifications. Its main weaknesses are the lack of executable implementation code (it describes what to do rather than providing runnable scripts), moderate verbosity in some sections, and inline content that would benefit from being split into referenced files. The migration alert feature is a strong safety-oriented addition.
Suggestions
Provide an executable script or detailed code implementation that actually parses git commits, categorizes them, and generates the three output formats, rather than just listing the bash commands and describing the desired output.
Move the tech-to-product transformation table and commit categories table into the referenced files (references/tech-to-product-mappings.md, references/commit-categories.md) and keep only 1-2 inline examples to demonstrate the concept.
Add explicit validation steps to the workflow, such as verifying the generated CHANGELOG section parses as valid markdown and confirming with the user before writing to files or creating PRs.
Remove obvious tips like 'Run from repository root' and 'Ensure gh CLI is authenticated' that Claude can infer, and trim the ASCII box art to a simpler format description.
| 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 lacks executable, copy-paste-ready scripts that actually generate the release notes. The workflow describes what to do at a high level but doesn't provide the actual implementation code to parse commits, categorize them, or produce the three output formats. The commands section is helpful but fragmented. | 2 / 3 |
Workflow Clarity | The workflow is clearly sequenced (6 steps in the main workflow, 7 steps in the integration workflow), and the migration detection includes a validation checkpoint. However, there are no explicit validation/verification steps for the generated outputs themselves (e.g., verifying CHANGELOG format correctness, confirming PR body renders properly), and the 'Write to files?' confirmation at the end is shown in an example but not formalized as a required checkpoint in the workflow. | 2 / 3 |
Progressive Disclosure | The skill references external files (assets/changelog-template.md, references/tech-to-product-mappings.md, etc.) and related skills, which is good progressive disclosure. However, the main file itself is quite long (~200 lines) with inline content that could be split out (e.g., the full output format examples, the transformation table, the commit categories table), and the references are only listed at the bottom rather than being signaled inline where relevant. | 2 / 3 |
Total | 8 / 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 | |
746adc8
Table of Contents
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.