Skip to content

SKILL.md

Latest commit

 

History

History
211 lines (151 loc) · 8.37 KB

SKILL.md

File metadata and controls

211 lines (151 loc) · 8.37 KB
Raw
name agent-commit
description 跨项目 Git 提交规范。当用户要求提交代码、写 commit message、整理改动准备提交时使用。覆盖 Conventional Commits、分类提交、文件粒度、绝对禁止 Agent/大模型/IDE trailer（如 Co-authored-by: Cursor）、Agent 仅在用户明确要求时 commit、不执行 push。scope 枚举与 trailer 以本仓 AGENTS.md 为准。按意图触发。

Git 提交规范（通用核心）

目标

生成规范、准确、可追溯的 Git 提交。message 与 staged 文件一一对应；按模块 / 主题分类；控制单条文件数。

触发场景

  • 用户要求提交 / commit / 写 commit message / 整理改动提交
  • 用户未要求时：不主动 commit、更不 push（交付结果 ≠ 提交）

前置：读取暂存区与最近提交

git status --short
git diff --cached --stat
git diff --cached
git log --oneline -10

禁止不读 git diff --cached 就写 message；禁止只根据文件名猜测。

Commit 格式

<type>(<scope>): <subject>
# 或
<type>: <subject>
字段 约定
type feat · fix · docs · style · refactor · perf · test · build · ci · chore · revert · release（本仓可增减，以 AGENTS.md 为准）
scope 可选；取值以本仓 AGENTS.md 的 scope 表为准（应用名 / 包名 / 模块名）
subject 祈使、简洁；写「为何改」与关键变化点；语言风格贴近 git log

type 速查

type 场景
feat 新功能
fix 修复
docs 文档
refactor 重构（无行为变化）
perf 性能
style 格式/样式
test 测试
build 构建/依赖
ci CI
chore 杂项
revert 回滚
release 发版（若本仓使用）

Subject / Body 反引号（Markdown 可读）

涉及英文单词、短语、标识符、路径、变量、API、配置键时，用 Markdown 反引号包裹，便于 GitHub / 文档渲染：

宜加 `...` 示例
包名 / 应用名（正文中） `@142vip/utils` · `fairy-cli`
变量 / 常量 / 类型 `compactMap` · `DateFormatTemplate` · `TTL`
路径 / 路由 / 文件 `/api/v1` · `.agents/skills` · `sidebar.ts`
英文专名 / 协议词 `OIDC` · `CDN` · `ESM`

中文产品简称一般不加反引号。

feat(@142vip/utils): `vipLodash` 挂载 `compactMap` 与 JSON 守卫
fix(docs): 补充 `BaseVo` 使用说明

发版类 commit（若本仓使用 release type）

  • message 前缀须与 CI 触发规则逐字匹配（如 release(<pkg>): publish `vX.Y.Z`）；前缀写错 → 流水线不触发
  • 发版前与用户二次确认清单与顺序；一次只处理一个模块（CD 只看 HEAD commit message）
  • 错误 message 已推送时：禁止 force push；可补同版本空 commit 修正 message，由用户手动推送

分类提交（强制）

用户要求交付/整理/提交时，禁止把多类改动揉进单个 commit。

应用或包
  → 功能域 / 模块
    → 单次改动主题
原则 要求
边界 scope 与 staged 路径一致；避免跨无关 app 混提（边界见 AGENTS.md）
主题 一条 commit 一个共同目的
文件数 默认 ≤15 个路径；超出再拆（本仓可另行规定）
暂存 只 git add 本批路径；禁止随手 git add -A
可编译 每批尽量保持中间态可构建

建议顺序（同模块内）：类型/接口 → 数据/常量 → 工具 → 配置 → 组件/页面 → 文档

文案真实性（强制）

  • 标题/正文与 git diff --cached --name-only 可追溯对应
  • 禁止标题写 A 却 stage B
  • 禁止空洞套话单独成句（「优化体验」「提升稳定性」）
  • 优先「为何改」与关键变化点

Commit trailer（绝对禁止）

