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.

Quality

52%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./plugins/conventional-commits/skills/conventional-commits/SKILL.md

Quality

Content

50%

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 it is far too verbose for a skill file. It essentially reproduces the entire Conventional Commits specification, FAQ, and benefits list — information Claude already knows or that should be in separate reference files. The content would benefit greatly from aggressive trimming to focus on the commit message template, type table, key examples, and validation pattern.

Suggestions

Remove the 'When to Use This Skill' section, 'Benefits' section, and FAQ — these explain concepts Claude already knows and waste token budget.

Move the full specification rules (rules 1-16) and extensive examples into a separate REFERENCE.md file, keeping only the message structure template, type table, and 3-4 key examples in SKILL.md.

Add a clear sequential workflow for composing a commit message: determine type → determine scope → write description → add body/footer if needed → validate with regex.

Remove the mermaid diagrams and redundant tables (SemVer mapping is stated three times in different formats) to reduce token usage.

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 a 'When to Use This Skill' section that is unnecessary. The content could be reduced by 60-70% without losing 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 commit message structure and format are clearly presented with good tables and examples. However, there's no clear sequential workflow for composing a commit message (e.g., 1. determine type, 2. determine scope, 3. write description, 4. validate). The validation step exists but isn't integrated into a coherent workflow with feedback loops.	2 / 3
Progressive Disclosure	References to related skills (commitlint, pre-commit) are well-signaled, but the document itself is monolithic — the full specification rules, FAQ, benefits, and extensive examples are all inline rather than split into separate reference files. Much of this content (spec rules, FAQ, references) should be in supporting files.	2 / 3
	Total	8 / 12 Passed

Description

54%

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 critically lacks any statement of what the skill actually does—it reads as a list of 'when' clauses without a corresponding 'what' clause. Adding a clear capability statement like 'Generates and formats git commit messages following conventional commits specification' would significantly improve it.

Suggestions

Add a clear 'what it does' statement at the beginning, e.g., 'Generates and formats git commit messages following the Conventional Commits specification.'

Restructure to lead with capabilities (concrete actions like 'formats commit messages', 'selects appropriate commit type', 'flags breaking changes') before the 'Use when...' triggers.

Dimension	Reasoning	Score
Specificity	The description names the domain (git commit messages) and references specific concepts like semantic-release, commitizen, git-cliff, and commit types (feat/fix/chore/docs), but it doesn't list concrete actions the skill performs—it only describes situations/triggers. There's no 'what it does' like 'generates commit messages' or 'formats messages according to conventional commits spec'.	2 / 3
Completeness	The description is almost entirely 'when' clauses with no clear 'what does this do' statement. It never explains what the skill actually does—it only lists trigger scenarios. The 'what' component is missing, which is a critical gap even though the 'when' is well-covered.	1 / 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 terms users would naturally mention when needing this skill.	3 / 3
Distinctiveness Conflict Risk	The description is clearly focused on git commit message formatting with specific tooling references (semantic-release, commitizen, git-cliff) and conventional commit types, making it highly distinctive and unlikely to conflict with other skills.	3 / 3
	Total	9 / 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
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: 2f639b2

Reviewed: 3 days 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.