write-conventional-commit
Create Git commit messages that conform to Conventional Commits 1.0.0, including type/scope/description format, optional body, trailer-style footers, and explicit BREAKING CHANGE signaling. Use when users ask to draft commit messages, commit current changes, rewrite a commit message into conventional format, or enforce conventional commit standards in a repo.
Resources
3Install
npx skillscat add ragnarok22/agent-skills/write-conventional-commit Install via the SkillsCat registry.
We need to produce a 2-3 sentence plain-text summary, objective, factual, no marketing language, no superlatives, no calls to action. No bullet points, no headings, no markdown. Max 60 words. Must be only the summary text. We need to describe skill: creates Git commit messages conforming to Conventional Commits 1.0.0, includes type/scope/description, optional body, trailer footers, explicit BREAKING CHANGE signaling. Use when users ask to draft commit messages, commit current changes, rewrite a commit message into conventional format, or enforce conventional commit standards in a repo.
Write Conventional Commit
Generate and apply Conventional Commits that follow the 1.0.0 specification.
Workflow
Step 1: Inspect commit scope
Run from repository root:
git status --short
git diff --staged --name-only
git diff --name-onlyUse staged changes when available. If nothing is staged and the user asked to commit now, stage intentionally relevant files first and state what was staged.
Step 2: Classify intent into commit type
Pick the best type from change intent, not from file extension.
Common types:
feat: add a user-facing featurefix: fix a bugrefactor: code change without new feature or bug fixperf: improve performancedocs: documentation onlytest: add/update testsbuild: build/dependency toolingci: CI/CD configurationchore: maintenance that does not fit aboverevert: revert a previous commit
If uncertain between feat and fix, prefer:
fixwhen correcting broken behaviorfeatwhen adding new behavior
Step 3: Choose optional scope
Scope is optional and should be short and stable.
Prefer one of:
- top-level package/app (
api,billing,auth) - subsystem (
migrations,deps,release) - user-visible surface (
checkout,search)
Avoid broad scopes like misc.
Step 4: Detect breaking changes
Mark breaking changes when diff indicates incompatible API/contract behavior.
Signals include:
- removed/renamed public endpoints, fields, events, CLI flags
- required inputs changed incompatibly
- output schema changed incompatibly
When breaking:
- Add
!after type or type+scope (feat!:orfeat(api)!:) - Add footer:
BREAKING CHANGE: <what changed and how to migrate>
Use both when possible for clarity.
Step 5: Compose message in spec format
Use this structure exactly:
<type>[optional scope][!]: <description>
[optional body]
[optional footer(s)]Formatting rules:
- Header type must be lowercase noun.
- Put a colon and single space after header prefix.
- Keep description concise and specific.
- Put one blank line between header and body.
- Put one blank line between body and footers.
- Footer tokens follow git trailer style (
Token: value), except references may useToken #value. - Use
BREAKING CHANGE:as the canonical breaking footer token.
Step 6: Create commit (when requested)
If user wants the commit executed, run non-interactively:
git commit -m "<header>" -m "<body>" -m "<footer1>" -m "<footer2>"Only include -m blocks that are needed.
For multiline body/footer with precise formatting, use:
git commit -F /tmp/commit-msg.txtThen report:
- final commit header
- commit hash
- whether breaking change was marked
Quality checks
Before finalizing, verify:
- Header matches
<type>[scope][!]: description - Type reflects intent correctly
- Scope is helpful or omitted
- Breaking changes are explicitly marked when applicable
- Body explains why when context is not obvious
- Footers are valid trailers and references are accurate
Output behavior
When user asks only for message suggestions, provide 1 recommended message and up to 2 alternatives.
When user asks to commit directly, proceed with staging/commit commands and then return commit result.
Reference
Read references/conventional-commits-1.0.0.md for the normative checklist and examples.
Install
npx skillscat add ragnarok22/agent-skills/write-conventional-commit Install via the SkillsCat registry.