规则 要求
默认 只写 type(scope): subject 与必要正文；零 trailer
绝对禁止 message 中出现任何 Agent / IDE / 大模型 品牌痕迹，包括但不限于：Co-authored-by: Cursor <cursoragent@cursor.com>、Made-with: Cursor、Claude / GPT / Copilot / Codex 等 Co-authored-by、Generated by …、via Agent
message 正文 即使用词描述「清理署名」，也禁止在 subject/body 写 IDE/Agent 品牌名；用「工具署名」「共署名字样」等中性表述
用户署名 仅当用户明文要求某一固定行时才追加；格式以本仓 AGENTS.md 为准；仍禁止上表产品 trailer
勿信设置 IDE / CLI 的 Commit Attribution 已关仍可能被 Agent Shell 注入 trailer；不得以「用户已关设置」跳过清 trailer

铁律：宁可不写 trailer，也不允许把 Cursor / Agent / 大模型写进 git 历史。

Commit 后清 trailer（强制 · 每条 commit）

Cursor Agent 经 Shell 执行 git commit 时，环境可能在 message 之外追加 Co-authored-by: Cursor …（与 HEREDOC 内容无关）。skill 层兜底：每条 commit 成功后立即执行下方步骤，未 push 前提下允许且必须 git commit --amend 仅用于剔除禁止 trailer（不算「擅自 amend」）。

禁止 trailer 行模式（整行删除，大小写不敏感）：

  • Co-authored-by: Cursor …
  • Made-with: Cursor
  • 含 cursoragent@cursor.com 的 Co-authored-by:

Agent 每条 git commit 成功后必须执行（可复制；多批提交时每条各跑一次）：

strip_commit_message() {
  git log -1 --format=%B | sed -E \
    '/^[[:space:]]*Co-authored-by:[[:space:]]*Cursor /Id;/^[[:space:]]*Made-with:[[:space:]]*Cursor/Id;/^[[:space:]]*Co-authored-by:.*cursoragent@cursor\.com/Id' \
    | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}'
}

raw="$(git log -1 --format=%B)"
clean="$(strip_commit_message)"
if [ "$raw" != "$clean" ]; then
  git commit --amend -m "$clean"
fi
git log -1 --format=%B | grep -Eiq 'Co-authored-by:[[:space:]]*Cursor|Made-with:[[:space:]]*Cursor|cursoragent@cursor\.com' \
  && echo 'FATAL: prohibited commit trailer remains' && exit 1

整轮提交结束后，对本轮新增的每条 commit 再抽查：git log -N --format=%B（N = 本轮条数）均不得含上表禁止行。

未推送且 amend 仍残留：用 git commit-tree 重写该 commit 对象（见各仓 Git 规范深文），禁止带 --no-verify 跳过。

skill 边界：上述流程保证 Agent 遵守时历史干净；无法阻止 IDE 注入本身。若需与 Agent 无关的硬兜底，在仓库加 commit-msg hook（可选，非本 skill 必须项）。

Agent 约束

操作 条件
commit 用户明确要求时可执行；只 stage 相关文件
push agent 不执行；提交完成后列出 commit 摘要，由用户手动 git push
PR 用户明确要求才创建
未要求 commit 不主动提交

其它：

  • hook 失败：修复后新 commit；不 amend 已推送
  • 禁止 --no-verify、对主分支 force push（除非用户明确要求）
  • 禁止改 git config

执行补充

  • 工作区已有大量无关 diff 时不要混入本批
  • commit 失败先修再新 commit；仅为剔除禁止 trailer 的 git commit --amend 允许（见上节）；其它擅自 amend 禁止；push 一律由用户手动

执行步骤

门闩：仅当用户明确要求提交（commit / 写 message / 整理改动提交）时才进入本流程；未要求 → 不 stage、不 commit、不 push，到此为止仅交付结果。

  1. 读 status / cached diff / 近期 log
  2. 暂存区空 → 说明无法提交
  3. 归纳主语义；多类则拆批
  4. scope / 文风对齐本仓与 git log
  5. 分批 git add + git commit
  6. 每条 commit 后立即执行「Commit 后清 trailer」脚本；失败则停止，不得继续下一批或 push
  7. 整轮结束后对本轮全部 commit 做 %B 抽查

边界情况

  • 多类混杂：诚实概括或拆 commit，不假装单一目的
  • 过于分散：可用较宽 chore 概括，仍须可追溯
  • push：agent 不执行；提交完成后给出 commit 摘要，由用户手动 git push

参考

  • 项目 L0：AGENTS.md §Git
  • 执行管线：workflow · 开发：code-dev · 自检 / TODO：self-check