commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

commit

提交

Fast path to commit. Gather the state below in one batch, reason about file safety and scope, then commit.

快速提交路径。批量收集以下状态信息，判断文件安全性和范围，然后执行提交。

Arguments

参数

$ARGUMENTS

may be empty or contain directives. Recognize and combine:

Directive	Behavior
`only staged` / `staged only`	Do NOT stage anything. Commit the existing index.
`relevant` / `scoped`	Stage only files that fit the current task's scope; leave unrelated tweaks out.
`amend`	Use `git commit --amend --no-edit` after staging. Do not rewrite the existing message.
`no trailer`	Never append a `Co-Authored-By` trailer, even if the repo uses them.
anything else	Treat as a message hint or additional constraint — see step 5.

$ARGUMENTS

可以为空或包含指令。支持识别并组合以下指令：

指令	行为说明
`only staged` / `staged only`	不暂存任何内容。提交已有的索引内容。
`relevant` / `scoped`	仅暂存符合当前任务范围的文件；忽略无关的微小调整。
`amend`	暂存后执行 `git commit --amend --no-edit` 。不重写现有提交信息。
`no trailer`	绝不追加 `Co-Authored-By` 尾部信息，即使仓库有此约定。
其他内容	视为提交消息提示或额外约束——详见步骤5。

Current state

当前状态

Gather this before anything else, in one batch where the host allows it. Every section below reasons off this output — do not re-run these commands later.

Command	Used for
`git branch --show-current`	issue-number suffix on the title
`git status --short`	what is untracked vs. modified vs. staged
`git diff --stat`	unstaged size and file list
`git diff --cached --stat`	staged size and file list
`git log --oneline -5`	recent title style
`git log -1 --format='%B'`	trailer style of the last commit

Then read the repo's own commit convention, if it has one:

bash

grep -B 1 -A 10 -i "^##.*commit\|commit message\|commit format\|conventional commit" \
  CLAUDE.md AGENTS.md .github/CONTRIBUTING.md 2>/dev/null | head -80 \
  || echo "(none found — use conventional commits)"

在执行任何操作前，先批量收集以下信息（若宿主环境允许）。后续所有步骤都基于这些输出——请勿重复执行这些命令。

命令	用途
`git branch --show-current`	获取标题中的 issue 编号后缀
`git status --short`	区分未跟踪、已修改和已暂存的文件
`git diff --stat`	未暂存变更的大小和文件列表
`git diff --cached --stat`	已暂存变更的大小和文件列表
`git log --oneline -5`	参考近期提交标题风格
`git log -1 --format='%B'`	参考上一次提交的尾部信息风格

然后读取仓库自身的提交规范（如果存在）：

bash

grep -B 1 -A 10 -i "^##.*commit\|commit message\|commit format\|conventional commit" \
  CLAUDE.md AGENTS.md .github/CONTRIBUTING.md 2>/dev/null | head -80 \
  || echo "(未找到规范 — 使用conventional commits)"

Staging rules

暂存规则

Source code, docs, and tracked configs are safe by default — don't overthink them. Focus the skip judgement on generated and machine-specific artifacts.

Never auto-stage these:

Build or incremental artifacts:

*.tsbuildinfo

dist/

build/

out/

.next/

.turbo/

.parcel-cache/

coverage/

node_modules/

Caches and logs:

.cache/

*.log

logs/

npm-debug.log*

pnpm-debug.log*

yarn-debug.log*

OS / editor cruft:
```
.DS_Store
```
,
```
Thumbs.db
```
,
```
*.swp
```
,
```
*.swo
```
,
```
*~
```
Secrets:
```
.env
```
,
```
.env.*
```
— warn the user if they appear untracked

Local machine state:

.playwright-mcp/

.claude/settings.local.json

.vscode/settings.json

unless already tracked

Anything else — use judgement. If a path looks generated (hash suffix, inside a cache-like dir, editor backup) and is untracked, skip it and list it in the final report. If ambiguous, ask by skipping and reporting, not by prompting.

Never use

git add .

git add -A

, or

git add -f

. Stage with explicit paths.

源代码、文档和已跟踪的配置文件默认是安全的——无需过度考量。重点判断需要跳过的生成文件和机器特定工件。

绝不自动暂存以下内容：

构建或增量工件：

*.tsbuildinfo

dist/

build/

out/

.next/

.turbo/

