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.
Install with Tessl CLI
npx tessl i github:Jamie-BitFlight/claude_skills --skill conventional-commits72
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 keyword coverage for conventional commit workflows. However, it inverts the typical structure by focusing almost entirely on 'when' clauses while omitting a clear statement of what the skill actually does. Adding a leading capability statement would significantly improve clarity.
Suggestions
Add a leading 'what' statement describing the skill's core function, e.g., 'Generates conventional commit messages following semantic versioning standards and commitizen conventions.'
Restructure to lead with capabilities, then follow with 'Use when...' triggers, e.g., 'Formats git commit messages using conventional commit syntax. Use when writing commit messages, when project uses semantic-release/commitizen/git-cliff...'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (git commit messages) and mentions some actions like 'choosing between feat/fix/chore/docs types' and 'generating changelogs', but lacks concrete verbs describing what the skill actually does (e.g., 'generates', 'formats', 'validates'). | 2 / 3 |
Completeness | The description is almost entirely 'when' clauses but lacks a clear 'what' statement. It tells Claude when to use it but doesn't explicitly state what the skill does (e.g., 'Generates conventional commit messages following semantic versioning standards'). | 2 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'git commit message', 'semantic-release', 'commitizen', 'git-cliff', 'feat/fix/chore/docs', 'breaking changes', 'changelogs'. These are terms developers naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinct niche with specific triggers like 'semantic-release', 'commitizen', 'git-cliff', and conventional commit types. Unlikely to conflict with other skills due to the specialized terminology. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is highly actionable with excellent examples and clear structure, but severely undermined by verbosity. It explains too much that Claude already knows (SemVer basics, what changelogs are, RFC 2119 semantics) and includes content better suited for reference files. A lean version focusing on the message structure, type table, and key examples would be far more effective.
Suggestions
Remove the 'Benefits' and 'FAQ' sections entirely—Claude doesn't need to be convinced why Conventional Commits are useful
Move the full specification rules (items 1-16) to a separate SPECIFICATION.md file, keeping only a brief summary in the main skill
Consolidate the multiple example sections into a single 'Examples' section with 5-6 representative commits covering the main patterns
Remove explanatory text like 'The following rules constitute the official Conventional Commits 1.0.0 specification per RFC 2119'—just show the rules
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at 400+ lines. Explains concepts Claude already knows (what SemVer is, what git commits are, RFC 2119 keywords). The FAQ section, benefits list, and extensive specification rules are unnecessary padding—Claude can reference the official spec if needed. | 1 / 3 |
Actionability | Provides fully executable code examples including Python validation, regex patterns, commitlint configuration, and semantic-release setup. Examples are copy-paste ready and cover the full range of commit types. | 3 / 3 |
Workflow Clarity | For a single-task skill (writing commit messages), the workflow is unambiguous. The message structure is clearly defined, the mermaid diagrams show decision flows, and validation patterns are provided for verification. | 3 / 3 |
Progressive Disclosure | References to related skills (commitlint, pre-commit) are well-signaled, but the document itself is monolithic. The extensive specification rules, FAQ, and benefits sections should be in separate reference files rather than inline. | 2 / 3 |
Total | 9 / 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 (522 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- 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.