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.
52
57%
Does it follow best practices?
Impact
—
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 excellent 'when to use' guidance with specific tool names and terminology. However, it critically lacks an explicit statement of what the skill actually does — it's entirely composed of 'When...' clauses without a capability statement. Adding a clear 'what' statement would significantly 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 lead with 'what it does' followed by 'Use when...' to clearly separate capabilities from trigger conditions.
| 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 'indicating breaking changes', but it doesn't explicitly list concrete actions the skill performs (e.g., 'generates commit messages', 'formats messages according to conventional commits spec'). It's mostly a list of 'when' triggers rather than 'what it does'. | 2 / 3 |
Completeness | The description is almost entirely 'when' clauses with strong explicit triggers, but the 'what does this do' part is largely missing or only implied. There's no clear statement of what the skill actually does (e.g., 'Generates conventional commit messages' or 'Formats commit messages following conventional commits specification'). | 2 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'git commit message', 'semantic-release', 'commitizen', 'git-cliff', 'feat/fix/chore/docs', 'breaking changes', 'changelogs'. These are all terms a user would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | The description carves out a very clear niche around conventional commit message formatting with specific tool references (semantic-release, commitizen, git-cliff) and commit type terminology (feat/fix/chore/docs). 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.
The skill is highly actionable with excellent concrete examples and executable code, but is severely bloated for a Claude-facing skill. It reproduces the entire Conventional Commits specification verbatim, includes FAQ and benefits sections that add no value for Claude, and packs everything into a single monolithic file. The core actionable content (message format, type table, a few examples, and the validation regex) could be delivered in under 80 lines.
Suggestions
Reduce content by 60%+: remove the verbatim specification rules (1-16), FAQ section, Benefits section, mermaid diagrams, and 'When to Use This Skill' — Claude already knows the Conventional Commits spec and doesn't need RFC 2119 language repeated.
Split into bundle files: move complete examples into EXAMPLES.md, tool integration configs into TOOLING.md, and keep SKILL.md as a concise reference with the format template, type table, and key rules only.
Remove explanatory content Claude already knows, such as what Semantic Versioning is, what PDF means (analogously), and the benefits list copied from the official site.
Consolidate the three separate type tables into a single compact table with a SemVer column, eliminating redundant information spread across sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose for a skill targeting Claude. Reproduces the entire Conventional Commits specification (rules 1-16 verbatim), 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 all types and edge cases, and a usable regex pattern. The examples are copy-paste ready and comprehensive. | 3 / 3 |
Workflow Clarity | The skill covers a single-task domain (writing commit messages) so complex workflows aren't strictly needed, but the commitlint setup and changelog generation sections present steps without validation checkpoints. The overall flow of 'choose type → write message → validate' is implicit rather than explicitly sequenced. | 2 / 3 |
Progressive Disclosure | All content is inlined in a single monolithic file with no bundle files. The specification rules, complete examples, FAQ, tool integration, and references are all dumped into one document. Content like the full spec rules, FAQ, and tool integration configs would benefit greatly from being split into separate referenced files. | 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
4e61312
- 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.