Conventional Commits

Core Question

What Conventional Commit message accurately describes the exact change evidence provided, without expanding scope or claiming unsupported impact?

When To Use

Use this skill when the user asks to:

• write or revise a Conventional Commit message,
• validate an existing commit message,
• choose a commit type, scope, subject, body, or footer,
• express a breaking change using ! or BREAKING CHANGE:,
• generate a message from staged diff or from explicitly provided diff evidence.

When Not To Use

Do not use this skill to stage files, unstage files, create commits, split commits, or decide atomic boundaries.

Route to:

• atomic-commits when the task requires staging, unstaging, commit execution, commit splitting, or multiple commits.
• changelog-maintenance when updating a changelog file.
• release-notes when drafting user-facing release notes.
• version-bump when deciding or editing versions.
• tag-release when creating or pushing Git tags.

Required Evidence

Inspect or establish:

• the exact staged diff when the message is for the current commit,
• the exact file or hunk evidence provided by a caller such as atomic-commits,
• user-provided change summary when no repository evidence is available,
• project commit conventions such as .commitlintrc*, commitlint.config.*, package.json, CONTRIBUTING.md, or recent commit style,
• breaking-change evidence before using ! or a BREAKING CHANGE: footer,
• issue or ticket references only when supplied or evidenced.

No evidence means no strong claim. A message from unstaged evidence must be labeled as a draft for unstaged changes and must not imply those changes are staged, selected, or ready to commit.

Operating Contract

This skill is message-only.

You MAY:

• inspect staged diff and commit convention evidence,
• generate one or more candidate commit messages,
• validate a message against project conventions,
• explain why a type, scope, or footer was selected.

You MUST:

• use only the provided or inspected change evidence,
• prefer staged diff over unstaged diff for messages intended for the current commit,
• label assumptions and missing evidence,
• avoid claiming performance, security, compatibility, or breaking impact without evidence,
• route mutation, staging, commit execution, and history operations to the owning skill.

You MUST NOT:

• stage files,
• unstage files,
• mutate the Git index,
• create commits,
• run git commit,
• create multiple commits,
• split working tree changes,
• decide atomic commit boundaries,
• include unstaged or untracked files unless the caller explicitly passes them as evidence.

State / Risk Table

Workflow

1. Identify whether the request is message generation, validation, or revision.
2. Inspect or receive the exact change evidence.
3. Inspect project commit conventions when available.
4. Classify the change type, scope, breaking-change status, and evidence limits.
5. Produce or validate the commit message.
6. Self-check format, scope, and unsupported claims.
7. Report the result, evidence source, assumptions, and limitations.

Decision Rules

• Use feat for evidenced user-visible capability additions.
• Use fix for evidenced bug fixes or corrected behavior.
• Use docs for documentation-only changes.
• Use test for tests-only changes.
• Use refactor for internal restructuring with no evidenced behavior change.
• Use perf only when performance intent or benchmark/profiling evidence exists.
• Use build for package, dependency, lockfile, or build-system changes.
• Use ci for CI workflow changes.
• Use chore for maintenance not covered by a more specific type.
• Use revert for revert commits and include the reverted context when evidenced.
• Do not add a scope unless it is evidenced by project convention, module, package, or file path.
• Do not invent ticket IDs, issue references, or migration notes.

Tool Rules

• Prefer read-only Git commands such as git diff --cached, git status --short, and git log --oneline -n 20.
• Do not run git commit.
• Do not stage or unstage files.
• Do not mutate the Git index.
• Do not decide file grouping or atomic commit boundaries.
• If the request requires mutation, remote/shared state, destructive action, or history rewriting, route to the owning skill and do not execute the action here.

Verification

Minimum verification:

• R0: evidence source identified.
• R1: message self-checked for Conventional Commit syntax, type/scope correctness, breaking-change accuracy, and unsupported claims.

Before returning a message, verify:

• the message describes only the evidence used,
• unstaged evidence is labeled as a draft when applicable,
• no secret-like value is copied,
• no security, performance, release, or compatibility claim exceeds evidence.

Output Contract

Final response should include:

## Result

- Commit message or validation verdict.

## Evidence

- Staged diff, provided diff, user summary, and convention files used.

## Assumptions / Limitations

- Missing evidence or unstaged-draft status.

## Verification

- Format and evidence self-check.

Stop / Confirmation Rules

• Stop when evidence is missing in a way that would make the message misleading.
• Stop and redact when secret-like values appear.
• Stop and route when the request requires staging, unstaging, commit execution, remote/shared mutation, destructive action, or history rewriting.
• No confirmation can expand this skill into a mutation-capable workflow; route to the owning skill instead.

Lazy-load References

Load:

• references/type-map.md when type selection is ambiguous.
• references/scope-rules.md when scope conventions are unclear.
• references/breaking-changes.md when breaking-change syntax or footer rules are needed.
• references/examples.md when the user asks for examples.
• references/validation.md when validating format or commitlint behavior.