changelog-generator

Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.

1.03x

Quality

37%

Does it follow best practices?

Impact

99%

1.03x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/all-skills/skills/changelog-generator/SKILL.md

Quality

Discovery

67%

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 clearly communicates specific capabilities around changelog generation from git history and is distinctive in its niche. However, it lacks an explicit 'Use when...' clause, which limits its completeness score, and the final sentence is marketing fluff that wastes space that could be used for trigger terms or usage guidance.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to generate a changelog, write release notes, summarize recent commits, or prepare a CHANGELOG.md for a new version.'

Replace the marketing sentence ('Turns hours of manual changelog writing into minutes of automated generation') with additional trigger terms or file format mentions like 'CHANGELOG.md', 'version notes', 'release summary', or 'what's new'.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: analyzing commit history, categorizing changes, transforming technical commits into customer-friendly release notes. These are clear, actionable capabilities.	3 / 3
Completeness	The 'what' is well-covered (creates changelogs from git commits, categorizes changes, transforms into customer-friendly notes), but there is no explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied by the description of capabilities.	2 / 3
Trigger Term Quality	Includes good terms like 'changelogs', 'git commits', 'release notes', and 'commit history', but misses common user variations like 'CHANGELOG.md', 'what changed', 'version notes', or 'release summary'. The phrase 'Turns hours of manual changelog writing into minutes' is marketing fluff rather than trigger terms.	2 / 3
Distinctiveness Conflict Risk	The combination of git commits, changelogs, and customer-friendly release notes creates a clear niche that is unlikely to conflict with general git skills or general documentation skills. The specific focus on transforming commits into user-facing changelogs is distinctive.	3 / 3
	Total	10 / 12 Passed

Implementation

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

This skill reads more like a marketing page or README for a product feature than an actionable skill for Claude. It spends most of its tokens describing what the skill does and when to use it, rather than providing concrete instructions on how to actually analyze git commits, categorize them, and transform them into user-friendly language. The complete absence of executable commands (like git log invocations) or concrete categorization rules makes this essentially non-functional as a skill.

Suggestions

Replace the 'What This Skill Does' and 'When to Use' sections with a concrete workflow: specific git commands to run (e.g., `git log --oneline --since='2024-03-01'`), commit categorization rules (e.g., 'feat:' → New Features, 'fix:' → Bug Fixes), and transformation guidelines.

Add explicit commit-to-changelog transformation rules with before/after examples, e.g., 'feat(auth): add JWT token refresh' → 'Your login sessions now stay active longer, so you won't be logged out unexpectedly.'

Include a concrete step-by-step workflow with validation: 1) Run git log command, 2) Filter out internal commits (list specific patterns to exclude like 'chore:', 'ci:', 'test:'), 3) Categorize remaining commits, 4) Transform language, 5) Review for accuracy.

Remove the 'When to Use This Skill', 'Related Use Cases', and 'Tips' sections—these are filler that Claude doesn't need. Use that space for actionable categorization rules and transformation examples.

Dimension	Reasoning	Score
Conciseness	Heavily padded with unnecessary content. The 'When to Use This Skill' section lists 7 obvious use cases Claude doesn't need. 'What This Skill Does' explains the concept at length rather than instructing. 'Related Use Cases' adds more filler. Much of this describes rather than instructs.	1 / 3
Actionability	No executable code, no concrete git commands, no actual implementation steps. The 'How to Use' section just shows natural language prompts to give Claude, not actionable instructions for Claude to follow. There's no git log command, no parsing logic, no commit categorization rules—just vague descriptions of what should happen.	1 / 3
Workflow Clarity	The 'What This Skill Does' lists steps conceptually but provides no actual workflow with concrete commands or validation checkpoints. There's no guidance on how to actually scan git history (e.g., `git log --oneline v2.4.0..HEAD`), how to categorize commits (what patterns to match), or how to verify the output. The process is entirely abstract.	1 / 3
Progressive Disclosure	The content is organized into sections with headers, which provides some structure. It mentions CHANGELOG_STYLE.md as an external reference. However, the content is somewhat monolithic with sections that could be trimmed or reorganized, and the example output takes up significant space that could be referenced separately.	2 / 3
	Total	5 / 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: davepoon/buildwithclaude
Commit: 7cc63f3

Reviewed: about 5 hours 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.