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

60%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

63%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is highly actionable and accurate, with executable code, commands, and thorough examples for every commit type. Its main weaknesses are verbosity — duplicating spec content Claude already knows and repeating examples across sections — and a monolithic single-file layout where the spec rules, FAQ, and tool integrations belong in one-level-deep reference files.

Suggestions

Deduplicate: the breaking-change examples (lines ~176–194 and ~300–321), the revert example (~340–343 and ~479–483), and the BREAKING CHANGE rules (stated in three sections) should each appear once.

Move the verbatim 16-rule spec transcription, the FAQ, and the tool integration configs (commitlint/semantic-release/git-cliff) into one-level-deep reference files (e.g., references/spec.md, references/tools.md), keeping SKILL.md as a lean overview.

Replace the spec transcription with a short "how to compose a message from a change" procedure (determine type → check breaking change → write imperative description ≤72 chars → optional body/footers), since Claude already knows the underlying spec.

Dimension	Reasoning	Score
Conciseness	The 500+ line body transcribes the entire Conventional Commits v1.0.0 spec verbatim (rules 1–16), a Benefits section, and an FAQ — material Claude already knows — and duplicates content: the three breaking-change examples appear twice, the revert example appears twice, and BREAKING CHANGE rules are stated in three separate sections. It is not a 1 because the tables, regex, and tool configs are dense reference material rather than fluffy explanation, but several padded and redundant sections are clearly unnecessary.	2 / 5
Actionability	Fully executable, copy-paste-ready guidance throughout: a working header-validation regex, complete Python validate/parse functions, runnable commitlint install-and-test bash commands, semantic-release and git-cliff config snippets, and concrete good/bad example messages covering all common cases.	5 / 5
Workflow Clarity	The single action (compose a conforming commit message) is unambiguous and fully supported — structure, types, rules, best practices, and examples are all specified. It is not a 5 because the body is a reference document rather than a procedure; no explicit sequence guides the reader from a change/diff to a finished message, and the reader must synthesize the workflow from the spec rules.	4 / 5
Progressive Disclosure	Section headers are clear and well-organized, but the entire skill is a single ~515-line monolith with no bundle files; content that clearly belongs in separate reference files — the full 16-rule spec transcription, the FAQ, tool integration configs, and the References/Related Skills sections — is inlined. This matches the anchor "content that should be separate is inline" with some structure present.	3 / 5
	Total	14 / 20 Passed

Description

57%Weight 40%Scale 1-5

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 provides strong, explicit trigger coverage for the Conventional Commits domain, but omits any 'what' statement describing the skill's capability, leaving a user to infer its purpose from trigger clauses alone. Adding a leading third-person capability sentence would resolve the main gap.

Suggestions

Add a leading capability statement before the trigger clauses, e.g., "Composes git commit messages following the Conventional Commits v1.0.0 specification, for structured history, automated changelogs, and semantic versioning."

Include natural trigger synonyms users commonly say: "semver", "version bump", "commit convention", and "commitlint".

Reword the overly broad clause "When task completes and changes need committing" to reference conventional-commit context specifically, reducing overlap with generic git skills.

Dimension	Reasoning	Score
Specificity	The description names several concrete, domain-specific items — "When writing a git commit message", "When choosing between feat/fix/chore/docs types", "When indicating breaking changes", "When generating changelogs from commit history" — which are specific rather than generic. It falls short of a 5 because these are all trigger conditions; no explicit capability statement of what the skill actually does is ever made.	4 / 5
Completeness	Only "when" guidance is present — the description is entirely a chain of "When ..." trigger clauses with no statement of what the skill does (e.g., "Compose commit messages following the Conventional Commits specification"). This matches the anchor "only 'when' is present without 'what'". It is not a 3 because that anchor requires a clear 'what' with only weakly implied 'when'; the 'what' is entirely absent.	2 / 5
Trigger Term Quality	Good natural keyword coverage: "git commit message", "committing", "breaking changes", "changelog", plus tool names (semantic-release, commitizen, git-cliff) and type keywords (feat/fix/chore/docs). Not a 5 because common variations like "semver"/"version bump", "commit convention", or "squash/merge commits" are missing.	4 / 5
Distinctiveness Conflict Risk	The conventional-commits niche is clear — feat/fix types, semantic-release, changelog generation are distinct triggers unlikely to fire for unrelated skills. Minor overlap risk remains with generic git/commit-helper skills due to the broad clause "When task completes and changes need committing".	4 / 5
	Total	14 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (517 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: Jamie-BitFlight/claude_skills
Path: plugins/conventional-commits/skills/conventional-commits/SKILL.md
Commit: 3e0b2af

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.