本文用 git-commit 这个具体案例，说明一个生产级 Skill 应该如何从隐性经验出发，被显性化、工程化、评估、改进，并最终集成进团队开发流程。
想了解更多 Skill 的最佳实践，参考：github.com/johnqtcg/aw…。
这个项目的核心目标不是”展示 prompt 怎么写”，而是回答三个更难的问题：
- 高质量 Skill 到底应该如何设计？
- 写出来之后如何证明它真的有效？
- 如何把它融入日常开发与团队工作流？
欢迎大家提交 PR，如果觉得有用，请给 star。
目录
1. skill 的本质
skill 把可复用的领域知识和工作流程封装成独立的、按需加载的模块。它遵循 Agent Skills 开放标准，不绑定单一平台。 它代表了一种工程哲学的转变：把人的经验从“可传授”变成“可执行”。
在任何技术团队中，工程实践以三种形态存在：
隐性知识 显性知识 可执行知识
(在人脑中) (在文档中) (在 Skill 中)
┌──────────┐ ┌──────────┐ ┌──────────┐
│ "提交前要 │ ──→ │ Git 规范 │ ──→ │ git- │
│ 检查密钥" │ 文档化 │ 第6章§2 │ Skill化 │ commit │
│ "message │ │ Commit │ │ SKILL.md │
│ 要写why" │ │ 规范细则 │ │ 7步工作流 │
└──────────┘ └──────────┘ └──────────┘
✗ 依赖记忆 ✗ 依赖阅读 ✓ 自动执行
✗ 不可验证 ✗ 不可强制 ✓ 门禁强制
✗ 随人员流失 ✓ 可沉淀 ✓ 可沉淀+可复用
传统做法止步于第二阶段：写文档、做培训、靠 Code Review 传承。这条链路的根本问题在于，知识的执行完全依赖人的自律和记忆。文档写得再好，忘了看就等于不存在。
Skill 补上了从第二阶段到第三阶段的关键一步：把显性知识自动化。
2. 找到 skill 的用武之地
封装 Skill 要结合实际工作需要，基于可复用的领域知识和工作流程进行封装。可以是固定工作流程、团队沉淀的技术规范，或是针对某个痛点总结的最佳实践。
以 Commit Message 为例。在实际开发中，每个人提交 Commit Message 的格式五花八门——有用中文的、有用英文的，甚至有直接填”11111”的。时间久了连提交者自己都看不懂，更别说给别人看了。
而一个规范化的 Commit Message 能解锁一系列自动化能力：过滤查找（git log --oneline --grep “^feat|^fix”）、生成 Change Log、触发 CI 流程、确定语义化版本号。简言之，让提交历史更可读、更可自动化——这正是适合封装为 Skill 的典型场景。
3. 实战案例
下面我们使用 Anthropic 官方的 skill-creator，把团队的提交规范显性化、自动化，创建一个 git-commit Skill。
前置准备：
- 下载 Anthropic 官方的
skill-creator：github.com/anthropics/… - 如果你使用 Claude Code，将其拷贝到
~/.claude/skills目录下。 - 如果你使用 Codex，将其拷贝到
~/.codex/skills目录下。 - 如果你使用 Cursor，将其拷贝到
~/.cursor/skills目录下。
当然，你也可以显式指定该 Skill 的目录，比如绝对路径，AI 肯定能识别。
3.1 用 Prompt 显性化提交规范
使用 skill-creator skill，封装一个git-commit skill，放到~/.cursor/skills 目录下，要求:
一次 commit 应该是一个逻辑完整的变更。遵循以下原则：
1. 原子性 — 不要把不相关的修改混在一个 commit 里。修 bug 和加新功能应该是独立的 commit。
2. 描述"为什么"而不是"做了什么" — 代码 diff 已经展示了"做了什么"，commit message 应该解释动机。
3. 遵循团队规范 — Conventional Commits 格式：type(scope): description。
4. scope 用于指明本次变更影响的模块或功能域，帮助读者快速定位变更范围：
- 模块名：auth, api, db, config
- 包名：handler, repository, middleware
- 功能域：connection-pool, rate-limit
5. subject 规则
- 不超过 50 字符——GitHub 等平台在列表视图中会截断过长的标题
- 使用动词原形开头：add, fix, update, remove, refactor
- 不加句号
- 描述"做了什么"而非"改了哪个文件"
6. body 规则
- body 用于详细描述变更的动机和前后对比，适合以下场景：
- 解释为什么需要这个变更（而非重复描述做了什么）
- 记录设计决策和权衡取舍
- 每行不超过 72 字符（方便在终端中查看 git log）
7. footer（可选）
- BREAKING CHANGE: 不兼容变更说明（会触发 major 版本号升级）
- Closes #123 关联并自动关闭 issue
- Refs: 相关链接或参考文档
示例:
feat(connection-pool): add idle connection cleanup
Previously idle connections were never cleaned up, leading to
resource exhaustion under sustained load. This adds a background
goroutine that periodically closes connections idle for more than
ConnMaxIdleTime.
Closes #245
另外，需重点解决以下问题：
仓库状态异常时仍然提交-把冲突、rebase 中间态、detached HEAD 一起提交进去；
暂存范围失控-把不相关改动、临时文件、子模块指针一起带进 commit；
敏感信息泄漏-API Key、私钥、数据库 URI 进入版本库；
提交前不做质量验证-测试没跑过，坏变更进入主分支；
message 看似规范但语义失真-scope 瞎编、subject 过长、一个 commit 混杂多个意图。
这段 Prompt 的设计有三个值得注意的决策：
- 正面规范与反面痛点并行。前半部分定义"好的提交长什么样"（Conventional Commits 格式、subject 规则、body 规则），后半部分列举"坏的提交是怎么产生的"（仓库状态异常、暂存范围失控、敏感信息泄漏等）。这种双向约束比单纯给正面规范更有效——LLM 天然倾向于"宁可多做不漏做"，明确的反面约束能抑制过度行为。
- 从"描述什么"到"解决什么"。Prompt 不是在复述 Git 文档，而是围绕 5 个具体的工程痛点组织需求。这让生成的 Skill 天然具备门禁结构，而不仅仅是一份格式模板。
- 精度梯度。format 规则给出精确约束（subject ≤ 50 字符、每行 ≤ 72 字符），而 scope 和 body 只给出原则性指导。这种"脆弱操作给精确规则、灵活操作给原则描述"的做法，对应的正是 Skill 设计中的自由度分级模式。
将以上 Prompt 交给 AI（如 Claude Sonnet 4.6），即可生成对应的 git-commit Skill。
3.2 skill 对齐结果
| Git 规范主题 | 当前文档主题 | Skill 对齐状态 |
|---|---|---|
| 原子性提交：一次 commit 只做一件事 | 提交粒度与分块暂存实践 | ✅ Hard Rule + git add -p 默认策略 |
| 描述“为什么”而非“做了什么” | 提交信息的 body 写法 | ✅ body 必须回答 “why it changed” |
| 遵循团队 commit 规范 | 提交消息约定 | ✅ Conventional Commits 全套规则 |
| Conventional Commits 格式 | 标题格式规范 | ✅ type(scope): subject 完全一致 |
| type 类型覆盖 | 类型约定与例外处理 | ✅ 超集，额外支持 build、revert |
| subject ≤ 50 字符 | 标题长度约束 | ✅ 与 GitHub 截断阈值对齐 |
| body 解释“为什么改” | 正文职责边界 | ✅ what 与 why 职责分离 |
| footer 规范 | footer / issue 关联规范 | ✅ BREAKING CHANGE + Closes # + Refs: |
--amend 安全警告 | 历史改写与 force push 风险 | ✅ 含已 push 场景的 force push 风险提示 |
这 9 条规范全部覆盖。关键转变不在于 Skill 重复了文档的内容，而在于它改变了知识的执行方式：从”请查阅 Git 规范”变成了”不符合规范就不允许提交”。
不过，规则存在 ≠ 规则有效。以 secret 检测为例，虽然规则已写入 Skill，但初版在实际使用中误报严重（详见第 5 章）。对齐验证只是起点，真正的质量验证还要靠 A/B 测试（第 4 章）和持续迭代（第 5 章）。
3.3 生成产物：SKILL.md 关键片段
上面的对齐表验证了”规则都在”，但 Prompt 的设计意图最终是怎么落地的？我们来看生成的 git-commit SKILL.md 中的四个关键片段（完整版见 github.com/johnqtcg/aw… skills/git-commit/SKILL.md）。
片段 1：7 步工作流结构
Prompt 中的 5 个痛点（仓库状态异常、暂存失控、敏感泄漏、质量未验证、message 失真）被转化为 7 步串行门禁：
1. Preflight ← 仓库状态异常 → 6 项检查（conflict/detached HEAD/rebase 等）
2. Staging ← 暂存范围失控 → >8 文件强制确认 + 逻辑分组 + git add -p
3. Secret gate ← 敏感信息泄漏 → 正则扫描 + 4 级过滤
4. Quality gate ← 质量未验证 → 生态检测 + 对应测试/lint 命令
5. Compose message ← message 失真 → scope 发现算法 + subject ≤ 50 字符硬规则
6. Commit ← --amend 风险 → 默认禁止 amend + hook 适配
7. Post-commit report → hash + 文件摘要 + 门禁状态
注意 Prompt 中的每个痛点都对应到了具体的工作流步骤——这就是”从描述什么到解决什么”在产物中的体现。
片段 2：Secret 检测与 4 级过滤
Prompt 要求”解决敏感信息泄漏”，生成的 Skill 将其具体化为正则模式扫描 + 分级过滤：
# Content gate（12+ 种密钥模式）
SECRET_PATTERNS='(AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36}|sk-[A-Za-z0-9]{20,}|...)'
# 4 级过滤（按顺序，首次命中即决定）
| # | Filter | Auto-dismiss when |
|---|--------------------|-----------------------------------------|
| 1 | Project allowlist | 路径匹配 .commit-secret-allowlist |
| 2 | Test/fixture path | 路径含 /test/、/mock/、/testdata/ 等 |
| 3 | Documentation file | 扩展名为 .md、.rst、.adoc |
| 4 | Comment line | 行首为 //、#、--、/* 等注释标记 |
这正是 §3.1 中”精度梯度”的产物：高置信模式（AWS Key、GitHub PAT）用精确正则，过滤层用路径和行级规则逐步排除误报。
片段 3：Scope 发现算法
Prompt 只说”scope 用于指明变更影响的模块”，但生成的 Skill 将其转化为可执行的算法：
git log --oneline -30 | grep -oE '^[0-9a-f]+ [a-z]+([a-z0-9_-]+):' | sort | uniq -c | sort -rn
# >= 3 commits with the same scope → 使用该 scope
# < 3 per scope → 省略 scope，使用 <type>: <subject>
# Never invent a scope not in the canonical set.
规则”永远不要发明不在历史中的 scope”是一个典型的反例约束——LLM 倾向于”合理推测”一个 scope 名称，这条规则阻止了这种行为。
片段 4：Post-commit 报告（输出契约）
每次提交结束后，Skill 输出结构化报告：
commit hash, final subject, changed files summary, quality gate status (ran / skipped / not detected).
这保证了每次提交的结果可审计，也为后续 CI 流程提供了标准化的输入。
4. 评估
Anthropic 官方的 skill-creator 不仅能帮助我们创建 Skill，还提供了完整的评估框架。它通过设计多个针对性场景的 A/B 测试，以实际测试数据帮助我们准确判断 Skill 的实际能力和价值，并给出迭代改进方向。
4.1 skill-creator 的评估框架
skill-creator Skill 的目录结构如下：
skill-creator/
├── SKILL.md
├── agents/
│ ├── grader.md # 定级打分
│ ├── comparator.md # 比较(with skill和without skill)
│ └── analyzer.md # 分析
├── references/
│ └── schemas.md
├── scripts/
│ ├── run_eval.py # 运行评估脚本
│ ├── run_loop.py # 循环脚本
│ ├── improve_description.py # 提升描述精确度脚本
│ ├── generate_report.py # 生成评估报告脚本
│ ├── utils.py
│ ├── aggregate_benchmark.py # benchmark基准测试数据聚合脚本
│ ├── package_skill.py
│ └── quick_validate.py # 快速验证脚本
├── eval-viewer/
│ ├── generate_review.py # 生成评审脚本
│ └── viewer.html
├── assets/
│ └── eval_review.html （description optimization 审查界面）
└── LICENSE.txt
这套评估框架的意义远超单个 Skill 的质量验证。它为 Skill 生态提供了质量基础设施：
- 可比较：不同 Skill 之间可以用相同维度对比，如触发率、信噪比、ROI。
- 可复现：评估场景和数据固化为
JSON/Markdown，任何人可以重跑验证。 - 可迭代：评估数据精确指向改进方向，不再“凭感觉”修改。
- 可信赖：经过量化验证的 Skill 可以更放心地集成到 CI/CD 流程中。
如果说 Skill 是 AI Agent 的“专业能力”，那么评估框架就是确保这些能力真实有效的“质检体系”。没有质检的工厂无法规模化生产，没有评估的 Skill 生态也很难真正繁荣。
4.2 评估维度
我们从三个维度量化评估 Skill 的实际价值：
| 维度 | 核心问题 | 度量方式 |
|---|---|---|
| 触发准确率 | Skill 能不能在该用的时候被触发、不该用的时候不被触发？ | 设计正例/负例查询集，计算 Recall + Precision |
| 实际任务表现 | 用了 Skill 之后，输出质量是否比不用更好？ | with-skill vs without-skill A/B 对照实验 |
| Token 效费比 | 多花的 token 值不值？ | 额外 token 成本 vs 开发者时间节省，计算 ROI |
使用 skill-creator 执行评估时，只需用自然语言描述评估目标：
使用 skill-creator skill 从触发准确率、实际任务表现、token 效费比三个维度
评估 git-commit skill 的价值，生成评估报告（.md 格式）。
AI 会自动完成以下步骤：设计 A/B 测试场景 → 运行 with-skill / without-skill 对照 → 计算各维度指标 → 生成评估报告。以 git-commit Skill 为例，实际评估覆盖了 3 组对照场景（标准提交、敏感内容扫描、多关注点分组）和 20 条触发准确率查询。
4.3 关键结果
最后生成了评估报告，关键数据和结论如下所示。
A/B 测试综合 Benchmark
| Eval | with_skill Pass Rate | without_skill Pass Rate | 提升幅度 |
|---|---|---|---|
| Eval 1：标准提交 | 100% (7/7) | 43% (3/7) | +57pp |
| Eval 2：敏感扫描 | 100% (5/5) | 40% (2/5) | +60pp |
| Eval 3：多关注点分组 | 100% (6/6) | 33% (2/6) | +67pp |
| 总计 | 100% (18/18) | 39% (7/18) | +61pp |
Blind Compare 判定：with_skill 在全部 3 个场景中胜出（3-0）。
Skill 价值总结
高价值场景（ROI 极高）
| 场景 | skill 作用 | 无 skill 风险 |
|---|---|---|
| 有敏感文件的仓库提交 | 系统性正则扫描 12+ 密钥类型，有 4 级过滤防误报 | 随机漏报，依赖 AI 视觉识别，不可靠 |
| 多文件混合改动 | 强制逻辑分组 + 结构化询问 + 原子性约束 | 可能建议但不强制，用户易忽略 |
| scope 发现 | 算法化分析 git log 30 条，决定是否含 scope | 凭经验猜测，风格不一致 |
| 预检 pre-flight | 7 项系统检查（rebase / merge / conflict / detached HEAD 等） | 完全缺失 |
边际价值场景（ROI 中等）
| 场景 | 说明 |
|---|---|
| 生成 Conventional Commits 消息 | without_skill baseline 已能生成合理消息，Skill 仍有提升但并非不可替代 |
| Subject 长度控制 | 重要，但可以通过简单 system prompt 规则部分替代 |
综合评分
| 维度 | 分数（/10） | 说明 |
|---|---|---|
| 安全保护价值 | 9.5 | 系统性密钥扫描，4 级过滤防误报 |
| 工作流纪律价值 | 9.0 | 原子性约束、分组询问、预检缺一不可 |
| 消息质量价值 | 7.5 | scope 发现和 subject 长度约束带来真实提升 |
| 触发准确率 | 6.5 | F1=0.78，YAML 格式有风险，边界场景易误触 |
| Token 效费比 | 7.0 | 5.7× 成本，但安全价值加权后完全合理 |
| 综合 Skill 价值 | 8.2 | 强烈推荐使用，尤其对重视代码安全的团队 |
但这些数据也有明确的边界：
- 场景覆盖有限：3 组 A/B 测试无法穷尽所有提交场景，monorepo 大批量提交、merge commit、submodule 变更等场景未被覆盖。
- 触发准确率是最大短板：F1=0.78 意味着约 22% 的边界查询会被错误触发或遗漏，这也是 4.4 节改进建议的直接来源。
- 受控环境 vs 真实环境：A/B 测试未模拟真实仓库中的文件复杂度、
.gitignore配置和 pre-commit hook 冲突。
所以评估不是给 Skill 盖章"合格"，而是精确定位下一步该改什么——这正是第 5 章迭代的起点。
4.4 改进建议
最后，AI Agent 基于测试数据给出了针对性改进建议。
Description 修复（高优先级）
# 当前（有问题）
description: >-
安全、规范地创建 Git 提交：...
# 建议（单行，无 block scalar）
description: "安全、规范地创建 Git 提交，扫描敏感信息、运行质量门禁并生成 Conventional Commits 英文消息。触发词：commit、git commit、帮我提交、提交代码、生成 commit message。不触发：git push、squash、revert、cherry-pick。"
Secret Patterns 补充（中优先级）
在 SECRET_PATTERNS 中补充 JSON 格式的 secret 匹配：
"(secret|password|token|api_key|apikey)"\s*:\s*"[^"]{12,}"
以覆盖当前的 "aws_secret": "key" 等 JSON 键值格式漏报。
SKILL.md Token 瘦身（低优先级）
将 SECRET_PATTERNS 正则表达式提取到 references/secret-patterns.md，按需加载，估计节省约 1000 chars。
4.5 基于评估的定向改进
有了基于实际测试数据的改进建议，就可以指示 AI Agent 对 Skill 做定向修复。关键是按优先级排序执行：
| 优先级 | 改进项 | 预期效果 |
|---|---|---|
| 高 | Description YAML 格式修复 + 触发边界精确化 | 提升 F1 从 0.78 → 0.90+ |
| 中 | SECRET_PATTERNS 补充 JSON/YAML 键值格式 | 修复已知的结构化密钥漏报 |
| 低 | 补充 --amend 边界说明 | 消除 trigger 歧义 |
每一项改进都可追溯到具体的评估数据——这正是"数据驱动改进"与"凭感觉修改"的根本区别。
5. 迭代
Skill 和项目代码一样，是需要持续维护和迭代的数字资产。一个 Skill 的质量不是一次性写出来的，而是通过实战暴露问题 → 分析根因 → 调整设计 → 验证效果的循环打磨出来的。
第 4 章展示了如何用量化评估驱动改进，但迭代还有另一个同样重要的驱动力：日常使用中的观察和反馈。下面用两个真实案例说明这个循环如何运转。
5.1 案例一：secret 检测误报控制
发现的问题：git-commit Skill 的 secret 检测在实际使用中误报严重。password=、token=、secret= 等通用模式频繁命中测试文件、文档和示例配置（如 config.example.yml 中的 password=changeme）。初版设计是”命中就阻断”，没有 allowlist / suppression 机制，导致开发者频繁被打断。
根因分析：初版把所有 secret 模式平等对待——AKIA0EXAMPLE1234（AWS Key，结构化 token，假阳性极低）和 password=changeme（通用键名，假阳性极高）触发了相同的阻断逻辑。这是一个典型的精度梯度缺失问题。
改进方案（5 项改动）：
| # | 改动 | 解决的问题 | |
|---|---|---|---|
| 1 | SECRET_PATTERNS 拆为 Tier1（结构化 Token）和 Tier2（通用键名） | 区分高低置信模式，分级处置 | |
| 2 | 新增行级内联抑制（# nosec / # git-commit-allow） | 已确认安全的误报有标准出口 | |
| 3 | 路径过滤扩展至 /examples/、.template.、.dist 等 | 覆盖示例配置的常见存放位置 | |
| 4 | Tier2 命中增加值分析三档处置（忽略/软警告/硬阻断） | password=changeme 自动忽略，高熵值才阻断 | |
| 5 | 提交报告附加 `Secret scan: T1=0 | T2=3→2 suppressed` 摘要 | 扫描决策可审计，不再静默通过 |
验证：改进后再次执行 A/B 测试，敏感扫描场景的 with-skill 通过率维持 100%，同时对示例配置文件的误报从 ~60% 降至 <5%。
5.2 案例二：scope 发现的一致性
发现的问题：git-commit Skill 通过分析 git log 最近 30 条记录来决定 scope 的写法。但在新仓库或刚切换分支的场景下，历史记录不足 30 条，scope 建议变得不稳定——有时加 scope，有时不加，同一模块的 scope 名称也不一致。
根因分析：算法对历史数据的依赖没有设置下限。当样本不足时，统计结果不可靠，但 Skill 仍然输出了看似确定的建议。这是一个诚实降级缺失的问题——Skill 应该在数据不足时明确告知用户，而不是给出不可靠的建议。
改进方案：
- 当
git log记录 < 10 条时，scope 改为可选，并提示”历史记录不足，建议手动指定 scope” - 添加 scope 一致性检查：如果最近 10 条同模块提交中 scope 写法不统一，输出警告
这个案例体现了一个重要原则：Skill 可以拒绝给出不可靠的建议，这比”总是给建议但有时是错的”更值得信赖。
5.3 迭代的边界
不是所有 Skill 都需要无限迭代。以下信号表明迭代可以暂停或停止：
| 信号 | 含义 |
|---|---|
| A/B 测试中 with-skill 与 without-skill 差异 < 10% | Skill 的差异化价值不足，考虑简化或合并 |
| 连续 3 次迭代未改变评估分数 | 已接近当前架构的天花板，需要根本性重构或接受现状 |
| 实际使用中被跳过的频率 > 30% | Skill 与开发者工作流存在摩擦，需要审视定位 |
| Token 消耗持续增长但 ROI 下降 | 过度复杂化，考虑拆分为多个轻量 Skill |
Skill 的迭代应遵循与代码相同的版本管理实践：每次改进提交到 Git，附带清晰的 commit message 说明改了什么、为什么改。这样团队中的任何人都可以追溯 Skill 的演进历史，理解每个设计决策的背景。
每次改动后，都可以再让 AI Agent 基于 skill-creator 做针对性评估——这正是”评估 → 改进 → 再评估”以及”实践驱动 → 迭代 → 再评估”的双循环。
6. 集成到开发流程
Skill 的真正价值不是孤立使用，而是串联到开发流程的关键节点，形成质量管线。
6.1 四级部署建议
Skill 支持四级部署，高优先级覆盖低优先级：
| 优先级 | 位置 | 路径 | 适用场景 |
|---|---|---|---|
| 1（最高） | 企业级 | 托管设置统一下发 | 全组织安全审查规范、合规检查 |
| 2 | 个人级 | ~/.claude/skills/<name>/SKILL.md | 个人写作风格、常用工作流 |
| 3 | 项目级 | .claude/skills/<name>/SKILL.md | 项目特定的代码规范、CI 配置 |
| 4（最低） | 插件级 | <plugin>/skills/<name>/SKILL.md | 跨项目复用的通用能力 |
选择建议
- 安全审查、代码规范：企业级部署，确保全员一致。
- 个人效率工具，如
tech-doc-writer、google-search：个人级。 - 项目专属流程，如特定项目的 CI workflow、PR 模板：项目级，并提交到 Git。
- 团队共享的通用工具：插件发布。
比如开发团队遵循的 git-commit、create-pr、unit-test 等规范，就可以放到项目根目录下的 .claude/skills/ 目录里，让 Skill 跟项目代码一样，作为数字资产不断迭代。
一人开发，团队所有人都可以使用；每个人都可以根据自己实际发现的问题做针对性改进，就像改进代码一样，一人修改，整个团队受益。
6.2 本地开发：Makefile 驱动的质量门禁
go-makefile-writer Skill 帮我们为 Go 项目生成标准化的 Makefile。核心理念是：开发者在 push 之前就应该能捕获 CI 会发现的所有问题（Local Parity）。这个理念不限于 Go——Python 项目可以用 Makefile 封装 pytest + ruff + mypy，Node.js 项目可以封装 jest + eslint + tsc。
以 Go 项目为例，Makefile 中的 ci 目标直接镜像 CI 流程：
ci: fmt-check ci-core ## Local/CI required gate parity checks
ci-core: cover-check lint build-all ## Run coverage gate, lint, build
本地执行 make ci 和 CI 执行 make ci COVER_MIN=80 是同一条命令——“CI 上红了”的问题在 push 前就能发现。
6.3 CI 流程：Skill 驱动的自动化门禁
CI workflow 是 Makefile 目标的薄封装层。以下为 Go 项目的典型配置（需根据自己的项目适配工具版本和目标名称）：
# .github/workflows/ci.yml（示例，需适配）
jobs:
ci:
steps:
- name: Install golangci-lint
run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.6.2 # 请检查最新版本
- name: Run CI gate
run: make ci COVER_MIN=80
docker-build:
steps:
- name: Build image
run: make docker-build
每个 CI job 委托给一个 Makefile 目标。开发者在本地跑 make ci，CI 也跑 make ci，流程完全一致。
6.4 代码审查：AI 驱动的 PR Review
代码审查类 Skill（如 go-code-reviewer）可以集成到 CI 中，对每个 PR 自动执行审查。以下为使用 claude-code-action 的典型配置（需根据项目适配 Skill 路径和 Prompt）：
# .github/workflows/claude-code-review.yml（示例，需适配）
name: Claude Code Review
on:
pull_request:
branches: [master, main]
types: [opened, synchronize]
jobs:
review:
steps:
- uses: anthropics/claude-code-action@v1.0.3 # 请检查最新版本
with:
prompt: |
Read .claude/skills/go-code-reviewer/SKILL.md,
get the PR diff via `gh pr diff`,
select review mode (Lite/Standard/Strict),
execute the full review workflow,
post findings as PR comments.
工作流 YAML 只做编排，所有审查逻辑都在 Skill 中。更新审查标准只需更新 Skill 文件，无需修改 CI 配置。
6.5 完整的质量管线
把上述环节串联起来，就形成了从编码到合并的完整质量管线：
编码
↓
make fmt / make lint（本地质量检查，go-makefile-writer 生成）
↓
git commit（git-commit skill：安全扫描 + 质量门禁 + 规范化 message）
↓
git push
↓
create PR（create-pr skill：8 道门禁 + 结构化 PR body）
↓
CI 触发
├── make ci（格式 + 测试 + lint + 覆盖率 + 构建）
├── make docker-build（容器镜像验证）
├── Claude Code Review（go-code-reviewer skill：自动代码审查）
└── govulncheck（依赖漏洞扫描）
↓
人工审查 + 合并
每个环节都有对应的 Skill 提供保障，且本地和 CI 保持一致。
6.6 团队落地策略
Skill 的技术集成只是一半，另一半是团队接受度。以下是经过验证的渐进式推广路径：
第一阶段：个人试点（1-2 周）。由 1-2 名对 AI 工具熟悉的成员先在日常工作中使用 Skill，收集真实的正面案例和问题反馈。这个阶段的目标不是推广，而是积累说服团队的证据。
第二阶段：可选启用（2-4 周）。将 Skill 提交到项目的 .claude/skills/ 目录，但不强制使用。在团队会议上用第一阶段的真实案例（如"Skill 拦截了一次密钥泄漏"）展示价值。关键原则：用证据说服，不用行政命令强推。
第三阶段：CI 门禁集成。当团队大多数成员已经在自愿使用 Skill 后，再将其集成到 CI 流程中作为质量门禁。此时团队对 Skill 的行为已有预期，CI 集成不会产生意外摩擦。
常见阻力与应对：
| 阻力 | 应对 |
|---|---|
| "Skill 拖慢了我的提交速度" | 先检查是否是误报过多（见 5.1），优化后再推广 |
| "我不信任 AI 生成的审查意见" | 初期可将 Skill 输出设为建议模式而非阻断模式 |
| "规范太死板，不适合我的场景" | 给 Skill 增加合理的降级和豁免机制（见 5.2 诚实降级） |
7. 小结
本文围绕 git-commit 这个案例，完整走了一遍打磨生产级 Skill 的路径：
- 概念：Skill 的本质是把隐性知识从"可传授"变成"可执行"。
- 案例：用 Prompt 显性化提交规范，生成可执行的 Skill——关键是双向约束（正面规范 + 反面痛点）和精度梯度。
- 评估：用 A/B 测试量化 Skill 的真实收益和短板——但评估数据有局限，不能替代持续的实战验证。
- 迭代：从日常使用中发现问题（误报、降级缺失），通过”发现 → 根因 → 改进 → 验证”循环打磨——同时知道何时停止。
- 集成：串联本地开发、CI 和 PR Review 形成质量管线——渐进式推广比一步到位更有效。
换句话说，生产级 Skill 不是”一段写得漂亮的 Prompt”，而是一套可以落地、可验证、可维护、可集成的工程资产。
