commit

Commit

The output of this skill is a correctly scoped local commit (or a read-only generated message). Three things determine success: choosing the right changeset, a message that conforms to emoji + Conventional Commits, and a report consistent with the actual Git result. Do not push.

1. First route the mode

• message-only: The user only wants a commit message generated, suggested, or rewritten. Read-only git status、git diff --cached、git diff and necessary files; do not git add, do not git commit, do not modify .gitignore or any other worktree/index. By default analyze staged changes; when the user names another set of unstaged/untracked changes, analyze only that scope and state that staged content is excluded. When the scope is not unique, only explain which set needs to be chosen.
• execute-commit: The user explicitly requests a commit. Only then enter the staging, Ignore vs Commit, and commit flow below.

2. Determine the commit scope (execute-commit)

Combine the first probes into one call:

git status --short --branch && git diff --cached --stat

Judge in order:

State	Action
There are staged changes and the user did not name another scope	Commit only the staged changes. Do not automatically add unstaged changes; in the report, remind about files still uncommitted.
There are staged changes, but the user authorized a different set of paths	Stop and report the scope mismatch. Do not commit the existing staged changes, do not stage the new scope, and do not unstage on the user's behalf; ask the user to choose or split the index.
No staged changes and only one unstaged/untracked file	If the file's diff or content has no sensitive risk, git add -- <path> and then continue without asking the user to run it again.
No staged changes and multiple files	The scope named by the user, or the changeset just completed in this session whose purpose is single and can be verified from the diff, is the commit scope; the user does not need to say "commit everything" again. Exclude existing modifications that cannot be attributed first; only ask when the scope is still not unique, and do not infer that changes in the same directory belong to this task.
Nothing at all	Tell the user there is nothing to commit.

When the user asks to split into multiple commits, stage each commit with explicit paths and complete the flow below one by one.

Staging boundaries

• Use only git add -- <path...>. Passing all entries of git status to git addin bulk (such as --pathspec-from-file) is equivalent to git add -Aand likewise skips item-by-item classification; do not use it unless the user explicitly requests committing all changes.
• When a path name or diff looks like .env, credentials, tokens, cookies, private keys, secrets, certificates, or private data, stop and ask the user to confirm.
• When changes mix multiple unrelated purposes, stop and ask whether to split.
• Ignore vs Commit: When candidates include ?? untracked, dependency/build/cache/OS noise, or suspected secrets, first read references/ignore-vs-commit.md before classifying; add what should be ignored to .gitignore and do not stage it; for tracked secrets, stop and report. When all candidates are tracked source/documentation changes, there is no need to read it.
• Ignore decisions must not be silent: for any paths skipped from staging, any changes to .gitignore, or any paths not included due to ignore rules, tell the user in that turn the path/pattern, the reason, and what was done.

3. Write the commit message

Use git diff --cached to view the content of the determined scope, then write the message:

1. If the user provided a message, use it as-is.
2. When the repository has its own commit conventions (commitlint configuration,CONTRIBUTING、AGENTS.md/CLAUDE.md defer to the repository.
3. Otherwise use emoji type(scope): subject. Emoji may only be the corresponding item from the table below, and you write it into the message; do not rely on hooks to add emoji automatically—repositories without such hooks will leave a history with inconsistent formatting.

type	emoji	For
feat	✨	New feature
fix	🐛	Bug fix
docs	📝	Docs only
style	🎨	Formatting changes that do not change semantics
refactor	♻️	Code changes that are neither new features nor fixes
perf	⚡️	Performance
test	✅	Tests
build	🏗️	Build system or dependencies
ci	👷	CI configuration and scripts
chore	🔧	Other miscellaneous (configuration, sync, etc.)

• header ≤ 250 characters; scope is optional, use the module, feature, or directory name; subject uses the imperative mood, lowercase first letter, no period.
• body is optional, write “why”, each line ≤ 300 characters. Example:🐛 fix(payment): handle zero-amount refunds。

4. Commit and verify

• Before committing, complete the change-related verification required by the repository. Pure documentation usually only checks formatting, links, or generated indexes; add lint, type checking, and tests only when code or configuration is affected. Results already passed for the same content in this session may be reused; rerun if the content changed or the repository requires a rerun.
• Commit with HEREDOC, preserving hooks:

git commit -m "$(cat <<'EOF'
✨ feat(auth): add user login feature
EOF
)"

• Do not use --no-verify or HUSKY=0, unless the user explicitly requests it.
• When a hook fails, the commit was not created: fix the root cause, re-stage, and create a new commit (not --amend); do not report success if it did not succeed.
• Fix boundary: do it directly only if the fix is mechanical—the hook output already states the change, or it is a formatter/lint autofix, and the change does not alter code behavior or textual meaning (such as removing a marker named by the hook). If you fix it directly, still state in the report which line was changed and why. When the fix requires judgment (changing logic, changing wording, deleting the user's substantive content, touching files outside the commit scope), first report the hook output and the proposed fix and wait for user confirmation; at this point the commit still has not been created, so say so truthfully.
• Hooks may rewrite files (such as lint-staged formatting). If they rewrite already-committed paths, rerun the affected focused verification.
• After committing, verify once, and the report is based on this output (hooks may have rewritten the subject):

git status --short --branch && git log -1 --format='%h %s'

5. Report

Provide: the commit hash and actual subject, the checks that were run, files still uncommitted, and the paths handled by Ignore vs Commit this time (what was ignored, why, and whether .gitignore）。