Committing Changes

Write effective git commit messages following Conventional Commits standard with selective staging, atomic commits, and domain-specific type conventions.

1. Run project validation first: Check CLAUDE.md for just check, pnpm run check, etc.
2. Review changes: git status, git diff
3. Classify changes by concern — group by type+scope, split if multiple groups
4. Stage specific files for ONE concern: git add path/to/file.ts (never git add .)
5. Write message: type(scope): description (imperative, under 50 chars)
6. Commit, then repeat from step 4 for remaining concerns

A successful commit has:

• Concerns classified before staging (type+scope grouping applied)
• One concern per commit (split when types or scopes differ)
• Selective staging (specific files, not git add .)
• Conventional Commits format (type, optional scope, imperative description)
• No debug code or unintended files
• Clean diff review confirms expected changes only

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

This skill does NOT:

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

Before creating any commit, gather context:

| Source | Gather | | ---------------- | ------------------------------------------------------- | | git status | Staged, unstaged, untracked files | | git diff | Actual changes to commit | | git log | Recent commit style for consistency | | Project docs | Custom commit types (CLAUDE.md, CONTRIBUTING.md) | | Conversation | User's intent - what story/issue does this commit solve |

When invoked from a reviewing skill (e.g., reviewing-python, reviewing-typescript):

This skill may be referenced during the commit phase of a code review. In that context:

1. Committing is the seal of approval — Only commit after verdict is APPROVED
2. Scope to work item — Stage only files from the approved work item:

• Implementation files
• Co-located tests (in spx/.../tests/)

1. Include work item reference — Add Refs: {capability}/{feature}/{story} in footer
2. Verify tests pass — All tests must pass before committing

The reviewing skill provides the specific file list and work item context. This skill provides the commit protocol mechanics.

MANDATORY: Analyze before staging. Never stage everything then ask about splitting.

After gathering context (git status, git diff), classify every changed and untracked file by concern before touching git add. A concern is one logical purpose that gets one commit type and one scope.

Classification procedure:

1. List every changed/untracked file.
2. Assign each file a commit type (spec, feat, fix, refactor, docs, etc.).
3. Assign each file a scope (module, plugin, component).
4. Group files that share the same type AND scope — each group is one commit.

Split signals — if ANY of these are true, you MUST split into multiple commits:

• Files need different commit types (e.g., spec for a design doc + feat for implementation)
• Files belong to different scopes (e.g., methodology/ spec + plugins/ code)
• Changes serve different purposes even within the same directory
• A design/spec document and its implementation are both present

Commit ordering:

When splitting, commit in dependency order:

1. Specs and design documents first (they define what follows)
2. Infrastructure and enablers second
3. Implementation last
4. Tests alongside whatever they test

Example:

Changed files:
  methodology/skills/skill-structure.md   → spec(spec-tree)
  plugins/spec-tree/**                     → feat(spec-tree)

→ Two commits:
  1. spec(spec-tree): define methodology
  2. feat(spec-tree): add plugin implementation

Never ask the user whether to split. Apply the classification procedure. If the result is multiple groups, commit them separately. Separation of concerns is not a preference — it is a requirement.

Step 0: Run Project-Specific Validation (BEFORE Staging)

Before staging any files, check CLAUDE.md for project-specific validation commands and run them. This prevents having to re-stage after auto-fixes.

# Check CLAUDE.md for commands like:
just check        # Justfile task runner
just validate
pnpm run check    # pnpm scripts
pnpm run validate
npm run check     # npm scripts
make check        # Makefile targets
make lint

Why before staging? Many project commands (formatters, linters with auto-fix) modify files. Running them after staging means you need to re-stage the fixed files. Run validation first, then stage.

Step 1: Selective Staging

# 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

git 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

[(scope)]: 

[optional body]

[optional footer(s)]

Subject Line (Required)

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

feat(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

Standard Types

| Type | Purpose | SemVer | | ------------ | ------------------------------------- | ------ | | spec | Specification only | PATCH | | test | Add/modify tests | PATCH | | feat | Implementation of new functionality | MINOR | | refactor | Code restructure (no behavior change) | PATCH | | fix | Bug fix | PATCH | | docs | Documentation only | PATCH | | style | Formatting (no logic change) | PATCH | | perf | Performance improvement | PATCH | | ci | CI/CD changes | PATCH | | build | Build system, dependencies | PATCH | | revert | Revert previous commit | varies |

Domain-Specific Types

Projects may define custom types:

| Type | Domain | Purpose | | ------------ | ---------------- | ------------------------------ | | draft | Writing projects | New or revised content | | research | Academic/books | Research notes | | meta | Process docs | Process/workflow documentation |

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

IMPORTANT: NEVER USE chore:. Everything has purpose; use specific type instead

Mark breaking changes with:

1. Exclamation suffix: "feat!: remove deprecated API"
2. Footer:

```text feat: change authentication flow

BREAKING CHANGE: JWT tokens now expire in 1 hour instead of 24 ```

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

When crafting the commit message description, read ${SKILL_DIR}/references/message-crafting.md for:

• Three description principles (no state words, content over container, don't repeat the prefix)
• Good and bad commit message examples with explanations

Is 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)

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

# 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

## Source & license

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

- **Author:** [outcomeeng](https://github.com/outcomeeng)
- **Source:** [outcomeeng/claude](https://github.com/outcomeeng/claude)
- **License:** MIT

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