Commit Message

When to use

• User runs git add and asks for a commit message.
• User pastes a diff and asks "what's a good commit message for this".
• User finishes a task and asks the agent to commit (combine with a separate commit tool/skill that actually runs git).

Do not use this skill to write a PR description (longer, audience-different) or a changelog entry (see the documentation skill).

Inputs

• A staged diff (git diff --cached) or an unstaged diff. If none is provided, fetch git status and git diff --cached from the repo.
• Optional: related issue/ticket id, prior commit for context, the branch name if it encodes intent.

Outputs

A commit message with:

• Subject line: [optional scope][!]: , , Co-authored-by: ...`.

Tool dependencies

• Bash for git status, git diff --cached, git log -n 20 --oneline (style calibration).
• Read/Grep to glance at touched files when the diff alone is ambiguous.

Procedure

1. Read the diff. If it is empty, ask for the staged changes or run git diff --cached.
2. Calibrate to the repo's style. Run git log -n 20 --pretty=format:'%s'. If the repo already uses Conventional Commits, match exactly (types, scope format, capitalisation). If not, propose Conventional Commits and follow the user's existing conventions where they conflict.
3. Classify the change into one type:

• feat — a user-facing new capability.
• fix — a bug fix observable to users or other systems.
• perf — a change that improves performance without changing behaviour.
• refactor — internal restructuring, no behaviour change.
• docs — documentation only.
• test — tests only.
• build — build system, dependencies, packaging.
• ci — CI/CD configuration.
• chore — maintenance (bumping deps, cleanup) that is neither feat nor fix.
• revert — reverts a previous commit.

1. Pick a scope if the repo uses them. Scope is usually a package, module, or subsystem (auth, api, billing). Omit the scope entirely rather than invent one.
2. Write the subject as an imperative phrase starting lowercase after the colon. "Add", "fix", "rename", never "added" or "adds". Cap at 72 characters; aim for or Closes: #` when linked to an issue.

• BREAKING CHANGE: when the diff removes or alters a public API, wire format, CLI flag, config key, database column, or event shape. Also append ! before the colon in the subject.
• Co-authored-by: when pair programming.

1. Never include implementation trivia the commit hash already captures ("changed 3 files", "added 42 lines"). Instead, state the user-visible or contract-level effect.
2. Check length and wrap. Return the final message in a single fenced block so the user can paste it directly.

Examples

Happy path: feature with a scope and a why

Diff: new /v1/invoices/:id/pdf endpoint that renders with a background worker and streams the result.

feat(invoices): stream rendered PDFs from a background worker

The previous implementation rendered synchronously on the request path,
which starved the HTTP thread pool whenever a large invoice came in
(>200 ms at p95, >5 s at p99). Moving rendering to the existing
BullMQ worker and streaming the signed S3 URL keeps the request path
under 50 ms regardless of invoice size.

The worker uses the same wkhtmltopdf container as the nightly report
job, so no new infrastructure is introduced. Rendering errors surface
as a 502 with a problem+json body (see api-standards).

Refs: #4821

Edge case: breaking change

Diff: renames the name field on the public User JSON to display_name, with a one-release deprecation window.

feat(api)!: rename User.name to User.display_name

Clients consistently conflated `name` (display) with `legal_name`
(KYC). Renaming aligns the API with the internal vocabulary and
with the mobile SDK's existing field.

A compatibility shim emits both keys for clients on API version
()?!?: ` and is <= 72 chars.
- Type is one of the allowed set and matches the diff's intent.
- `!` in the subject iff a `BREAKING CHANGE:` footer is present.
- Body (if any) is separated by one blank line and wrapped at 72 columns.
- Issue references use the repo's convention (`Refs:` vs `#` vs `Closes:`).
- Running `git log --oneline -n 5` after commit shows a message that reads like the rest of the history.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tahirraufkeeyu](https://github.com/tahirraufkeeyu)
- **Source:** [tahirraufkeeyu/software-development-agent-stack--sdas](https://github.com/tahirraufkeeyu/software-development-agent-stack--sdas)
- **License:** MIT

Install and usage instructions live in the source repository linked above.