参考资料

• Agent Skills 规范
• MCP 规范

Skill（09） - 从零实现代码审查 Skill

读完后，你应能完成以下任务：

• 绘制“Skill（09） - 从零实现代码审查 Skill / 实战目标”的关键对象与数据流，解释“我们要做的技能 code-review：用户贴一段代码（或给个文件），它按固定维度审查，输出一张带严重等级的问题表，并能调脚本做一些机械检查（如找硬编码密钥、空 catch）。”，并用源码位置、日志或 Trace 标注证据。
• 为“Skill（09） - 从零实现代码审查 Skill / 第 1 步：需求拆解（先想清楚再动手）”设计正常与异常输入，验证“它干一件事吗？ 是——只做代码审查（不做改写、不做生成）。✅ 单一职责。 -> 什么时候该触发？ 用户说「看看这代码」「审查下」「有没有 bug / 安全问题」。→ 这些是 description 的钩子。 -> 审查哪些维度？ 安全、正确性、规范、测试。→ 这些做成清单。 -> 哪些检查能自动化？ 找硬编码密钥、空 catch、危险函数。→ 这些交给脚本，结果再让 Claude 综合判断。”，输出首个偏差位置与回归测试结果。
• 实现“Skill（09） - 从零实现代码审查 Skill / 第 2 步：设计目录结构”的最小代码或配置，检验“符合第 06 章心法：正文薄，清单和脚本沉到第 3 层。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：把前八章的知识串起来，从零设计并实现一个真实可用的「代码审查」技能。学完你会得到一个完整项目——含元数据、正文、清单、脚本。

一、实战目标

我们要做的技能 code-review：用户贴一段代码（或给个文件），它按固定维度审查，输出一张带严重等级的问题表，并能调脚本做一些机械检查（如找硬编码密钥、空 catch）。

这个例子好在它用全了前八章：

用到的知识	来自
判断该不该做成技能	01
目录结构、入口	03
规范的 frontmatter	04
高触发率 description	05
渐进式披露、内容分层	06
清单作为资源文件	07
机械检查交给脚本	08

二、第 1 步：需求拆解（先想清楚再动手）

动手前，问自己四个问题：

1. 它干一件事吗？ 是——只做代码审查（不做改写、不做生成）。✅ 单一职责。
2. 什么时候该触发？ 用户说「看看这代码」「审查下」「有没有 bug / 安全问题」。→ 这些是 description 的钩子。
3. 审查哪些维度？ 安全、正确性、规范、测试。→ 这些做成清单。
4. 哪些检查能自动化？ 找硬编码密钥、空 catch、危险函数。→ 这些交给脚本，结果再让 Claude 综合判断。

三、第 2 步：设计目录结构

code-review/
├── SKILL.md                      # 入口：流程 + 指路
├── reference/
│   └── checklist.md              # 审查维度清单（第 3 层，按需加载）
└── scripts/
    └── scan.py                   # 机械扫描脚本：找硬编码密钥、空 catch 等

符合第 06 章心法：正文薄，清单和脚本沉到第 3 层。

四、第 3 步：写 SKILL.md

---
name: code-review
description: 当用户需要审查代码质量、查找 bug、检查安全漏洞或代码规范问题时使用。适用于 review 代码、找隐患、把关提交的场景。
---

# 代码审查

对用户提供的代码做系统性审查，输出可执行的改进建议。

## 流程
1. 先运行机械扫描：`python scripts/scan.py <代码文件路径>`，拿到「疑似硬编码密钥、空 catch」等线索。
2. 再逐项对照 `reference/checklist.md` 做人工维度的审查。
3. 综合脚本线索 + 清单结果，输出一张表格，每个问题含：位置、问题、严重等级（高/中/低）、修复建议。
4. 最后给一句总体评价。

## 注意
- 脚本只给「线索」，是否真有问题由你结合上下文判断，不要照搬。
- 没有问题的维度也要说明「已检查、无问题」，让用户安心。

逐处呼应前面的章节：

• description 用了第三人称 + 场景 + 用户大白话（review、找隐患、把关提交）——第 05 章。
• 正文只写流程主干，清单和脚本都用「指路」引用——第 06、07、08 章。
• 流程把「运行脚本」明确写成第 1 步——第 08 章。

五、第 4 步：写审查清单（reference/checklist.md）

# 代码审查清单

## 安全
- [ ] 是否有 SQL 注入风险（字符串拼接 SQL）？
- [ ] 是否硬编码了密钥、密码、token？
- [ ] 用户输入是否做了校验/转义？

## 正确性
- [ ] 边界条件（空值、0、负数、超长）是否处理？
- [ ] 异常是否被静默吞掉（空 catch）？
- [ ] 是否有资源泄漏（文件/连接没关）？

## 规范
- [ ] 命名是否清晰、一致？
- [ ] 是否有必要的注释？
- [ ] 是否有重复代码可提取？

## 测试
- [ ] 关键逻辑是否有对应测试？

六、第 5 步：写扫描脚本（scripts/scan.py）

脚本只做「机械能做对」的事——正则找明显的硬编码密钥、空 catch。判断权仍在 Claude（脚本给线索，不下结论）。完整代码在 Demo 里，跑过验证可用。

七、第 6 步：组装与测试

把三个文件按结构放好，复制到 ~/.claude/skills/code-review/，然后用第 02 章的方法测触发：

「帮我审查下这段登录代码……」

确认它被触发、跑了脚本、对照了清单、输出了表格。这就是一个完整、能用、用全了所有知识点的技能。

八、常见错误

