commit
When the bundled commit skill or built-in commit-push-pr command resolves in this session, prefer the first only when none of this skill's contract (convention, trailer, surgical staging, pre-checks) is wanted and the second to commit, push, and open a PR at once; this skill for every other commit. Create a git commit with a subject matching the resolved convention (layered source-control config → project convention → Conventional Commits default), a Claude Co-authored-by trailer, and surgical staging (never `git add -A`), feeding the message to git via Bash heredoc. Use when: 'commit this', 'make a commit', 'commit with message HINT', not for push, branch creation, or PR creation (use /pull-request).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- shell
- bash
- metadata
- { "summary": "Commit with the resolved convention and surgical staging", "workflow-stage": "implement" }
- description
- When the bundled commit skill or built-in commit-push-pr command resolves in this session, prefer the first only when none of this skill's contract (convention, trailer, surgical staging, pre-checks) is wanted and the second to commit, push, and open a PR at once; this skill for every other commit. Create a git commit with a subject matching the resolved convention (layered source-control config → project convention → Conventional Commits default), a Claude Co-authored-by trailer, and surgical staging (never `git add -A`), feeding the message to git via Bash heredoc. Use when: 'commit this', 'make a commit', 'commit with message HINT', not for push, branch creation, or PR creation (use /pull-request).
- argument-hint
- [message-hint]
- user-invocable
- true
- disable-model-invocation
- false
02 资源文件 14
- 参考文档.claude/source-control.local.md274 B
- 参考文档.claude/source-control.md557 B
- 参考文档evals/docs/conventions/source-control.yaml385 B
- 参考文档evals/evals.json14.3 KB
- 参考文档reference/changelog-fragments.md1.1 KB
- 参考文档reference/config-probes.md3.3 KB
- 参考文档reference/design-rationale.md2.8 KB
- 参考文档reference/exec-bit.md9.0 KB
- 参考文档reference/format-check.md6.3 KB
- 参考文档reference/native-commit.md2.8 KB
- 参考文档reference/pathspec-commits.md9.6 KB
- 参考文档reference/staging-preconditions.md3.6 KB
- 脚本scripts/exec-bit-check.sh10.1 KB
- 脚本scripts/exec-bit-check.test.sh37.4 KB
03 SKILL.md 正文
Pre-computed context
Exec-bit backstop: !bash "${CLAUDE_PLUGIN_ROOT}/skills/commit/scripts/exec-bit-check.sh" --probe 2>/dev/null || echo "unavailable — run the check manually"
Config layer (user-global): !test -f "$HOME/.claude/source-control.md" && echo present || echo absent
Repository context. Gather first
Collect these with individual Bash calls, one command per call, never combined into a single invocation:
- Current branch,
git branch --show-current - Staged,
git diff --cached --stat | tail -1 - Unstaged,
git status --short | head -20 - Recent commits,
git log --oneline -5
Keep the head and tail pipes in the commands: they are the bound
(reference/config-probes.md says why).
Before the layer probes, classify the config root with bash "${CLAUDE_PLUGIN_ROOT}/lib/config-root.sh" classify. For home or non-repo, report team and personal override as not applicable, skip the three probes, and read user-global only (../../reference/config-resolution.md, "The three layers").
The team value of the convention keys (subject_pattern, type_list, trailer_policy) comes from
docs/conventions/source-control.yaml, read when probe 1 below reports it tracked, through
bash "${CLAUDE_PLUGIN_ROOT}/lib/convention-key.sh" layer "$ROOT" <key>, which prints yaml or
none for a key; value and list print the YAML's value. The retired .claude/source-control.md
is not read. Report which layer supplied each value.
Run the repo-scoped probes as separate calls. Each uses git's repo-root-relative
magic pathspec :/, which resolves against the top of the working tree, so these are correct from
any subdirectory and never need the repository root substituted into them. Quote the pathspec,
the leading : is pathspec magic, and quoting keeps the shell from reinterpreting it.
- Team layer, trackedness.
git ls-files --error-unmatch -- ":/docs/conventions/source-control.yaml" - Team layer, existence.
git ls-files --cached --others -- ":/docs/conventions/source-control.yaml" - Personal override, existence.
git ls-files --cached --others -- ":/.claude/source-control.local.md"
Probes 2 and 3 deliberately omit --exclude-standard, so a gitignored file is still listed.
Combine probes 1 and 2 in that order. Trackedness first, existence consulted only when trackedness comes back nonzero. They are not independent readings:
| Trackedness (1) | Existence (2) | Team-layer state |
|---|---|---|
| exit 0 | not consulted | present (tracked), this is a config layer |
| nonzero | non-empty output | present but UNTRACKED, deliberately not a config layer |
| nonzero | empty output | absent |
A nonzero exit from probe 1 is a result, not a failure: only a probe that could not run at all
(git unavailable, not a repository) yields an unknown value. Never fold present but UNTRACKED into
"unknown". Keep the git lines above out of ## Pre-computed context.
These are snapshots taken when they run, not substitutes for the checks. The exec-bit
line only sees what was already staged when the skill loaded; anything staged in step 2 below is
invisible to it, so step 4 re-runs the script for real. The config-layer probes report presence,
not merged content. Read the layers that are present and merge them per key. A tracked-team layer
reported present but UNTRACKED is deliberately not a layer: resolution requires the team file to
be git-tracked, so an untracked or gitignored file at that well-known path must not drive the
convention.
Every repo-scoped probe anchors at the repository root, via the :/ magic pathspec, never at
the session's current directory, and never with a resolved root path substituted in. The reasons
for each probe's shape are in reference/config-probes.md.
Per-commit checklist
Run this list for every commit, including the second and tenth commit of a session. These are commands, not remembered facts. Steps 3–5 are the ones a long session silently stops performing.
- Resolve the convention +
trailer_policyacross all three config layers (once per session is enough; re-resolve if a layer changed). - Stage surgically by explicit path, after checking the four pre-existing conditions below.
- Format, run the discoverable formatter scoped to this commit's paths, re-stage its fixes.
- Exec-bit, run
exec-bit-check.sh --fix -- <this commit's paths>, AFTER step 3. - Pre-check the drafted subject against the resolved pattern before invoking git.
- Fragments, in a repository with a
fragment-plugins.txtlist underscripts/, pipe the drafted message towrite-changelog-fragments.shand stage the paths it prints (Task step 7). - Commit via the Bash tool:
git commit -F -heredoc-piped,--trailerpertrailer_policy. - Report the resulting SHA + subject to the user.
Purpose
Encapsulates the canonical mechanic for building a commit message that honors a subject convention,
appending a Co-authored-by: trailer, and feeding the result to git commit via stdin, without
these failure modes:
- PowerShell here-string syntax (
@'...'@) inside a Bash tool call producesunexpected EOFand triggers fallback to writing the message to.git/<TEMP>.txt..git/is git's internal directory; scratch files there collide withCOMMIT_EDITMSGand other internals. git commit -m "<multi-line>"flattens newlines unpredictably across shells.git add -A/git add .stages secrets, build artifacts, unrelated edits, the convention is surgical staging.
Subject convention ladder
The subject convention (WHAT shape a subject must take) resolves via a ladder, checked in order:
- The layered source-control convention config. User-global, tracked team
(
docs/conventions/source-control.yaml), and gitignored personal override, merged per key by${CLAUDE_PLUGIN_ROOT}/reference/config-resolution.md. Resolve all three layers before using any value; a value from one layer alone is not the effective config. When any layer declares one, the effectivesubject_pattern(andtype_list, when Conventional-Commits-shaped) is authoritative. Before pre-checking, expandsubject_pattern: the literal keywordConventional Commitsexpands to the anchored pattern in step 3 below; anything else is already a single anchored regex and is used as-is. - The consuming project's own
CLAUDE.md,AGENTS.md, rules, or commit-msg hook, if the effective merged config declares nosubject_pattern(absent from every layer, which includes the case where layers exist but only contribute other keys) but the project declares (or enforces via lefthook, husky, commitlint, or a plain.git/hooks/) a different convention, follow that instead. - Conventional Commits (11-type vocabulary), the default when neither of the above is present. Every subject must match this anchored pattern:
^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+
Compliant examples:
feat(auth): add OAuth login flowfix(api): handle null user in /me endpointdocs: clarify rebase guidancerefactor(skills)!: rename /simplify to /code-review
The 11 types. build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test.
security is not a Conventional Commits type, never add it. The sources for the set are in
reference/design-rationale.md.
When the project enforces its convention with a commit-msg git hook, that hook is the authoritative
gate regardless of which rung above resolved the pattern; this skill's pre-check exists to fast-fail
client-side before the hook round-trip. When no layer resolves a subject_pattern and nothing is
inferable from the project's own files, point the user at /source-control:setup to persist a
convention instead of re-inferring one every commit.
Task
-
Survey working tree (
git status,git diff --cached --stat) to confirm what's staged. -
Stage the intended files, but first check each path against these four pre-existing conditions, before this step touches anything. Each is a state
git addsilently overwrites rather than errors on, and in three of the fourgit diff --statreads empty, so the obvious check misses it. Rationale for each is in reference/staging-preconditions.md.Condition Detect with Action Already-staged deletion git diff --cached --name-status -- <path>reportsDSkip the path entirely; never git addover itStaged rename, old side same command reports R<score> <old> <new>whose<old>falls under<path>Skip the old side entirely; never git addover itUntracked files under a directory path git status --porcelain -- <path>shows??entriesStop and surface them; enumerate the intended files instead of adding the directory Partial-staging split git diff --cached --stat -- <path>andgit diff --stat -- <path>both non-emptyLeave as-is; a blanket add sweeps in hunks the user deliberately left unstaged Run
git add <path>...only for paths in none of those four states. -
Run the format-before-push check against the files just staged for this commit (not the full staged set), re-staging any fixes.
-
Run the exec-bit check, after step 3, not before: a formatter re-stage in step 3 reads the worktree file mode, so setting the exec bit any earlier would be silently undone by that later
git add.bash "${CLAUDE_PLUGIN_ROOT}/skills/commit/scripts/exec-bit-check.sh" --fix -- <path>...The script reports and fixes every newly-added file whose staged blob starts with a shebang while its staged mode is
100644, setting the worktree bit and the index entry in the order that survives a latergit add. The pathspec is required.--fixrefuses an unscoped run (exit 2) rather than sweeping mode changes across another session's staged work; pass--allonly to opt into a deliberate whole-index sweep. Rationale, cross-platform caveats, and the manual fallback live in reference/exec-bit.md. -
Draft a subject + optional body, scoped to the staged diff, shaped to satisfy the active subject convention (default: the Conventional Commits pattern above).
-
Pre-check the subject against the pattern (fast-fail before invoking git).
-
Write changelog fragments when the repository releases plugins from them, which it does when a
fragment-plugins.txtlist exists in itsscripts/directory. Pipe the drafted message (subject, blank line, body) to the script from the repository root andgit addeach path it prints, so the fragments land in this commit:bash "${CLAUDE_PLUGIN_ROOT}/scripts/write-changelog-fragments.sh" <<'EOF' <the drafted message> EOFOn exit 2 for a subject it cannot map, rerun with
--level major|minor|patch|none. A fragment replaces the hand version bump and CHANGELOG entry. For a plugin the list does not name, the script writes nothing, and the hand release record still applies. What it writes, and the bump each type maps to, is in reference/changelog-fragments.md. -
Invoke
git commit -F -via the Bash tool, heredoc-piped, adding--trailerper the trailer template below only when the resolvedtrailer_policycalls for one. -
Surface the resulting commit SHA + subject to the user.
Canonical bash form
Use the Bash tool, not the PowerShell tool. Bash heredoc is the canonical form across all platforms (Git Bash, Linux, macOS).
# --trailer line below applies only when the resolved trailer_policy calls for one
# (default: yes). trailer_policy "none" -> drop the --trailer line entirely.
# trailer_policy naming a different template -> substitute that template's text.
git commit -F - --cleanup=verbatim \
--trailer "<Co-authored-by trailer, placeholders filled>" \
<<'EOF'
<subject — shaped to satisfy the active subject convention>
<body — wrap at ~72 cols, blank line between paragraphs>
EOF
PowerShell here-string is shown only for reference. git commit -F - <message-via-stdin> with
@'...'@ would work in a pure PowerShell tool call, but never mix syntaxes inside one tool
invocation. A PowerShell @'...'@ block inside a Bash tool call leaves the bash parser unable to
terminate the heredoc.
Hard rules:
- Invoke via the Bash tool.
- Heredoc delimiter is single-quoted:
<<'EOF' ... EOF. Single quotes prevent$variableand backtick interpolation inside the message. --cleanup=verbatimpreserves the message exactly, no auto-stripping of comments or whitespace.- Never write the message to
.git/<TEMP>.txt. If a real file is unavoidable, usemktemp. - Never mix Bash heredoc with PowerShell
@'...'@inside one invocation.
For a dirty shared index (concurrent sessions, pre-existing mixed WIP), the pathspec-limited form and its staged-deletion hazards live in reference/pathspec-commits.md. Default remains the plain index commit.
The exec bit does not survive the pathspec form under core.filemode=false (the Windows
default). --only records the working-tree mode, and with filemode off git cannot see the
chmod +x, so a correctly-set 100755 index entry is rebuilt as 100644. Verified both
directions: the plain index commit preserves 100755; the pathspec commit loses it. If this
commit includes a newly-added shebang file the exec-bit check corrected, commit that path with the
plain index form (splitting the commit if the rest needs a pathspec), and confirm with
git ls-tree HEAD -- <path> rather than trusting the index. Full detail and the two workarounds
that were tested and failed are in reference/pathspec-commits.md.
Pre-check
Before invoking git commit, regex-match the drafted subject against the active convention's pattern
(default: the Conventional Commits pattern above).
On mismatch, surface the convention name and the compliant examples as actionable guidance, and ask
for a compliant subject before invoking git. The pre-check is shape-only; the project's commit-msg
git hook (when one exists) is the authoritative gate at commit time. The pre-check exists to save the
hook-startup floor when the drafted subject is obviously wrong, plus to give the user a fast
actionable error rather than an opaque hook failure.
Trailer resolution
The default template is:
Co-authored-by: Claude <model> <noreply@anthropic.com>
The <model> placeholder is filled from your own knowledge of the running session: the model
family and version the harness reports for this session. If uncertain, ask the person to read the
model from /status and tell you, rather than guessing or running a command yourself. There is no
environment variable that auto-fills it, the trailer is part of the message body sent to
git commit, not git config. Pointer:
commands reference, rows /status and
/usage; Restrict Claude's skill access
for which built-ins the model can invoke.
An optional context clause, Co-authored-by: Claude <model> (<context>) <noreply@anthropic.com>,
e.g. (1M context), may be added when the context window is a genuinely distinguishing fact about
the session and is known with confidence. It is not required, and its absence is not a defect.
Which authority wins
Four sources can specify a trailer. Resolve in this order:
- A resolved
trailer_policyfrom any config layer. Authoritative.nonemeans omit--trailerfrom thegit commitinvocation entirely (do not append an empty or default trailer); a value naming a different template means substitute that template exactly.noneand absence are different states. - The consuming project's own conventions (
CLAUDE.md,AGENTS.md, rules), if they specify a different attribution trailer, or none, follow those. - Harness-injected commit guidance. The Claude Code harness may inject its own commit
instruction into the session, naming a
Co-Authored-Bytrailer. Adopt its shape, this is why the context clause above is optional rather than mandatory, but never copy its literal text. That injected guidance can carry a hardcoded model name that does not match the running session. Copying it verbatim writes a false provenance claim into durable git history, which is precisely the harm this template exists to avoid. Always fill<model>from actual session knowledge. Absent or unusual injected guidance says nothing about the project's wishes (a mod can rewrite or blank it; reference/design-rationale.md); sources 1 and 2 still decide. - This skill's default, above.
Key spelling. This skill emits Co-authored-by and never rewrites the spelling existing history
carries; a consumer who wants a different spelling expresses it as a trailer_policy template. Why
that spelling: reference/design-rationale.md.
Unrelated uncommitted changes
If the working tree contains unstaged or untracked files that fall outside this commit's scope,
classify each before staging per /source-control:pull-request create (its unrelated-changes classification:
include / stash / separate-commit / discard). Do not duplicate that classification here; invoke
/source-control:pull-request create to surface it to the user.
Staging discipline
Always git add <specific-files>, never git add -A or git add .. The risk is including secrets,
build artifacts, or unrelated changes that the user did not approve for this commit. If multiple
files are intentionally part of the commit, stage them by explicit list, not by wildcard, and skip
the partial-staging split per step 2 above.
Immediately after staging, run the format-before-push check and then the exec-bit check, in that order. Catch what CI would otherwise catch on the push round-trip.
Composition policy
This skill is the single source of truth for the commit mechanic. Other skills should compose
/source-control:commit rather than invoking git commit directly. Direct calls bypass the pre-check, trailer
logic, and surgical-staging discipline this skill exists to enforce.
"Compose" means one of exactly two things, and a composing skill must name which:
- Re-invoke
/source-control:commitfor the commit. This is the default and the only form that re-renders this skill's full content. Prefer it whenever the commit is a discrete step a user could have asked for. - Run the per-commit checklist above yourself, per commit, as commands. Permitted for a workflow skill making many commits in one flow, where re-invocation per commit is disproportionate.
What is not composition is treating this skill as a convention absorbed once and thereafter remembered. The mechanic that decays is not the shape of the commit message, that is reinforced every commit, it is the ordered per-commit checks: the formatter run, the exec-bit fix, the subject pre-check. Those produce no visible signal when skipped, so a session that has stopped running them looks identical to one that has not, until CI says otherwise. That is the observed failure this policy exists to prevent, not a hypothetical one.
Two properties make step 4 the cheap re-anchor for the checklist form: it is a command with an exit code rather than a paragraph to recall, and the pre-computed probe at the top of this file surfaces its finding before anything else is read.
Workflow skills without explicit commit semantics should report status at phase boundaries and let
the user or the next workflow stage decide commit timing; a skill with commit semantics in its
documented contract (e.g. /source-control:pull-request create) composes this one.
Recorded deviations
- Model invocation stays enabled (
disable-model-invocation: false), so composing workflow skills can reach this one. The archetype, the reason and the compensating controls are in reference/design-rationale.md.
Boundary, native Claude Code surfaces
Claude Code bundles a skill of the same name whose description tells the model to use it whenever it is about to commit, so the two compete for every commit. A built-in command also commits as its first step. What each of the three surfaces does is in reference/native-commit.md.
Routing. Prefer this skill whenever it resolves and the repository carries a commit
convention, a source-control config layer is present, or a workflow composes /source-control:commit.
When the bundled commit skill resolves in this session, prefer it only for a plain commit where
none of this skill's contract is wanted. A request to commit, and nothing more, stays here even
when /commit-push-pr resolves: that command also pushes and opens a PR, which
/source-control:pull-request owns.
Mutation gate. All three create commits, and /commit-push-pr also pushes. Pick one per
commit and never run two for the same change. This skill never chains into the bundled commit
or /commit-push-pr on its own behalf.
Availability is never assumed. The bundled skill is gated, and disableBundledSkills or a
skillOverrides entry hides it; this section states what to do when a surface resolves, never
that it is present. The four-part records live in reference/native-commit.md.
What this skill does NOT do
- No
git push, that's/source-control:pull-request create. - No branch creation, that's the project's branch-naming / branch-protection mechanisms (or
/source-control:worktree create). - No PR body composition, that's
/source-control:pull-request create. - No
git mergeor forge merge, that's/source-control:pull-request merge. - No rebase, that's
/source-control:pull-request create. - No
--no-verifyor hook bypass, if the project'scommit-msghook rejects the message, surface the error and re-draft; never bypass.
Spoke paths
The reference/ files write this skill's directory as <skill-dir>, which is
${CLAUDE_SKILL_DIR}. Put that path in place of the placeholder before running a command or writing
it into a brief. Those files arrive through the Read tool as plain bytes, so a ${…} token in them
would reach the Bash tool unsubstituted, and the Bash tool's environment has no CLAUDE_SKILL_DIR
to expand it from. Basis: the plugins reference,
https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves.
Next
/source-control:pull-request create. Its precondition is a branch carrying the work to ship.
Reference index. Load on demand
| File | Load when |
|---|---|
| reference/config-probes.md | A repository-context probe's shape is in question: the bounding pipes, the omitted --exclude-standard, what a nonzero probe exit means, or why probes anchor at :/. |
| reference/changelog-fragments.md | Running step 7 and checking what a fragment holds: the bump per type, the changelog section, a none fragment, a repository or plugin without the list. |
| reference/design-rationale.md | A rule's source is questioned: the 11-type set, a mod rewriting injected commit guidance, the Co-authored-by spelling, or the model-invocation deviation. |
| reference/native-commit.md | Choosing between this skill, the bundled commit skill and /commit-push-pr, or rechecking their records. |
| reference/staging-preconditions.md | A step-2 precondition fired and the right action is not obvious, or judging whether a new condition belongs in the set. |
| reference/format-check.md | Running step 3, formatter discovery, path scoping, the two-stage filter, partial-staging preservation. |
| reference/exec-bit.md | Understanding or hand-running step 4, why both the worktree bit and the index, core.filemode caveats, manual fallback. |
| reference/pathspec-commits.md | The index holds staged work outside this commit's scope. Pathspec --only semantics and the staged-deletion hide/restore sequence. |
${CLAUDE_PLUGIN_ROOT}/reference/config-resolution.md |
Resolving or merging the three config layers, or interpreting a key's none-vs-absent state. |
04 同仓库更多 Skills
work
Pick exactly one work item from the tracker frontier by priority tier (due recurring, guardrails, highest impact, then not-yet-due recurring), claim it race-safe, and execute it end-to-end through the project's workflow. Use when the user asks to pick, grab, or work the next item, ticket, or issue, or asks what to work on next. Backlog CRUD is /work-items:track; draining the backlog in a loop is /work-items:work-loop.
work-loop
Drain the work-item backlog as a self-paced autonomous loop, launched via /loop: each cycle triages raw intake, admits items through the fail-closed admission gate, runs them through /work-items:work under an adaptive cap, and checks the drain exit. Authors PRs, never merges. Use when: 'work loop', 'run the work loop', 'start the worker loop', 'drain the backlog', 'autonomous drain', 'loop the backlog', 'drain the issue backlog to done'. Escalations: /work-items:attend-queue.
triage
Evaluate raw intake, any untriaged item whoever filed it (bug reports, feature requests, unsolicited PRs, dogfood issues): raw, verified, briefed, autonomous-eligible, with exits to needs-info, human-gated, close. Use when: 'triage', 'what needs triage', 'triage this issue', 'triage this PR', 'evaluate this bug report', 'is this bug real', 'should we merge this unsolicited PR', 'attention view', 'what intake needs attention', 'sweep needs-human'. No number: the attention view. Escalations: /work-items:attend-queue.
track
Backlog CRUD through the bound tracker: stats, list, add, start, done, due, recheck, search, audit, publish-plan, link (default: stats). Use when the user wants to add, claim, or close a work item, ticket, or issue; list, search, or see a dashboard of open items; check what is due on the recurring schedule; or audit stale claims and labels. New bug reports go to /bugs:write first. Picking and executing the next item is /work-items:work; raw intake is /work-items:triage.
ship
Route and run one spec container's multi-session effort: where it stands, which execution shape is in effect (per-item PRs or one integration branch) and its discipline, the next step; `run` works its ready items in parallel, landing one at a time. Use when the user says 'ship' about a spec or container, asks where it stands or what is next, wants to run, drive or resume it, or close it out. One item: /work-items:work; re-slicing: /work-items:decompose.
setup
Verify and configure the work-items plugin for this repo. check read-only inspects the tracker binding (the home's work-items.yaml), tracked .github/recurring-schedule.json (presence, JSON validity, unique reconciliation keys), jq and tracker-seam entry gates, recurring-maintenance role label, provenance and capability-tier labels; apply binds the provider (copying legacy JSON), writes the schedule, migrates provenance and capability-tier labels when authorized, backfills legacy frontier stamps, and optionally remaps role labels. First-time bind writes minimum viable config only; per-item schedule seeding is opt-in via --seed-schedule. Use when: 'set up work-items', 'bind the tracker provider', 'is work-items configured', 'configure the recurring schedule', 'work-items setup', 'seed recurring items', 'bulk-seed the recurring schedule', 'remap the work-item role labels', or the due/recheck/work actions report no recurring schedule configured, or the seam reports no binding. Re-runnable.