.parcel-cache/

coverage/

node_modules/

缓存和日志：

.cache/

*.log

logs/

npm-debug.log*

pnpm-debug.log*

yarn-debug.log*

系统/编辑器临时文件：
```
.DS_Store
```
,
```
Thumbs.db
```
,
```
*.swp
```
,
```
*.swo
```
,
```
*~
```
敏感信息：
```
.env
```
,
```
.env.*
```
—— 如果这些文件显示为未跟踪状态，需向用户发出警告

本地机器状态：

.playwright-mcp/

.claude/settings.local.json

.vscode/settings.json

（除非已被跟踪）

其他内容——自行判断。如果路径看起来是生成的（带有哈希后缀、位于类缓存目录中、编辑器备份文件）且未被跟踪，则跳过它并在最终报告中列出。若存在歧义，应跳过并报告，而非提示用户确认。

绝不使用

git add .

、

git add -A

或

git add -f

。使用明确的路径执行暂存操作。

Heavy-diff delegation

大差异委托处理

The

git diff --stat

output from Current state shows the size. Handle the common case in-thread. Only delegate when the staged OR unstaged diff exceeds ~500 changed lines or ~20 files AND you need actual diff content (not just stats) to decide scope, classify files, or compose the body.

Delegation is an optimization, not a requirement. On a host with no subagent facility, read the diff in-thread instead — in chunks if it is large — and carry on. Nothing else in this skill depends on the delegation step.

When delegating, dispatch one subagent:

A read-only subagent is enough — it inspects the diff and answers, nothing more.
The subagent has no conversation history — pass the exact
```
git diff
```
output (or the subset you need) in the prompt.
Ask a single narrow question. Good shapes:
- "From this diff, which files belong to scope:
  <scope from $ARGUMENTS>
  ? Return file paths only."
- "Summarize the distinct changes in this diff as 3-5 past-participle bullets, no prose."
Use the returned answer directly. Do not ask the subagent to write the commit message — that stays in-thread with full project context.

Do not delegate for small diffs. The round-trip is slower than reading the diff inline, and the main thread already has the conventions context.

当前状态中的

git diff --stat

输出显示了变更大小。常规情况在主线程处理。仅当已暂存或未暂存的差异超过约500行变更或约20个文件，且需要实际差异内容（而非仅统计信息）来判断范围、分类文件或撰写提交正文时，才进行委托处理。

委托是一种优化手段，而非必需步骤。如果宿主环境不支持子代理，则在主线程中读取差异内容——若内容过大可分块读取——然后继续执行。本技能的其他部分不依赖委托步骤。

进行委托时，调度一个子代理：

仅需只读子代理——它仅检查差异并返回结果，不执行其他操作。
子代理无对话历史——在提示中传递完整的
```
git diff
```
输出（或所需子集）。
提出单一明确的问题。示例：
- "从该差异中，哪些文件属于范围：
  <$ARGUMENTS中的范围>
  ？仅返回文件路径。"
- "将该差异中的不同变更总结为3-5个过去分词形式的项目符号，无需额外描述。"
直接使用返回的答案。请勿让子代理撰写提交消息——这需在主线程中结合完整项目上下文完成。

小差异无需委托。往返通信比直接读取差异内容更慢，且主线程已掌握规范上下文。

Steps

步骤

Parse
```
$ARGUMENTS
```
.
If
```
only staged
```
: go to step 4.
Stage safe files with
```
git add <path>
```
. Apply the rules above.
- If
```
relevant
```
  : from the unstaged diff, pick only files whose changes fit the scope described in
```
$ARGUMENTS
```
  or obvious from the combined diff; leave the rest.
Look at the staged diff (you already have
```
git diff --cached --stat
```
from Current state; read
```
git diff --cached
```
only if the message needs detail beyond the stat). If nothing is staged, stop and tell the user.
Compose the commit message:
- Single-line title, ≤72 chars,
```
<type>: <description>
```
  .
- Types:
```
feat
```
  ,
```
fix
```
  ,
```
docs
```
  ,
```
chore
```
  ,
```
refactor
```
  ,
```
test
```
  ,
```
style
```
  ,
```
ci
```
  .
- Follow the project convention from Current state when present.
- If the current branch is
```
issue-<N>
```
  , append
```
 #<N>
```
  to the title.
