commit

name	commit
description	Format and create commits following Conventional Commits with project-specific scopes
version	2.0.0
compat	claude-code, codex, cursor, openclaw
fill	scopes, co-authored-by

Skill: commit

Purpose

Format and create a commit following Conventional Commits with this project's conventions. Always use this skill before pushing — never commit with improvised messages.

Conventional Commits enables automated CHANGELOG generation, semantic versioning, and a readable history.

Preconditions

• Working on a feature branch (never commit directly to main or the epic branch)
• Changes to be included are ready for staging

Invocation

/commit
/commit "brief description of changes"

---

Steps

1. Review what's to be committed

git status
git diff --staged   # if things are already staged
git diff            # if nothing is staged yet

If nothing is staged, git add the relevant files first. Do not use git add . blindly — review what's being included.

2. Identify the commit type

Choose the type that best describes the main change:

Type	When to use
feat	New functionality visible to the user or system
fix	Bug fix or incorrect behavior correction
refactor	Code reorganization without observable behavior change
test	Adding or modifying tests (no production changes)
docs	Documentation, comments, or .md files only
chore	Setup, configuration, dependencies, build scripts
perf	Performance improvement without behavior change
ci	CI/CD pipeline changes

If the commit mixes types, split into two separate commits. If splitting isn't reasonable, use the dominant type.

3. Determine the scope

The scope indicates which area of the system changed. It must be consistent across commits within the same epic.

{{FILL: List valid scopes for this project.

Convention: scopes are system layers (auth, db, api) or business domains (catalog, payments, admin).

Examples:

• Web project: auth, catalog, cart, payments, admin, db, notifications
• Mobile app: auth, feed, profile, messaging, db
• Backend/API: auth, users, orders, payments, db, integrations
• Library: core, utils, types, hooks, components

If the change spans multiple scopes, omit the scope (use type only). }}

If the change spans multiple scopes, omit the scope (use type only).

4. Write the message

Required format:

<type>(<scope>): <description in lowercase, no period>

[optional body — one or more lines explaining the "why", not the "what"]
[the "what" is already in the diff]

{{FILL: If this project uses commits from an AI agent, optionally add: Co-Authored-By: [Agent Name] <noreply@[domain].com> Examples: Claude AI <[e-mail]>, GitHub Copilot <[e-mail]> If not applicable, omit this line. }}

Rules for the description:

• Lowercase, no period at the end
• Imperative present tense: "add feature" not "added feature" or "adds feature"
• Maximum 72 characters on the first line
• Body is optional but valuable when the decision isn't obvious

5. Create the commit

git commit -m "feat(scope): brief description

Optional explanation of why. The diff already shows what."

If this project uses Co-Authored-By (see {{FILL}} in step 4), add it at the end of the message.

Examples of well-formed messages:

feat(auth): add email verification on signup

Email verification was missing — users could sign up with invalid emails.
Added resend logic with 60s cooldown.

fix(api): return 404 when resource not found instead of empty array

refactor(core): extract validation logic to separate module

chore: add pre-commit hook for lint-staged

---

Validation

The commit is correct if:

• git log --oneline -1 shows the message with the correct format
• git show --stat shows exactly the expected files (nothing extra)
• Follows Conventional Commits: <type>(<scope>): description

How this skill enables automation

A well-formed commit history enables:

• Automated CHANGELOG: extract all feat: from a release
• Automated semantic versioning: count feat: (minor bump) vs fix: (patch) vs breaking changes (major)
• Searchable git log: filter by scope or type
• Clean history: the next developer can understand what happened and why

Bad examples — and why

fix: stuff                          ← doesn't describe what was fixed
WIP                                 ← not a finished commit
feat: Add new feature.              ← uppercase + period
update files                        ← no type, no scope, no useful description
BREAKING CHANGE: everything        ← breaking changes go in the body, not the subject

Common failure modes

Committing unrelated files. Always review git diff --staged before committing. A mixed commit makes history unreadable and rollback difficult.

Using "update" as a type. There is no update type. If something is updated, it's feat, fix, or chore depending on what changed.

Body describes the what, not the why. The diff already shows the what. The body is valuable when it explains the reason behind the decision — especially if it's not obvious to someone reading the history six months later.

Omitting Co-Authored-By when the project requires it. If the project uses the agent authorship convention (defined in the {{FILL}} of step 4), including it maintains traceability that an agent wrote the code — useful for audit and history.