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.
68
61%
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 like 'formats commit messages, selects appropriate type prefixes, 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's 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
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive but excessively verbose reproduction of the Conventional Commits specification. While it excels at actionability with concrete examples and executable code, it massively over-explains concepts Claude already knows (SemVer correlation, what commit types mean, the full RFC 2119-style specification rules). A lean version at ~25% of the current length, focusing on the format template, a few examples, and tool configuration snippets, would be far more effective.
Suggestions
Cut the content by 60-75%: remove the full specification rules section (Claude knows the spec), the Benefits section, the FAQ, and the mermaid diagrams. Keep only the message structure template, a compact type table, 3-4 examples, and tool config snippets.
Move the complete examples catalog and tool integration details into separate referenced files (e.g., EXAMPLES.md, TOOLS.md) to improve progressive disclosure.
Add an explicit workflow: 'When composing a commit: 1. Review staged changes 2. Choose type based on change nature 3. Determine scope 4. Write imperative description 5. Validate with regex/commitlint'.
Remove explanations of what Conventional Commits is, what SemVer is, and what benefits structured commits provide—Claude already knows all of this.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Reproduces the entire Conventional Commits specification verbatim (all 16 rules), explains basic concepts Claude already knows (what SemVer is, what RFC 2119 is, what a PDF-like 'Benefits' section listing why structured commits matter), includes an FAQ section, mermaid diagrams, and extensive reference links. Most of this content is publicly available knowledge Claude already has internalized. | 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 scenario, and a usable regex pattern. The guidance is copy-paste ready throughout. | 3 / 3 |
Workflow Clarity | The skill is primarily a reference/format specification rather than a multi-step workflow. While the commit message structure is clearly laid out, there's no explicit workflow for composing a commit message (e.g., check diff → choose type → write description → validate). The validation step exists but isn't integrated into a sequential process. | 2 / 3 |
Progressive Disclosure | References to related skills (commitlint, pre-commit) are well-signaled, but the main document is a monolithic wall of text with massive inline content that could be split into separate reference files (e.g., the full spec rules, the FAQ, the complete examples catalog, the tool integration section). The document tries to be both a quick reference and an exhaustive specification simultaneously. | 2 / 3 |
Total | 8 / 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
11ec483
- 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.