- A hint in
```
$ARGUMENTS
```
  — whatever the Arguments table did not match — steers the message, not the staging: let it shape the title's description, and pass it verbatim to
```
commit-summary
```
  so the body reflects it too. It narrows what the message leads with; it never drops changes the commit contains.
- Body: invoke the
```
commit-summary
```
  skill and use what it returns. It weighs the change and either derives a body from the code or returns two to three mechanical lines. See Body below for the inline fallback.
- Attribution: this step runs the
```
git commit
```
  , so it is the last place a footer can be caught. Read the assembled message and remove any "Drafted with AI" or "Generated with" line, session or transcript link,
```
<sub>
```
  line, trailing
```
---
```
  rule, badge, promotional line, or
```
Co-Authored-By
```
  trailer crediting an assistant — wherever it came from, including a body
```
commit-summary
```
  returned and a message being amended. Add none either, and do not copy one forward from the previous commit: a trailer already in the log is not licence to repeat it. A human co-author trailer is fine where the repo's convention asks for one.

Commit:

bash

git commit -m "$(cat <<'EOF'
<title>

<optional body>
EOF
)"

amend

was requested:

git commit --amend --no-edit

Never pass
```
--no-verify
```
. If a pre-commit hook fails: fix the issue, re-stage, create a NEW commit (do not amend unless the user asked).
Final output: one line —
```
Committed <short-sha> on <branch>: <title>
```
— followed by a short
```
skipped: …
```
list if anything was left out.

解析
```
$ARGUMENTS
```
。
如果包含
```
only staged
```
：跳至步骤4。
使用
```
git add <path>
```
暂存安全文件。遵循上述规则。
- 如果包含
```
relevant
```
  ：从未暂存差异中，仅选择变更符合
```
$ARGUMENTS
```
  描述范围或从合并差异中可明显判断的文件；忽略其余文件。
查看已暂存的差异（已从当前状态获取
```
git diff --cached --stat
```
；仅当提交消息需要超出统计信息的细节时，才读取
```
git diff --cached
```
）。如果没有任何已暂存内容，停止操作并告知用户。
撰写提交消息：
- 单行标题，≤72字符，格式为
```
<type>: <description>
```
  。
- 类型包括：
```
feat
```
  、
```
fix
```
  、
```
docs
```
  、
```
chore
```
  、
```
refactor
```
  、
```
test
```
  、
```
style
```
  、
```
ci
```
  。
- 若存在当前状态中获取的项目规范，需遵循该规范。
- 如果当前分支为
```
issue-<N>
```
  ，在标题后追加
```
 #<N>
```
  。
- ```
$ARGUMENTS
```
  中的提示内容——未匹配到参数表中的内容——用于引导消息撰写，而非影响暂存：让它塑造标题的描述部分，并将其原样传递给
```
commit-summary
```
  技能，以便正文也能体现该提示。它仅调整消息的重点内容；绝不会忽略提交包含的变更。
- 正文：调用
```
commit-summary
```
  技能并使用其返回内容。该技能会评估变更内容，要么从代码中生成正文，要么返回2-3条标准化内容。若无法调用该技能，可参考下方正文部分的内联替代方案。
- 署名：此步骤执行
```
git commit
```
  ，因此是最后可处理尾部信息的环节。读取组装好的消息并移除任何"Drafted with AI"或"Generated with"字样、会话或记录链接、
```
<sub>
```
  行、尾部
```
---
```
  分隔线、徽章、推广内容，或任何归功于助手的
```
Co-Authored-By
```
  尾部信息——无论这些内容来自何处，包括
```
commit-summary
```
  返回的正文或待修正的提交消息。也不要添加此类内容，且不要从上一次提交中复制：日志中已有的尾部信息并非重复添加的许可。若仓库规范要求，人类合著者的尾部信息是允许的。

执行提交：

bash

git commit -m "$(cat <<'EOF'
<title>

<optional body>
EOF
)"

如果请求了

amend

：执行

git commit --amend --no-edit

。

绝不使用
```
--no-verify
```
。如果预提交钩子失败：修复问题，重新暂存，创建新的提交（除非用户要求，否则不要修正）。
最终输出：一行内容——
```
已提交 <短哈希> 至 <分支>: <标题>
```
——如果有内容被忽略，后续追加简短的
```
跳过: …
```
列表。

Body

正文

The body is the part a reader cannot recover from the diff: what the running code does that forced the change, which call paths reach it, what breaks on update, when it broke, and what was deliberately left alone.

