Skip to main content
skill CX Codex

git-commit-workflow — Claude Code skill: commits and setup

The git-commit-workflow Claude Code skill defines commit-message and staging rules. It helps split related edits into focused commits and review staged changes.

MIT 161 installs ★ 60 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add laurigates/claude-plugins --skill git-commit-workflow -a claude-code
Open on GitHub

What git-commit-workflow does

git-commit-workflow runs with Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It uses the type(scope): description form, makes the scope mandatory, and covers types such as feat, fix, docs, refactor, test, chore, perf, and ci.

The skill recommends grouping related edits, staging files by explicit path, then reviewing git status and git diff --cached. Its context script, commit-context.sh, reports branch details, staged files, diff statistics, recent commit style, and pre-commit configuration status.

This is a reference skill, not a commit executor. It never creates the commit. For bulk edits, check git status --porcelain and run /git:coworker-check first so staged files from another session are not swept into the wrong change.

What it helps with

  • write a message in type(scope): subject format
  • split related edits into focused commits
  • stage files by explicit path
  • review the cached diff before committing
  • link a commit with Fixes #N or Refs #N

Example prompts for the agent

  • Write a conventional commit message for the current changes using type(scope): subject.
  • Split these edits into focused commits and stage each file by its explicit path.
  • Check git status --porcelain and gather context with commit-context.sh before drafting the message.

How to install git-commit-workflow

1Skills CLI (Vercel)

npx skills add laurigates/claude-plugins --skill git-commit-workflow -a claude-code

2Manually: put the files in place

~/.claude/skills/git-commit-workflow/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/git-commit-workflow/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about git-commit-workflow

How do I install git-commit-workflow in Claude Code?

Run npx skills add laurigates/claude-plugins --skill git-commit-workflow -a claude-code, then use ~/.claude/skills/git-commit-workflow/SKILL.md.

What does git-commit-workflow do?

It guides conventional commit messages with a required scope, logical change grouping, and explicit staging review. The skill does not create commits.

Which platforms support git-commit-workflow?

It supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

Source text

