generate-release-notes

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

Quality

56%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./.claude/skills/generate-release-notes/SKILL.md

Quality

Discovery

57%

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 identifies a clear niche (release note generation) with specific source integrations, making it distinctive. However, it lacks an explicit 'Use when...' clause and could benefit from additional trigger terms like 'changelog' or 'what's new' to improve discoverability. The actions described are somewhat thin—mainly 'generate' and 'publish'—and could be more detailed.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to create release notes, changelogs, or version summaries from commits, issues, or tickets.'

Include common synonym trigger terms such as 'changelog', 'CHANGELOG.md', 'what's new', 'version notes', and 'release summary' to improve matching.

Expand the concrete actions beyond 'generate' and 'publish'—e.g., 'Fetches commits/issues, groups changes by category (features, fixes, breaking changes), formats release notes in markdown, and optionally publishes to GitHub Releases or Slack.'

Dimension	Reasoning	Score
Specificity	Names the domain (release notes) and mentions specific sources (GitHub, Linear, Jira, manual input) and one action (publishing), but doesn't detail what 'categorized' means or list multiple concrete actions beyond 'generate' and 'publish'.	2 / 3
Completeness	Clearly answers 'what does this do' (generate categorized release notes from various sources with optional publishing), but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric.	2 / 3
Trigger Term Quality	Includes good natural keywords like 'release notes', 'GitHub', 'Linear', 'Jira', and 'publishing', but misses common variations users might say such as 'changelog', 'what's new', 'version notes', 'release summary', or 'CHANGELOG.md'.	2 / 3
Distinctiveness Conflict Risk	The combination of 'release notes' with specific source integrations (GitHub, Linear, Jira) and 'categorized' output creates a clear niche that is unlikely to conflict with other skills.	3 / 3
	Total	9 / 12 Passed

Implementation

55%

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 excellent workflow clarity, including explicit review gates and a 'never auto-publish' safety constraint. However, it is severely bloated—the inline agent prompts, dual full-page templates, and multi-platform publishing details make it a massive token burden that should be decomposed into referenced files. The lack of any progressive disclosure or bundle structure is its biggest weakness.

Suggestions

Extract the full release note templates (internal and external) into separate referenced files like TEMPLATE-EXTERNAL.md and TEMPLATE-INTERNAL.md to dramatically reduce inline token cost.

Move the detailed agent prompt blocks (github-release-collector, linear-release-collector, jira-release-collector) into a separate COLLECTORS.md reference file, keeping only a brief summary of each in the main skill.

Move per-platform publishing instructions (GitHub, Confluence, Notion, HackMD) into a PUBLISHING.md reference file, since most invocations will only use one platform.

Remove explanatory text Claude already knows (e.g., categorization heuristics like 'feat/feature/enhancement labels → Enhancements' can be condensed to a simple mapping table).

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~250+ lines. It includes extensive template boilerplate for both internal and external audiences, full agent prompt texts that could be referenced externally, and detailed publishing instructions for four platforms. Much of this (markdown frontmatter templates, categorization rules Claude already understands, basic git/gh commands) could be dramatically condensed.	1 / 3
Actionability	The skill provides fully executable commands (gh CLI, bash mkdir, git log), concrete JQL queries, specific MCP tool names (mcp__claude_ai_Linear_2__list_issues), complete markdown templates, and clear categorization rules. Guidance is copy-paste ready throughout.	3 / 3
Workflow Clarity	The six-phase workflow is clearly sequenced with explicit validation: Phase 4 is a dedicated review gate with user options, Phase 6 requires explicit approval before publishing ('NEVER auto-publish'), and the fallback behavior table provides clear error recovery paths. The feedback loop of draft → review → revise → approve → publish is well-defined.	3 / 3
Progressive Disclosure	This is a monolithic wall of text with no bundle files or external references. The full agent prompts, both complete release note templates (internal + external), publishing instructions for four platforms, and fallback tables are all inline. The agent prompt blocks, templates, and per-platform publishing details should be split into separate referenced files.	1 / 3
	Total	8 / 12 Passed

Validation

90%

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 — 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

Repository: huytieu/COG-second-brain
Commit: 034af4c

Reviewed: 18 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.