| name | commit |
| description | Create a git commit following the project's commit standards. Triggers on "/commit" or when user asks to commit changes. |
Commit Skill
Commit workflow: review code, list files, get approval, then drive ALL THE WAY to a merged
pull request on origin/main and park the checkout back on main.
Trunk-based development - "done" means merged to main
This repo (like every repo here) does trunk-based development. There are three states of
work and only one counts:
- Committed / pushed to a side branch - still IN PROGRESS. A backup, not a delivery.
- An open pull request - still IN PROGRESS.
- Merged to origin/main - DONE. Tracked, visible to every agent, carries its pull
request record so it can be QA'd or reverted later.
So a commit request is NOT finished at git push. Committing still requires the user's
explicit ask (per CLAUDE.md) - but ONCE the user approves the commit, that authorizes driving
it the rest of the way: push, open a pull request, merge on green, delete the branch, and park
the checkout back on main. "I committed and pushed" is an unfinished job. Merge first, QA
after - main is GitHub, not a public release.
The four supporting rules (see the TRUNK DEVELOPMENT section of the global CLAUDE.md):
- A branch lives less than a day - merge the day it is born.
- Soft cap of 3 open pull requests at once - finish one before opening a fourth.
- One checkout per concurrent activity - never build two workstreams from one tree; a
concurrent agent uses its own worktree off origin/main.
- Never commit directly on main. If the checkout is on main, create a branch first.
Triggers
Invoke with /commit or when user asks to commit changes.
Scope
Default: Only files Claude modified this session.
With "all" argument: All uncommitted changes.
With specific files: Only those files.
Workflow
STEP 1: Determine scope and gather changes
Run git status to see all changes.
Run git log --oneline -5 to see recent commit message style.
If user specified "all", include everything.
If user specified files, use those.
Otherwise, use only files modified during this Claude Code session.
STEP 2: Run code review
Use the Skill tool to invoke the review-code skill.
Wait for the review to complete.
Read the REVIEW_STATUS line from the output.
If REVIEW_STATUS is FAIL:
- Show the blocking issues found
- Tell the user they have three options:
- Reply "fix issues" for help resolving them
- Fix manually and run /commit again
- Reply "commit anyway" to bypass (not recommended)
- STOP and wait for user response
If REVIEW_STATUS is PASS:
- Note any warnings
- Continue to Step 3
STEP 3: Present commit plan
Show the user:
- List of files to commit (status and path)
- Code review result summary
- Proposed commit message
Commit message format:
[type]: [Short description]
[Optional body explaining why]
Type prefixes: feat, fix, refactor, docs, style, test, chore
Do NOT include "Co-Authored-By" lines in commit messages.
Ask: Approve this commit? Reply "yes" to commit and push.
STEP 4: Wait for approval
DO NOT PROCEED until user says yes, ok, approved, go ahead, or proceed.
If user says no or requests changes, update the plan and re-present.
STEP 5: Put the work on a branch (never commit directly on main)
Check the current branch: git branch --show-current.
If the checkout is already on a short-lived feature branch, commit there.
If the checkout is on main, create a branch FIRST - never commit on main:
- If no other session shares this checkout: git checkout -b /
- If this checkout is shared with other live sessions (a fleet checkout), do NOT move its
HEAD. Create an isolated worktree off origin/main and work there:
git worktree add ../-wt- -b / origin/main
then cd into it. (See the "Shared checkout" rules in the global CLAUDE.md.)
STEP 6: Commit and push
Stage the specific files using git add with each filename.
Never use git add . or git add -A.
Commit using HEREDOC format:
git commit -m "$(cat <<'EOF'
[message here]
EOF
)"
Run git status to verify commit succeeded.
Push with: git push -u origin HEAD.
If push fails due to remote changes, run git pull --rebase then git push.
STEP 7: Open the pull request, merge on green, and park back on main
The job is not done until the work is MERGED to origin/main. Once the user approved the
commit (Step 4), drive it home:
- Open the pull request: gh pr create --fill (or with a title/body matching recent PRs).
- Wait for checks to go green: gh pr checks --watch.
- If checks fail, fix the failure and push a NEW commit (never amend, never --no-verify),
then re-watch. Report the failure to the user if it is not quick and mechanical.
- Merge with squash once green: gh pr merge --squash --delete-branch.
(delete_branch_on_merge is ON, but --delete-branch is explicit and harmless.)
- Park the checkout back on main:
git checkout main && git pull
If you worked in a worktree, remove it: git worktree remove ../-wt-.
- Verify the resting state: git status --short is empty, git branch --show-current is main,
and the feature branch is gone (git branch --list / prints nothing).
STEP 8: Report completion
Tell the user:
- Pull request number and merge commit on main
- Number of files changed
- That the branch was deleted and the checkout is parked back on main, clean
- Any exception (e.g. left open because checks are still running) WITH the reason
Handling bypass requests
If user says "commit anyway" with blocking issues:
- Warn about the risks (runtime errors, security, UI issues)
- Ask them to type "I understand the risks"
- If confirmed, add a note about bypassed review in the commit message
- Proceed with commit
Git rules (from CLAUDE.md)
NEVER do these:
- Update git config
- Run push --force, reset --hard, checkout ., clean -f
- Skip hooks with --no-verify
- Force push to main/master
- Use git add . or git add -A
- Amend commits unless explicitly requested
ALWAYS do these:
- Use HEREDOC for commit messages
- Drive an approved commit all the way to merged-on-main, then park the checkout on main
- Create NEW commit after hook failures, never amend
Skill Version: 2.0 - trunk-based development (2026-07-11)
Changed from 1.0: The workflow no longer stops at git push. Once the user approves the
commit it drives all the way to a merged pull request on origin/main and parks the checkout
back on main: branch-if-on-main (or isolated worktree on a shared checkout), push, open the
pull request, merge on green (squash + delete branch), park on main, verify clean. Added the
trunk-based-development framing (merged-to-main is the only "done") aligned with the global
CLAUDE.md TRUNK DEVELOPMENT section and the /repo-hygiene skill.
Adapted from: sampleWeb commit skill
