Conventional Commits

This skill inspects your staged changes and produces a commit message that follows the Conventional Commits specification. It picks the right type and scope, writes a concise imperative subject, adds a body explaining the why when the change is non-trivial, and flags breaking changes correctly — so your history stays readable and your tooling (changelogs, semantic-release) keeps working.

When to use this skill

• You have changes staged with git add and want to commit them.
• You want a consistent, spec-compliant message instead of free-form text.
• You are unsure which type (feat, fix, chore, …) fits the change.
• Your repo uses semantic versioning or automated changelog generation that depends on commit conventions.

> [!NOTE] > This skill only reads and commits what is already staged. Stage the exact hunks you want first (git add -p). It will not stage files for you.

Instructions

1. Read the staged diff to understand what actually changed:

``bash git diff --cached `` If nothing is returned, stop and tell the user there are no staged changes to commit.

1. Check the staged file list for scope hints (directory or package names):

``bash git diff --cached --name-only ``

1. Choose the type from the staged changes:

• feat — a new user-facing capability
• fix — a bug fix
• docs — documentation only
• style — formatting, no logic change
• refactor — code change that neither fixes a bug nor adds a feature
• perf — performance improvement
• test — adding or correcting tests
• build / ci — build system or pipeline changes
• chore — maintenance, deps, tooling

1. Derive an optional scope in parentheses from the affected area (e.g. auth, api, parser). Omit it if the change is broad.
2. Write the subject line: type(scope): summary

• Imperative mood ("add", not "added" or "adds").
• No trailing period; aim for 50 characters, hard limit 72.

1. If the change is non-trivial, add a blank line then a body explaining the motivation and any context the diff alone does not convey. Wrap at ~72 columns.
2. If the change breaks compatibility, mark it: append ! after the type/scope (e.g. feat(api)!:) and add a BREAKING CHANGE: footer describing the migration.
3. Add footers for issue references when relevant (e.g. Refs: #123, Closes: #456).
4. Present the proposed message to the user for confirmation, then commit:

``bash git commit -m "feat(parser): add support for nested arrays" \ -m "Handles arbitrarily deep nesting by recursing on bracket pairs." \ -m "Closes: #128" ``

Examples

Suppose git diff --cached --name-only shows src/auth/session.ts and the diff replaces a 1-hour token TTL with a configurable value, removing the old constant.

feat(auth)!: make session token TTL configurable

Replace the hardcoded 1-hour TTL with SESSION_TTL_SECONDS so deployments
can tune session lifetime without a rebuild. Falls back to 3600 when the
variable is unset.

BREAKING CHANGE: the SESSION_MAX_AGE constant has been removed. Set the
SESSION_TTL_SECONDS environment variable instead.

Closes: #214

Commit it:

git commit \
  -m "feat(auth)!: make session token TTL configurable" \
  -m "Replace the hardcoded 1-hour TTL with SESSION_TTL_SECONDS so deployments can tune session lifetime without a rebuild. Falls back to 3600 when the variable is unset." \
  -m "BREAKING CHANGE: the SESSION_MAX_AGE constant has been removed. Set the SESSION_TTL_SECONDS environment variable instead." \
  -m "Closes: #214"

Source & license

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

• Author: imtiazrayhan
• Source: imtiazrayhan/agentscamp-library
• License: MIT
• Homepage: https://agentscamp.com

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