conventional-commits
When writing a git commit message. When task completes and changes need committing. When project uses semantic-release, commitizen, git-cliff. When choosing between feat/fix/chore/docs types. When indicating breaking changes. When generating changelogs from commit history.
65
57%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/conventional-commits/skills/conventional-commits/SKILL.mdQuality
Discovery
72%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 excels at trigger terms and distinctiveness, providing rich keywords that would help Claude select this skill in the right context. However, it is structured entirely as 'Use when...' clauses without ever stating what the skill actually does, which is a significant gap in completeness. Adding a clear capability statement at the beginning would substantially improve it.
Suggestions
Add an explicit capability statement at the beginning, e.g., 'Generates and formats git commit messages following the Conventional Commits specification.'
Restructure to separate 'what it does' from 'when to use it' — list concrete actions (formats messages, selects commit type, flags breaking changes) before the trigger clauses.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (git commit messages) and references some actions like 'choosing between feat/fix/chore/docs types' and 'generating changelogs,' but it reads more as a list of trigger scenarios than concrete actions the skill performs. It doesn't clearly state what the skill does (e.g., 'Generates conventional commit messages'). | 2 / 3 |
Completeness | The description is almost entirely 'when' clauses with strong trigger guidance, but the 'what does this do' part is missing or only implied. There is no explicit statement of the skill's capabilities (e.g., 'Formats commit messages following Conventional Commits specification'). | 2 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms: 'git commit message', 'semantic-release', 'commitizen', 'git-cliff', 'feat/fix/chore/docs', 'breaking changes', 'changelogs'. These are terms users would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | The description is highly specific to conventional commit message formatting with clear niche triggers like 'semantic-release', 'commitizen', 'git-cliff', and commit type prefixes. This is unlikely to conflict with other skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is comprehensive and highly actionable with excellent concrete examples and executable code, but it is far too verbose for a skill file targeting Claude. It essentially reproduces the entire Conventional Commits specification, FAQ, benefits list, and tool ecosystem documentation—most of which Claude already knows. The content would benefit enormously from aggressive trimming to focus only on the format template, key rules Claude might misapply, and the validation/tooling snippets.
Suggestions
Reduce content by 60%+: Remove the 16 specification rules (Claude knows the spec), the FAQ section, the Benefits section, and the 'When to Use This Skill' boilerplate. Keep only the message structure template, type table, description best practices, breaking change syntax, and validation code.
Split into bundle files: Move complete examples, tool integration configs (commitlint, semantic-release, git-cliff), and the specification rules into separate referenced files to keep SKILL.md as a lean overview.
Add a clear single workflow: Include a concise 3-4 step process like '1. Determine type from change category → 2. Add scope if applicable → 3. Write imperative description under 72 chars → 4. Validate with regex or commitlint before committing.'
Remove mermaid diagrams: These consume significant tokens and convey information already captured in the tables. The SemVer mapping table alone is sufficient.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose for a skill targeting Claude. Reproduces the entire Conventional Commits specification (rules 1-16 verbatim with RFC 2119 language), explains benefits Claude already knows, includes an FAQ section, mermaid diagrams, extensive reference links, and 'When to Use This Skill' boilerplate. Much of this is publicly available knowledge Claude already has internalized. The content could be reduced by 60-70% while preserving all actionable value. | 1 / 3 |
Actionability | Provides fully executable code examples (Python validation, commitlint setup, semantic-release config, git-cliff config), concrete commit message examples covering every type and variation, a usable regex pattern, and copy-paste ready tool configurations. The guidance is specific and directly usable. | 3 / 3 |
Workflow Clarity | The skill covers a single-task domain (writing commit messages) so complex workflows aren't strictly needed, but the content lacks a clear sequential workflow for actually composing a commit message. The commitlint setup has clear steps, but the core task—deciding type, writing description, adding body/footer—is spread across many sections without a unified step-by-step process. No validation checkpoint like 'verify your message matches the regex before committing.' | 2 / 3 |
Progressive Disclosure | Monolithic wall of text with no bundle files to offload content into. The specification rules, complete examples, FAQ, integration guides, and references are all inline in a single massive document. The specification rules (16 numbered items), the FAQ, the benefits section, and the extensive references could all be in separate files, leaving SKILL.md as a concise overview with pointers. | 1 / 3 |
Total | 7 / 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 |
|---|---|---|
skill_md_line_count | SKILL.md is long (523 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- Jamie-BitFlight/claude_skills
- Commit
b9f32ec
- 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.