Conventional Commit Writer
A SKILL.md that makes your agent write clean conventional commits, every time.
An agent skill that standardizes commit messages to the Conventional Commits format: correct type prefixes, imperative subjects under 72 characters, and bodies that explain why rather than what. Drop it into .claude/skills/ and your coding agent commits like your best engineer.
SKILL.md
--- name: commit-message description: Write commit messages in Conventional Commits format. Use whenever creating a git commit. --- # Conventional Commit Writer When writing any commit message, follow these rules exactly. ## Format ``` <type>(<scope>): <subject> <body> ``` ## Types - `feat` — new user-facing capability - `fix` — bug fix - `refactor` — code change that neither fixes a bug nor adds a feature - `perf` — performance improvement - `test` — adding or correcting tests - `docs` — documentation only - `chore` — build process, dependencies, tooling ## Subject rules - Imperative mood: "add", not "added" or "adds" - Max 72 characters, no trailing period - Scope is the affected module/area in lowercase: `feat(auth):`, `fix(billing):` - Breaking changes: append `!` after scope — `feat(api)!:` — and explain in body ## Body rules - Explain WHY the change was made, not what changed (the diff shows what) - Wrap at 72 characters - Reference issues at the end: `Fixes #123` - Omit the body only for trivial changes where the subject says everything ## Before committing 1. Run `git diff --staged` and verify the message describes ALL staged changes 2. If the diff contains unrelated changes, suggest splitting into separate commits 3. Never include internal tool names, model names, or session IDs in messages
How to use
- 1Save the content as .claude/skills/commit-message/SKILL.md in your repo (or ~/.claude/skills/ for all projects).
- 2Your agent picks it up automatically whenever it commits — no invocation needed.
- 3Adjust the types list to your team's convention (some teams add build, ci, style).
- 4Pair with a CI commit-lint rule so human commits follow the same format.
Examples
Agent commit after a bug fix
Input
Agent fixed a timezone bug in the dashboard date filter and was asked to commit.
Output
fix(dashboard): use UTC day boundaries in date filter The filter computed day boundaries in server-local time, so users in UTC+ timezones saw the previous day's data after midnight. Fixes #482
Pro tips
- Add your issue-tracker URL pattern to the body rules so references become clickable links.
Frequently asked questions
What are agent skills and how do they work?+
Skills are markdown instruction files (SKILL.md) that coding agents like Claude Code load when relevant. The frontmatter description tells the agent when to apply it; the body contains the actual instructions.
Does this work with agents other than Claude Code?+
The SKILL.md format is native to Claude Code, but the body works as a system-prompt snippet or rules file (e.g. .cursorrules) for any coding assistant.