Invoke the

commit-summary

skill to compose it. If the host cannot chain skills or

commit-summary

is not installed, do it inline:

Weigh the change first. Derive when it alters behaviour, a contract, a public type, or a default, or when it fixes a defect. Otherwise — a rename, a formatting pass, generated output, additive scaffolding — write two or three past-tense lines naming what the file list does not show, and stop. Weight decides, not diff size.

To derive, answer these against the code, in order, in blank-line-separated paragraphs wrapped at 80. Skip any question with no real answer:

What changed, and what does the running code do that forces it? Open the implementation behind the declaration, the client behind the handler, the changelog behind the bump — not the diff again. A change holding several independent decisions gets one paragraph each, including anything the fix revealed and anything it made redundant.
Which concrete inputs or call paths reach it, and which are ruled out?
How did it fail observably — what a user saw, not "the type was wrong".
What breaks for someone who updates, and why is it still correct?

When did it break?

git log -S '<removed expression>' -- <path>

git blame -L '<line>,+1'

What do the tests pin? Name the cases, never "added tests".
What did you notice and deliberately not fix?

Never invent provenance. A hash appears only if a command returned it in this session; a named call path was read in the source. No result means the paragraph is dropped, not softened into "has likely been broken for a while".

Write it in plain words and short sentences. Each paragraph opens on a past-tense verb, and the sentence after it is the reason, stated as behaviour.

Design rationale handed over from a comment-cleanup pass answers question 1 — fold it into that paragraph rather than appending it as a block.

A project convention found in Current state overrides all of this. Some repos cap body width or forbid paragraphs outright.

Nothing is appended after the last paragraph — see the trailer rule in step 5.

正文是读者无法从差异中恢复的信息：运行代码的哪些行为导致了此次变更、哪些调用路径涉及该变更、更新时会出现哪些问题、问题何时出现，以及哪些内容被刻意保留未修改。

调用

commit-summary

技能来撰写正文。如果宿主环境无法链式调用技能或未安装

commit-summary

，可使用内联方式撰写：

首先评估变更的重要性。判断它是否改变了行为、契约、公共类型或默认值，或是修复了缺陷。否则——重命名、格式调整、生成输出、新增脚手架——撰写2-3条过去式语句，说明文件列表未体现的内容，然后停止。重要性决定内容，而非差异大小。

生成正文时，按顺序针对代码回答以下问题，每个答案为单独段落，每行不超过80字符。跳过无实际答案的问题：

变更了什么，运行代码的哪些行为导致了此次变更？查看声明背后的实现、处理程序背后的客户端、版本 bump 背后的变更日志——而非再次查看差异。包含多个独立决策的变更需分段落描述，包括修复过程中发现的问题和不再需要的内容。
哪些具体输入或调用路径涉及该变更，哪些被排除在外？
它出现了哪些可观察到的故障——用户实际看到的现象，而非"类型错误"。
更新时会出现哪些问题，为何该变更仍然正确？

问题何时出现？可使用

git log -S '<移除的表达式>' -- <路径>

或

git blame -L '<行号>,+1'

命令查询。

测试用例验证了什么？列出具体案例，不要仅写"添加测试"。
你注意到了哪些内容并刻意未修复？

绝不编造来源。哈希值仅当本次会话中命令返回时才出现；命名的调用路径必须是从源代码中读取到的。若无结果则跳过该段落，不要模糊表述为"可能已损坏一段时间"。

使用简洁的语言和短句。每个段落以过去式动词开头，下一句说明原因（以行为表述）。

从注释清理过程中获得的设计理由可回答问题1——将其融入该段落，而非作为块内容追加。

当前状态中找到的项目规范优先于上述所有规则。部分仓库会限制正文宽度或完全禁止段落格式。

最后一段之后不得追加任何内容——详见步骤5中的尾部信息规则。

Out of scope

超出范围的操作

Pushing, opening PRs, switching branches.
Splitting into multiple commits.
Rewriting history beyond a single
```
--amend --no-edit
```
.
Adding files listed in
```
.gitignore
```
via
```
-f
```
.

推送代码、创建PR、切换分支。
拆分为多个提交。
除单次
```
--amend --no-edit
```
外的历史重写操作。
通过
```
-f
```
添加
```
.gitignore
```
中列出的文件。",