version: "1.0.2" created: 2026-01-21 modified: 2026-09-23 reviewed: 2026-09-02 name: git-commit description: Create commits with conventional messages and issue references. Use when user says "commit", "save changes", or "stage and commit". Local commits only — see git-push for remote. user-invocable: false allowed-tools: Bash(git status ), Bash(git diff ), Bash(git log ), Bash(git add ), Bash(git commit ), Bash(git restore ), Bash(pre-commit ), Bash(gh issue ), Read, Grep, Glob, TodoWrite

Git Commit

When to Use This Skill

Create local commits with proper conventional messages and issue references.

When to Use

Trigger phrases:

• "commit" / "commit locally" / "commit these changes"
• "save changes" / "save my work"
• "stage and commit"
• "create a commit"

Context signals:

• User has made code changes
• git status shows modified/untracked files
• No mention of "push", "remote", or "PR"

Workflow

1. Assess State

# Check branch and status
git branch --show-current
git status --porcelain=v2 --branch
 
# View changes
git diff --stat                    # Unstaged
git diff --cached --stat           # Already staged

2. Stage Changes

Explicit staging (preferred):

git add src/feature.ts
git add tests/feature.test.ts
git status --porcelain              # Verify

Modified tracked files:

git add -u                          # Stage all modified tracked files

3. Run Pre-commit Hooks

If .pre-commit-config.yaml exists:

pre-commit run --all-files
 
# If hooks modify files (formatters), re-stage:
git add -u
pre-commit run --all-files          # Should pass now

4. Detect Related Issues

Scan open issues for matches (see github-issue-autodetect skill):

gh issue list --state open --json number,title,labels --limit 30

Match staged changes to issues by:

• File paths mentioned in issue body (high confidence)
• Error messages or function names (high confidence)
• Directory/component matches (medium confidence)

5. Create Commit

IMPORTANT: Use HEREDOC directly in the git commit command.

git commit -m "$(cat <<'EOF'
type(scope): concise description
 
Optional body explaining the change.
 
Fixes #123
Refs #456
 
Co-Authored-By: Claude <model name> <noreply@anthropic.com>
EOF
)"

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.

Use the exact Co-Authored-By line the harness provides for the current session — do not copy a model name from this example.

Inside a quoted heredoc (`<<'EOF'`), backticks, `$`, and `\` are already literal — never backslash-escape them. A reflexive \ produces a literal backslash in the commit message that survives into git log and needs an --amend` to clean up.

For trailer conventions (Co-authored-by, Signed-off-by, BREAKING CHANGE, Release-As), see git-commit-trailers skill.

Conventional Commit Types

See Conventional Commits Standards for complete reference.

Issue References

Output

On success, report:

Created commit: abc1234
Message: feat(auth): add OAuth2 support
 
Fixes #123
Refs #456
 
Ready for: push to remote, create PR, or continue working

Composability

This skill creates local commits only. For remote operations:

• git-push skill: Push commits to remote
• git-pr skill: Create pull request

Common compositions:

• "commit" → git-commit only
• "commit and push" → git-commit → git-push
• "commit and create PR" → git-commit → git-push → git-pr

Before building further on an existing PR branch (an additional in-session request continuing earlier work), invoke /git:pr-sync-check first. If the verdict is anything other than in_sync / no_pr / no_remote — e.g. pr_merged or behind — stop and reconcile (branch off the updated default, or git pull --rebase) before committing. See .claude/rules/pr-branch-sync.md.

Error Handling

No changes to commit:

Nothing to commit. Working tree clean.

Pre-commit hook fails:

# Fix the issue, then:
git add -u
pre-commit run --all-files
# Then commit

Merge conflict markers:

Cannot commit: unresolved merge conflicts in <file>

Best Practices

1. One logical change per commit - Easier to review and revert
2. Always reference issues - Maintains traceability
3. Run pre-commit before staging - Avoids re-staging formatter changes
4. Keep subject under 72 chars - Better display in git log
5. Use imperative mood - "Add feature" not "Added feature"
6. Add appropriate trailers - Co-authored-by for pair/AI work, Signed-off-by for DCO projects, BREAKING CHANGE for major versions (see git-commit-trailers)