generate-release-notes

Generate categorized release notes from any source (GitHub, Linear, Jira, or manual input) with optional publishing

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/generate-release-notes/SKILL.md

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable with a clear, validated multi-phase workflow, but it is monolithic — all collector scripts and output templates are inlined rather than progressively disclosed into separate reference files.

Suggestions

Move the per-source collector agent prompts (GitHub/Linear/Jira) and the external/internal output templates into files under references/ and link to them from SKILL.md to improve progressive disclosure.

Consider extracting the categorization rules and fallback/error-handling tables into a short reference so the main body stays a lean overview.

Keep the phase sequence and review gate as the spine of SKILL.md while pointing to the extracted references for the bulk content.

Dimension	Reasoning	Score
Conciseness	The body is efficient and assumes Claude's competence (no basic-concept padding), with most length coming from legitimate output templates and commands rather than fluff; a few inlined templates could be trimmed.	4 / 5
Actionability	It provides copy-paste-ready, fully executable commands (gh pr list with flags, JQL queries, gh release create) and concrete save paths covering the common source/audience cases.	5 / 5
Workflow Clarity	Phases 1–6 are explicitly sequenced with an approval review gate ('NEVER auto-publish') as a validation checkpoint, plus a fallback table and error-handling section providing feedback loops for recovery.	5 / 5
Progressive Disclosure	The content is well-organized with clear headers, but everything is inlined in SKILL.md with no bundle files; the per-source collector prompts and full output templates are substantial content that would be better split into reference files.	3 / 5
	Total	17 / 20 Passed

Description

53%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description conveys a clear purpose and niche but omits any explicit 'when to use' trigger guidance, which caps completeness, and it relies on a single natural keyword ('release notes') without synonyms.

Suggestions

Add a 'Use when...' clause naming concrete triggers, e.g. 'Use when the user asks for release notes, a changelog, or what shipped in a version/sprint/cycle.'

Include natural synonyms such as 'changelog' and 'what shipped' alongside 'release notes' to broaden trigger coverage.

Optionally surface the categorization capability more concretely (e.g. 'categorize into breaking changes, features, fixes, and security updates') to lift specificity.

Dimension	Reasoning	Score
Specificity	The description names the domain and two concrete actions ('Generate categorized release notes', 'optional publishing') plus an enumerated source list, but the action set is not comprehensive — it stops at generate + publish.	3 / 5
Completeness	It clearly states what the skill does but lacks any 'Use when...' trigger clause; per the rubric a missing explicit trigger guidance caps completeness at 3.	3 / 5
Trigger Term Quality	'release notes' is a natural term users say, but common synonyms like 'changelog' or 'what shipped' are absent, and the named integrations (GitHub, Linear, Jira) are inputs rather than trigger phrases.	3 / 5
Distinctiveness Conflict Risk	The release-notes niche is mostly distinct with a clear trigger, though there is minor overlap risk with general documentation or changelog-style skills.	4 / 5
	Total	13 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: huytieu/COG-second-brain
Path: .claude/skills/generate-release-notes/SKILL.md
Commit: cb4644d

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

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.