---

name: committing-changes description: Write git commit messages following Conventional Commits. Use when committing changes or writing commit messages.

Commit Message

Write effective git commits with Conventional Commits standard and pre-commit verification.

What This Skill Does

• Guides selective file staging (never git add .)
• Writes commit messages in Conventional Commits format
• Verifies atomic commit principles
• Adapts commit types to project domain

What This Skill Does NOT Do

• Push commits to remote
• Create pull requests
• Modify git configuration
• Bypass pre-commit hooks

---

Before Creating Any Commit

Gather context:

---

Pre-Commit Verification Protocol

Step 1: Selective Staging

Copy# NEVER do this
git add .

# ALWAYS stage specific files
git add path/to/file1.ts path/to/file2.ts

Rules:

• One logical change per commit
• Review each ?? untracked file consciously
• Exclude experimental/incomplete work
• Use explicit paths, not wildcards

Step 2: Diff Review

Copygit diff --cached           # Review actual changes
git diff --cached --name-only  # Verify file list

Checklist:

• File count matches scope of change
• No surprise files included
• All changes related to single purpose
• No debug code (console.log, print statements, temp comments)

Step 3: Atomic Commit Verification

• Single purpose - does exactly one thing
• Independent - can be reverted without breaking other features
• Complete - includes everything needed for the change to work

Red Flags - DO NOT COMMIT IF

• More than 10 files for a simple fix
• Changes span unrelated modules
• Experimental code mixed with stable fixes
• New unintended files included

---

Commit Message Format

Copy<type>[(scope)]: <description>

[optional body]

[optional footer(s)]

Subject Line (Required)

• Type: Required (see types table)
• Scope: Optional, component/module name
• Description: Imperative mood, 50 chars max, no period

Copyfeat(auth): add OAuth2 token refresh
fix: handle empty response from API
refactor(db): extract query builder module

Body (Optional)

• Wrap at 72 characters
• Explain WHAT and WHY, not HOW
• Blank line between subject and body

Footer (Optional)

• BREAKING CHANGE: description - major version bump
• Refs: #123 or Closes #456 - issue references
• Work item refs: Refs: feature-32/story-27

---

Commit Types

Standard Types

Domain-Specific Types

Projects may define custom types:

Check project's CLAUDE.md or commit-standards.md for custom types.

Avoid

• chore: - Everything has purpose; use specific type instead

---

Breaking Changes

Mark breaking changes with:

1. ! suffix: feat!: remove deprecated API

2. Footer:

   Copyfeat: change authentication flow
   
   BREAKING CHANGE: JWT tokens now expire in 1 hour instead of 24
   

---

Scope Usage

Use Scope When

• Component-specific: feat(auth): add 2FA support
• Module changes: fix(api): handle rate limiting
• Clear subsystem: test(db): add connection pool tests

Omit Scope When

• Single-file change: fix: correct typo in error message
• Cross-cutting: refactor: consolidate error handling
• Obvious context: docs: update installation guide

---

Examples

Good

Copyfeat(parser): add support for nested expressions

Enables users to write complex queries with unlimited nesting depth.
Previously limited to 3 levels.

Refs: #234

Copyfix: prevent crash on empty config file

Return sensible defaults when config is missing or empty
instead of throwing unhandled exception.

Copyrefactor: extract validation logic into separate module

Prepares codebase for unit testing by isolating validation
from business logic.

Bad

Copy# Too vague
fix: bug fixes

# Multiple unrelated changes
feat: add parser and fix tests and update docs

# Contains attribution (NEVER do this)
feat: add export feature (by John)

# Not atomic
refactor: various improvements

---

Quick Decision Tree

CopyIs this a new user feature?           → feat:
Is this fixing a bug?                 → fix:
Is this improving performance?        → perf:
Is this code reorganization?          → refactor:
Is this build/dependencies?           → build:
Is this CI/CD?                        → ci:
Is this documentation?                → docs:
Is this adding/changing tests?        → test:
Is this context/workflow docs?        → ctx: (if project uses it)

---

Critical Rules

1. NO ATTRIBUTION - Never include author names in commit messages
2. IMPERATIVE MOOD - "add feature" not "added feature" or "adds feature"
3. NO PERIOD - Subject line doesn't end with punctuation
4. SELECTIVE STAGING - Never use git add .
5. ATOMIC COMMITS - One logical change per commit

---

Git Commands Reference

Copy# Check what will be committed
git status
git diff --cached
git diff --cached --name-only

# Stage selectively
git add path/to/specific/file.ts

# Commit with multi-line message
git commit -m "$(cat <<'EOF'
feat(scope): subject line here

Body explaining why this change was made.
Wrapped at 72 characters for readability.

Refs: #123
EOF
)"

# View recent commits for style reference
git log --oneline -10