Agent Skills: commit

Workflow

1. Preflight
   • Use git status --short to check repository state (staged, unstaged, untracked files)
   • If no changes exist, report and stop
2. Analyze changes
   • Use git diff <base> to view tracked working-tree changes compared to the base branch; inspect untracked files identified during preflight separately
   • Categorize changes by type (feature, fix, refactor, docs, test, chore, etc.)
3. Propose staging
   • If there are unstaged changes, ask the user which files to stage
   • List each file with its change type:

     Files to stage:
     - [M] src/file1.ts (modified)
     - [A] src/file2.ts (new file)
     - [D] src/file3.ts (deleted)
     

4. Draft commit message
   • Use Conventional Commits format (see below)
   • Include body if changes are complex (wrapped at 72 chars)
   • Include a footer for breaking changes when needed
   • Always use lowercase unless proper nouns
5. Ask for approval: Present the draft and ask "Do you approve this commit? (yes/no/edit)"
6. Commit (only after explicit approval)
   • Use tool__git--stage-files with the list of files
   • Use tool__git--commit with the commit message
   • Handle pre-commit hooks (see below)
   • After successful commit, offer to push (requires explicit approval)
   • Report the commit SHA and summary

Conventional Commits Format

<type>(<scope>): <description>

[optional body wrapped at 72 chars]

[optional footer(s)]

Use standard types: feat, fix, docs, style, refactor, perf, test, chore.

Breaking changes — append ! after type/scope:

feat(api)!: change response format from XML to JSON

BREAKING CHANGE: API responses are now JSON. Clients using XML
parsing must migrate to JSON parsing.

Example: Full Commit Workflow

> git status --short
 M src/auth.ts
 M src/auth.test.ts
?? src/middleware/rateLimit.ts

The first status column is the index (staged) state and the second is the
working-tree state. The ` M` entries each begin with one space before `M`,
indicating an unstaged modification; `??` has no leading space and denotes an
untracked file.

> git diff main
  src/auth.ts: Added JWT token refresh logic
  src/auth.test.ts: Added tests for token refresh

> git diff --no-index /dev/null src/middleware/rateLimit.ts
  src/middleware/rateLimit.ts: New rate limiting middleware

  `git diff --no-index` exits with status 1 when it detects differences. If
  the command's exit status is surfaced, treat status 1 as expected
  detected-diff behavior, not an inspection failure.

> Propose staging:
  Files to stage:
  - [M] src/auth.ts (modified)
  - [M] src/auth.test.ts (modified)
  - [A] src/middleware/rateLimit.ts (new file)

  Suggested split into 2 commits:
  1. feat(auth): add JWT token refresh logic
     - src/auth.ts, src/auth.test.ts
  2. feat(middleware): add rate limiting middleware
     - src/middleware/rateLimit.ts

  Do you approve this commit plan? (yes/no/edit)

> User: yes

> tool__git--stage-files ["src/auth.ts", "src/auth.test.ts"]
> tool__git--commit "feat(auth): add JWT token refresh logic"
  ✓ Commit abc1234

> tool__git--stage-files ["src/middleware/rateLimit.ts"]
> tool__git--commit "feat(middleware): add rate limiting middleware"
  ✓ Commit def5678

  Would you like to push? (yes/no)

Pre-Commit Hook Handling

This is a common failure mode — follow these steps exactly:

1. First attempt: Make initial commit
2. If failed with modified files (hook auto-formatted code): Stage the modified files and retry once
3. If retry still fails: Report the hook error to user — do NOT keep retrying

Constraints

• NEVER create empty commits
• NEVER commit without explicit user approval
• NEVER push without explicit user approval
• NEVER use --no-verify to skip pre-commit hooks
• NEVER amend commits that have been pushed to remote