Skills 中篇：创建你的第一个 Skill ------ 从零手写 code-review
上篇你学会了安装和使用别人的 Skill。这篇更进一步------从零创建一个属于你自己的 Skill。我们会手把手走完整个流程，最终产出的是一个真正能用的 code-review Skill。
什么时候该写一个 Skill
不是所有重复操作都值得变成 Skill。一个简单的判断标准：
这个操作你重复了多少次？
├─ 1-2 次 → 不值得，继续手写提示词
├─ 3-5 次 → 开始考虑写 Skill
├─ 5-10 次 → 明确应该写 Skill
└─ 10 次以上 → 赶紧写，你在浪费生命以及，以下三类场景是 Skill 的最佳用武之地：
| 场景类型 | 举例 | 为什么适合写成 Skill |
|---|---|---|
| 需要固定流程的任务 | code-review、deploy、security-scan | Checklist 保证步骤不遗漏 |
| 需要统一标准的任务 | api-design、naming-check | 每次输出一致，不受"AI 心情"影响 |
| 团队共享的工作流 | onboarding、release-notes | 一次写好，全团队复用 |
Skill 目录结构逐行拆解
一个完整的 Skill 长这样：
my-code-review/
├── metadata.yml # Skill 的"身份证"------名字、描述、触发条件
├── SKILL.md # Skill 的"大脑"------具体指令和 Checklist
└── references/ # 补充参考资料（按需加载，节省 Token）
├── security-rules.md
└── style-guide.mdmetadata.yml ------ Skill 的"身份证"
yaml
# metadata.yml ------ 每个字段都不能省
name: code-review # 唯一标识符，kebab-case
version: 1.0.0 # 语义化版本
description: > # 一句话说清这个 Skill 做什么（也用于自动匹配）
标准化代码审查流程。检查安全漏洞、错误处理、性能问题、代码风格。
触发条件：用户提到"review"、"审查"、"检查代码"或使用 /review 命令。
author: your-name
license: MIT
tags: [review, quality, security]
trigger: # 触发条件（可选，Claude Code 会自动判断）
keywords: [review, 审查, 检查代码, code review]
commands: [/review]
platforms: [claude-code] # 兼容的平台
min_version: "2.0" # 最低 Claude Code 版本
dependencies: [] # 依赖的其他 Skill 或 MCP Server关键字段说明：
| 字段 | 为什么重要 | 写错会怎样 |
|---|---|---|
name |
唯一标识，/name 手动触发用 |
名字冲突时后者覆盖前者 |
description |
自动匹配的核心依据 | 太模糊则 AI 判别不准，太窄则触发不了 |
trigger.keywords |
增强自动匹配的准确性 | 不写也能靠 description 匹配，但不如显式声明可靠 |
dependencies |
告诉用户这个 Skill 需要什么前置条件 | 用户装了但缺依赖，Skill 可能报错 |
SKILL.md ------ Skill 的"大脑"
这是 Skill 的核心文件，包含 AI 在执行 Skill 时加载的全部指令。
markdown
# Code Review Skill
你是一个资深代码审查专家。每次审查代码时，按以下清单逐项检查，不得跳过。
## 审查清单
### 🔴 安全检查（必须全部通过，一项不通过则拒绝合并）
- [ ] SQL 注入：所有数据库查询是否使用参数化查询？
- [ ] XSS 漏洞：用户输入是否经过转义或使用安全渲染？
- [ ] 密钥泄露：是否有硬编码的 API Key、Token、密码？
- [ ] 路径遍历：文件操作是否校验了路径范围？
- [ ] 反序列化：是否使用了不安全的序列化方式（pickle、eval）？
### 🟡 错误处理（尽量通过，不通过需说明理由）
- [ ] 所有 IO 操作（网络请求、文件读写、数据库查询）是否有 try/except？
- [ ] 异常信息是否清晰？（不能只写 "An error occurred"）
- [ ] 是否有合适的日志记录？
### 🟢 代码质量（参考建议）
- [ ] 函数是否超过 40 行？（超过需说明拆分理由）
- [ ] 变量名是否见名知意？
- [ ] 是否有明显的重复代码？
- [ ] 公开函数是否有 docstring？
## 输出格式
审查结果按以下格式输出：
| 级别 | 问题 | 位置 | 建议修复 |
|------|------|------|----------|
| 🔴 | ... | 文件:行号 | ... |
| 🟡 | ... | 文件:行号 | ... |
| 🟢 | ... | 文件:行号 | ... |
最后给出总结：🔴 X 个 🟡 Y 个 🟢 Z 个
如果有 🔴 级别问题，结论为"❌ 不建议合并"。references/ ------ 按需加载的补充资料
references/ 下的文件只在 AI 认为需要时才加载，不会自动进入上下文。
markdown
# references/security-rules.md
## OWASP Top 10 简表
此文件作为 code-review Skill 的补充参考。
当审查的代码涉及以下场景时，AI 会自动查阅此文件。
### SQL 注入检查
- 任何拼接 SQL 字符串的代码都是 🔴 级别
- 必须使用 ORM 的参数化方法或 Prepared Statement
### XSS 检查
- React 项目中，dangerouslySetInnerHTML 必须人工审查
- 用户输入的富文本需要 DOMPurify 处理
### CSRF 检查
- 所有状态变更请求（POST/PUT/DELETE）必须有 CSRF Token
- API 接口使用 Bearer Token 的可豁免references 的设计原则：
两种设计模式：Checklist 驱动 vs 散文驱动
选择哪种模式，取决于 Skill 的性质。
Checklist 驱动：适合步骤明确的任务
适用场景：code-review、deploy、test-gen、security-scan
特点：
- 步骤明确，可以列成清单
- 每步有明确的通过/不通过标准
- 输出格式可以统一
- AI 的"自由度"低，执行确定性高
优点：
✅ 输出一致性好，不同次执行结果可对比
✅ 不易漏项，清单保证了覆盖率
✅ 适合团队共享------标准统一
缺点：
❌ 不够灵活，遇到清单外的场景可能不适用
❌ 清单维护成本------规则变了要更新散文驱动：适合知识传授型任务
适用场景：onboarding、style-guide、best-practices
特点：
- 不是步骤而是"知识"
- AI 需要根据上下文灵活应用
- 没有固定的通过/不通过标准
- AI 的"自由度"高，更像"咨询师"角色
优点：
✅ 灵活，适用于多种场景
✅ 写起来快，不需要精细拆解步骤
缺点：
❌ 输出一致性差，不同次执行结果差异大
❌ 不好验证------你怎么知道 AI 真的"学会"了？选择框架
你的 Skill 是做什么的？
│
├─ 做检查（review/scan/audit）
│ → Checklist 驱动
│
├─ 做操作（deploy/generate/create）
│ → Checklist 驱动（操作步骤不能漏）
│
└─ 传知识（onboard/explain/guide）
→ 散文驱动进阶技巧：混合模式。SKILL.md 主体用散文驱动解释上下文和原则，但把具体的检查项放在 Checklist 里。既有灵活性，又有确定性。
手把手实战：从零写一个 code-review Skill
第一步：创建目录结构
bash
mkdir -p .claude/skills/my-code-review
cd .claude/skills/my-code-review
touch metadata.yml SKILL.md
mkdir -p references第二步：写 metadata.yml
yaml
name: my-code-review
version: 1.0.0
description: >
个性化代码审查。检查安全漏洞、错误处理、代码质量。
适用于 Python/FastAPI 和 TypeScript/React 项目。
trigger:
keywords: [review, 审查, 检查代码, code review, cr]
commands: [/review, /cr]
platforms: [claude-code]
dependencies: []第三步：写 SKILL.md
上面已经有完整示例，这里不再重复。核心要点：
- 第一行定义角色：AI 需要知道它在扮演什么角色
- 分级清单：🔴 硬性 → 🟡 推荐 → 🟢 建议
- 输出格式模板：锁定输出格式，每次审查结果可对比
- 总结规则：有 🔴 就拒绝，没商量
第四步：写 references（可选）
bash
cat > references/security-rules.md << 'EOF'
# 安全规则补充
本项目特别关注的安全问题（按优先级排列）：
1. JWT Token 不过期或硬编码
2. 文件上传无大小/类型限制
3. API 接口缺少 rate limiting
EOF第五步：验证 Skill
bash
# 确认 Skill 被识别
claude skill list | grep my-code-review
# 在 Claude Code 中测试
# 输入：/review
# 观察：AI 是否按你的 checklist 逐项检查？
# 输出：格式是否符合模板？调试 Skill 的三个技巧
技巧一：看 AI 是否加载了 Skill
当你说触发词后，观察 AI 的响应开头。如果它加载了你的 Skill，通常会在思考过程或开头提及 Skill 名称。
没有加载 Skill 的信号：
"我来 review 一下这段代码..."（用自己的标准）
加载了 Skill 的信号：
"按照 code-review Skill 的清单，逐项检查..."（用你的标准）
→ 并且输出格式符合你的模板技巧二：白盒测试------用极简用例验证
不要用复杂代码测试新 Skill。用一个"故意有 SQL 注入"的极简代码：
python
# 测试用例：故意写一段有问题的代码
def get_user(username):
return db.execute(f"SELECT * FROM users WHERE name = '{username}'")如果 Skill 正常，AI 应该：
- 检测到 SQL 注入（🔴 级别）
- 给出修复建议（参数化查询）
- 输出格式符合你的模板
如果没检测到 → checklist 描述不够明确，或者输出格式指令冲突了。
技巧三：渐进加载测试
Skill 的 references 是按需加载的。测试方法：
第一轮：只触发 Skill → 检查是否加载了 SKILL.md 的内容
第二轮：提供一段涉及安全问题的代码 → 检查是否加载了 references/security-rules.md
第三轮：提供一段纯风格的代码 → 检查是否加载了 references/style-guide.md如果 references 一直没加载，检查 SKILL.md 里是否有明确的引用指令，比如"当涉及安全问题时，参考 references/security-rules.md"。
常见写入错误
| 错误 | 现象 | 修复 |
|---|---|---|
| metadata description 太模糊 | AI 判别不准，该触发不触发 | 加具体关键词和场景 |
| Checklist 项太抽象 | AI 检查结果没有一致性 | 每条改成可判断的"是/否"问题 |
| SKILL.md 太长（>2000 字） | Skill 加载慢，占用太多上下文 | 拆分到 references/ |
| 输出格式指令不明确 | AI 输出格式每次不一样 | 给模板，用竖线表格或固定字段 |
| 和其他 Skill 规则冲突 | AI 行为异常，两个 Skill 的结果矛盾 | 检查 Skill 的 dependencies 和互斥关系 |
从个人 Skill 到团队共享
Skill 写好、调通之后，自然想让团队其他人也用。有三条路径：
个人 Skill（本篇）
│
├─ 路径 A：提交到项目仓库
│ git add .claude/skills/my-code-review
│ → 放在项目的 .claude/skills/ 目录，随项目版本管理
│
├─ 路径 B：发布到 GitHub
│ 独立建仓库 → 写 README → 打 tag
│ → 团队成员从 GitHub 克隆到 ~/.claude/skills/
│
└─ 路径 C：打包成 Plugin（第 9-10 篇）
把多个 Skill + MCP + Hooks 打包成一个 Plugin
→ 一条命令安装全套配置路径 A 最省事，适合项目专用 Skill。路径 C 最强大，适合"团队标准化工作台"。