SKILL.md · MIT
---
created: 2025-12-16
modified: 2026-11-14
reviewed: 2026-05-14
name: git-commit-workflow
description: "Commit-message and staging conventions: type(scope): subject, logical grouping, explicit-path staging. Reference only, makes no commit. Use when deciding how to word a message or split changes."
user-invocable: false
allowed-tools: Bash(bash ${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh *), Bash(git status *), Bash(git add *), Bash(git diff *), Bash(git commit *), Bash(git log *), Bash(git worktree add *), Bash(gh issue list *), Read
---

# Git Commit Workflow

## When to Use This Skill

| Use this skill when... | Use the alternative when... |
|---|---|
| Designing the conventional-commit message and staging conventions for a repo | Use `git-commit` to actually create a commit (handles pre-commit hooks, issue detection) |
| Reviewing how to group changes logically into focused commits | Use `git-commit-trailers` for `BREAKING CHANGE` / `Co-authored-by` trailer rules |
| Discussing humble, fact-based commit communication style | Use `github-issue-autodetect` to add `Fixes #N` / `Closes #N` links to messages |
| Authoring `feat(scope): subject` rules for your codebase | Use `github-pr-title` to apply the same conventional format to PR titles |

Expert guidance for commit message conventions, staging practices, and commit best practices using conventional commits and explicit staging workflows.

For detailed examples, advanced patterns, and best practices, see [REFERENCE.md](REFERENCE.md).

## Preconditions

Before staging any files — especially for bulk-edit / commit-loop workflows that touch many subdirectories — verify the working tree is yours alone:

| Check | Why | How |
|-------|-----|-----|
| Coworker check | Another Claude session in the same checkout may have already pre-staged files (`git commit -a` retry, abandoned staging) that your loop would sweep into the wrong commit. **Run this up front, not opportunistically.** | `SlashCommand` → `/git:coworker-check` |
| Working tree scoped | Confirm `git status --porcelain` shows only your edits | `git status --porcelain` |

If `/git:coworker-check` returns anything other than `clear`, stop and either move to a fresh worktree under `<repo>/.claude/worktrees/<task>` (`EnterWorktree`, or `git worktree add .claude/worktrees/<task>`) or ask the user before proceeding. See `.claude/rules/agent-coworker-detection.md` for the seven detection signals.

## Core Expertise

- **Conventional Commits**: Standardized format for automation and clarity
- **Explicit Staging**: Always stage files individually with clear visibility
- **Logical Grouping**: Group related changes into focused commits
- **Communication Style**: Humble, factual, concise commit messages
- **Pre-commit Integration**: Run checks before committing

**Note:** Commits are made on main branch and pushed to remote feature branches for PRs. See **git-branch-pr-workflow** skill for the main-branch development pattern.

## Conventional Commit Format

### Standard Format

```
type(scope): description

[optional body]

[optional footer(s)]
```

**The scope is required.** Write `type(scope): …` — `docs(readme): update install steps`, never a bare `docs: update install steps`. The Conventional Commits spec lets you omit the scope; this house convention does not (`.claude/rules/conventional-commits.md`). Take it from the component or plugin the change touches.

For footer/trailer patterns (Co-authored-by, BREAKING CHANGE, Release-As), see **git-commit-trailers** skill.

### Commit Types

- **feat**: New feature for the user
- **fix**: Bug fix for the user
- **docs**: Documentation changes
- **style**: Formatting, missing semicolons, etc (no code change)
- **refactor**: Code restructuring without changing behavior
- **test**: Adding or updating tests
- **chore**: Maintenance tasks, dependency updates, linter fixes
- **perf**: Performance improvements
- **ci**: CI/CD changes

### Examples

```bash
# Feature
git commit -m "feat(auth): implement OAuth2 integration"

# Bug fix with body
git commit -m "fix(api): resolve null pointer in user service

Fixed race condition where user object could be null during
concurrent authentication requests."

# Breaking change
git commit -m "feat(api)!: migrate to GraphQL endpoints

BREAKING CHANGE: REST endpoints removed in favor of GraphQL.
See migration guide at docs/migration.md"
```

### Commit Message Best Practices

**DO:**
- Use imperative mood ("add feature" not "added feature")
- Keep first line under 72 characters
- Be concise and factual
- **ALWAYS reference related issues** - every commit should link to relevant issues
- Use GitHub closing keywords: `Fixes #123`, `Closes #456`, `Resolves #789`
- Use `Refs #N` for related issues that should not auto-close
- Use lowercase for type and scope
- Be humble and modest

**DON'T:**
- Use past tense ("added" or "fixed")
- Include unnecessary details in subject line
- Use vague descriptions ("update stuff", "fix bug")
- Omit issue references - always link commits to their context
- Use closing keywords (`Fixes`) when you only mean to reference (`Refs`)

## Pre-Commit Context Gathering (Recommended)

Before committing, gather all context in one command:

```bash
# Basic context: status, staged files, diff stats, recent log
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"

# With issue matching: also fetches open GitHub issues for auto-linking
bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues
```

The script outputs: branch info, staged/unstaged status, diff stats, detected scopes, recent commit style, pre-commit config status, and optionally open issues. Use this output to compose the commit message. See [scripts/commit-context.sh](scripts/commit-context.sh) for details.

## Explicit Staging Workflow

### Always Stage Files Individually

```bash
# Show current status
git status --porcelain

# Stage files one by one for visibility
git add src/auth/login.ts
git add src/auth/oauth.ts
git status  # Verify what's staged

# Show what will be committed
git diff --cached --stat
git diff --cached  # Review actual changes

# Commit with conventional message
git commit -m "feat(auth): add OAuth2 support"
```

## Bulk-edit / per-plugin commit loops

When a single change touches many subdirectories (per-plugin, per-package, per-doc) and each needs its own scoped commit for release-please, write a one-shot script rather than chaining commands inline.

Why inline loops fail, the canonical one-shot script recipe, and failure recovery: [REFERENCE.md](REFERENCE.md#bulk-edit--per-plugin-commit-loops).

**Compose a multi-line message with a HEREDOC, not by slurping a temp file.**

```bash
git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 support

Implements token refresh and secure storage.

Fixes #123
EOF
)"
```

Passing the message **by path** is equally accepted — `git commit -F <file>` /
`--file=<file>` is git's analogue of `gh --body-file`, and the
`bash-antipatterns` hook exempts it (#2462):

```bash
git commit -F /tmp/commit-msg.txt
```

What the hook still nudges away from is the roundabout middle ground: writing a
temp file and then slurping it back through `-m "$(cat /tmp/commit-msg.txt)"`.
Either compose inline with a heredoc, or pass the file by path.

## Communication Style

### Humble, Fact-Based Messages

```bash
# Good: Concise, factual, modest
git commit -m "fix(auth): handle edge case in token refresh"

git commit -m "feat(api): add pagination support

Implements cursor-based pagination for list endpoints.
Includes tests and documentation."
```

Focus on facts: **What changed**, **Why it changed** (if non-obvious), and **Impact** (breaking changes).

## Issue Reference Summary

| Scenario | Pattern | Example |
|----------|---------|---------|
| Bug fix resolving issue | `Fixes #N` | `Fixes #123` |
| Feature completing issue | `Closes #N` | `Closes #456` |
| Related but not completing | `Refs #N` | `Refs #789` |
| Cross-repository | `Fixes owner/repo#N` | `Fixes org/lib#42` |
| Multiple issues | Repeat keyword | `Fixes #1, fixes #2` |

## Best Practices

### Commit Frequency

- **Commit early and often**: Small, focused commits
- **One logical change per commit**: Easier to review and revert
- **Keep commits atomic**: Each commit should be a complete, working state

### Commit Message Length

```bash
# Subject line: <= 72 characters
feat(auth): add OAuth2 support

# Body: <= 72 characters per line (wrap)
# Use blank line between subject and body
```

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Pre-commit context | `bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh"` |
| Context + issues | `bash "${CLAUDE_PLUGIN_ROOT}/skills/git-commit-workflow/scripts/commit-context.sh" --with-issues` |
| Quick status | `git status --porcelain` |
| Staged diff stats | `git diff --cached --stat` |
| Recent commit style | `git log --format='%s' -5` |
| Open issues for linking | `gh issue list --state open --json number,title --limit 30` |

© laurigates · MIT · laurigates/claude-plugins

Similar skills

All skills for Git and GitHub →

From the same set27

The whole set →
jq-json-processing jq-json-processing — a skill for parsing, filtering and transforming JSON with jq. Extracts fields, filters arrays, reshapes objects and validates syntax. CX Codex +1 245installs python-development python-development gives your agent Python 3.10+ idioms: type hints, pattern matching, asyncio. Handy for library code and refactors. CX Codex +1 192installs generate-image The generate-image skill generates images from text prompts using Google's Gemini 3 Pro Image model on Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 177installs justfile-expert justfile-expert is a Claude Code skill for designing Just recipes, parameters, dependencies, and modules. It supports adding project commands and task automation. CX Codex +1 162installs binary-analysis binary-analysis guides your coding agent in inspecting unknown binaries, running hex dumps, and extracting embedded artifacts. CX Codex +1 146installs shell-expert shell-expert is a Claude Code skill for writing Bash, zsh, and POSIX scripts and composing command-line automation. It activates for shell pipelines and portable scripting tasks. CX Codex +1 141installs rust-development A Rust development skill covering Cargo, ownership, async code, and Tokio. It fits coding tasks that mention Rust or its core tooling. CX Codex +1 108installs clippy-advanced clippy-advanced guides Clippy setup for Rust projects: custom lints, clippy.toml thresholds, suppression rules, and CI check commands. CX Codex +1 107installs

Project sponsors

Companies that keep this analytics open