• ❌ 职责膨胀：做着做着想让它「顺便改一下代码」「再写个提交信息」。打住——那是别的技能的事，保持单一职责。
• ❌ 脚本下结论：让脚本直接判定「这是 bug」。脚本会误报，应只给线索，由 Claude 结合上下文定夺。
• ❌ 清单塞进正文：维度多，应放 reference/，正文「指路」即可。
• ❌ 描述太窄：写成「审查 Python 代码」，用户贴 JS 就不触发了。

九、最佳实践

• 先需求拆解再动手：四个问题（单一职责？何时触发？查哪些维度？哪些能自动化？）想清楚，结构自然就出来了。
• 脚本与 AI 分工：脚本给线索，Claude 做判断和表达。
• 输出结构化：用表格 + 严重等级，让结果可读、可执行。
• 没问题也要反馈：「已检查、无问题」比沉默更让人安心。

十、动手实践：09 章 Demo · 完整实战：code-review 技能

前八章的知识全用上的综合项目。一个能扫、能查、能给结构化报告的代码审查技能。

10.1 结构

code-review/
├── SKILL.md                    # 入口：流程串起脚本和清单
├── reference/
│   └── checklist.md            # 审查维度清单（安全/正确性/规范/测试）
└── scripts/
    ├── scan.py                 # 机械扫描器（找密钥、SQL拼接、eval、空catch）
    └── sample-bad-code.py      # 故意埋雷的示例代码，供演示

10.2 先单独跑扫描脚本

cd code-review
python3 scripts/scan.py scripts/sample-bad-code.py

预期扫出 5 条线索：硬编码密钥、token 串、SQL 拼接、eval、空 catch。

注意脚本只给「线索」不下结论——正则会误报（比如同一行密钥被两条规则各命中一次）。最终判断交给 Claude，这正是第 08 章「脚本给线索、Claude 做判断」的体现。

10.3 装上完整体验

cp -r code-review ~/.claude/skills/

开新会话：

帮我审查下这个文件的代码：<sample-bad-code.py 的绝对路径>

技能会被触发 → 跑扫描脚本拿线索 → 对照清单逐维度审查 → 输出带严重等级的问题表格 → 给总体评价。

10.4 这个技能用全了前八章

知识点	体现在哪
单一职责（01）	只做审查，不改代码
目录结构（03）	SKILL.md + reference/ + scripts/
规范 frontmatter（04）	name/description 合规
高触发 description（05）	覆盖「review、找隐患、把关」等说法
渐进式披露（06）	正文薄，清单/脚本沉第 3 层
清单资源（07）	reference/checklist.md 被正文点名
脚本协作（08）	scan.py 给线索，Claude 做判断

10.5 你会收获什么

• 一个真正可用的完整技能，可作为你做其它技能的模板。
• 把零散知识点串成「能交付的东西」的工程经验。

10.6 配套实践材料

以下材料已并入正文，便于阅读时直接对照和练习。

code-review/reference/checklist.md

# 代码审查清单

逐项核对，每项给出「通过 / 有问题 / 不适用」。

## 安全
- [ ] 是否有 SQL 注入风险（字符串拼接 SQL）？
- [ ] 是否硬编码了密钥、密码、token？
- [ ] 用户输入是否做了校验/转义？

## 正确性
- [ ] 边界条件（空值、0、负数、超长输入）是否处理？
- [ ] 异常是否被静默吞掉（空 catch）？
- [ ] 是否有资源泄漏（文件/连接没关闭）？

## 规范
- [ ] 命名是否清晰、一致？
- [ ] 关键逻辑是否有必要的注释？
- [ ] 是否有明显重复代码可以提取？

## 测试
- [ ] 关键逻辑是否有对应的测试？

code-review/SKILL.md

---
name: code-review
description: 当用户需要审查代码质量、查找 bug、检查安全漏洞或代码规范问题时使用。适用于 review 代码、找隐患、把关提交的场景。
---

# 代码审查

对用户提供的代码做系统性审查，输出可执行的改进建议。

## 流程
1. 先运行机械扫描：`python scripts/scan.py <代码文件路径>`，拿到「疑似硬编码密钥、空 catch」等线索。
2. 再逐项对照 `reference/checklist.md` 做人工维度的审查。
3. 综合脚本线索 + 清单结果，输出一张表格，每个问题含：位置、问题、严重等级（高/中/低）、修复建议。
4. 最后给一句总体评价。

## 注意
- 脚本只给「线索」，是否真有问题由你结合上下文判断，不要照搬。
- 没有问题的维度也要说明「已检查、无问题」，让用户安心。
- 保持单一职责：只做审查，不顺手改代码、不写提交信息。

十一、总结

• 实战目标：我们要做的技能 code-review：用户贴一段代码（或给个文件），它按固定维度审查，输出一张带严重等级的问题表，并能调脚本做一些机械检查（如找硬编码密钥、空 catch）。
• 第 1 步：需求拆解（先想清楚再动手）：它干一件事吗？ 是——只做代码审查（不做改写、不做生成）。✅ 单一职责。 -> 什么时候该触发？ 用户说「看看这代码」「审查下」「有没有 bug / 安全问题」。→ 这些是 description 的钩子。 -> 审查哪些维度？ 安全、正确性、规范、测试。→ 这些做成清单。 -> 哪些检查能自动化？ 找硬编码密钥、空 catch、危险函数。→ 这些交给脚本，结果再让 Claude 综合判断。
• 第 2 步：设计目录结构：符合第 06 章心法：正文薄，清单和脚本沉到第 3 层。
• 第 3 步：写 SKILL.md：正文只写流程主干，清单和脚本都用「指路」引用——第 06、07、08 章。
• 第 5 步：写扫描脚本（scripts/scan.py）：完整代码在 Demo 里，跑过验证可用。
• 第 6 步：组装与测试：确认它被触发、跑了脚本、对照了清单、输出了表格。