1. 引言

在前面的博客，博主已经讲解了 Claude Code 相关的概念，有兴趣的同学可以参考下：

• 《Claude Code 完整指南（一）：安装、CLI 实战、IDE 集成一次讲透》
• 《Claude Code 完整指南（二）：终端命令全解析（收藏级）》
• 《Claude Code 完整指南（三）：命令背后的数据流动》
• 《Claude Code 完整指南（四）：Hooks（自动化事件触发）》
• 《Claude Code 完整指南（五）：Subagents（AI 角色工程化）》

很多人用 Claude Code 用着用着，会出现一个非常典型的“团队化痛点”：

• 同一个需求，不同人问法不同，Claude 输出结构就不同
• 今天它写出了测试证据，明天它只给一段“我觉得差不多”
• 团队有规范（比如迁移必须可回滚、PR 必须写风险与回滚），但 AI 不一定每次都记得

Skills 的价值不在 “更聪明”，而在“更稳定”：把一类任务的标准步骤、检查清单、输出格式、工具边界写成 Skill，让它每次都按 SOP交付 （Standard Operating Procedure，翻译为标准操作流程）。

2. Skills 是什么?

Skills 是一个独立的任务模板，核心由三部分组成：

1. 触发语义：description 描述 “什么时候用我”
2. 执行流程：正文写 “怎么做（步骤/清单/约束）”
3. 能力边界：allowed-tools 约束 “能用哪些工具”

它可以：

• 手动调用（最可控）
• 自动触发（依赖 description 匹配）
• 被 Subagent 引用（把 SOP 固化到某个岗位上）

3. 如何理解 Skills、Subagents、Hooks

把这三个概念分清楚，你就知道 “该用 Skill 还是该用 Subagent”：

能力	它更像	解决的问题	适合什么场景
Skills	SOP/作业指导书	让输出结构稳定、流程可复制	审查清单、迁移模板、文档生成、PR 总结
Subagents	岗位/专职工种	让角色边界清晰、上下文更干净	测试工程师、安全审计、文档工程师、重构工程师
Hooks	事件触发器/门禁	让流程自动发生、能阻断风险	代码格式化、危险命令拦截、Stop 质量门禁

总结：Skill 定“怎么做”，Subagent 定“谁来做”，Hook 定“什么时候做/能不能继续”。

如果结合5w1h图，可能就更容易理解了，Skills → HOW | Subagent → WHO | Hooks → WHEN。

4. Skills 配置

Skill 的基本结构是：一个文件夹 + SKILL.md。

用户级（跨项目复用）配置示例：

~/.claude/skills/
└── code-reviewer/
    └── SKILL.md

适合：你个人通用的 SOP（安全审查、变更总结、周报整理）。

---

项目级（推荐团队共享）配置示例：

{project}/.claude/skills/
├── api-doc-generator/
│   └── SKILL.md
└── db-migration-helper/
    └── SKILL.md

适合：强依赖项目结构与技术栈的 SOP（路由风格、目录规范、测试命令、迁移框架）。

团队最佳实践：项目级 Skills 提交到 Git；个人覆盖放 settings.local.json 或用户级 skills。

---

4.1 SKILL.md 结构

Skill 定义文件是 SKILL.md（Markdown + YAML frontmatter），示例：

---
name: Code Review Assistant
description: Perform comprehensive code reviews focusing on security, performance, and best practices
user-invocable: true
context: fork
model: opus
allowed-tools:
  - Read
  - Grep
  - Bash
---

# Code Review Instructions

你是一位资深工程师，目标是产出可执行的 Review 报告。

## Checklist
- Security
- Performance
- Best Practices

## Output Contract
1) Summary
2) Must Fix
3) Suggestions
4) Test Evidence

理解重点：

• YAML 区决定“运行方式”（能否在菜单出现、是否隔离上下文、用哪个模型、允许哪些工具）
• 正文决定“产出质量”（流程/清单/约束/输出契约）

---

4.2 关键字段解析

4.2.1 name、description

name：展示名（给人看）

description：触发语义（给 Claude 判断“何时用”），建议写法：

• 写清楚 “Use when … / 当用户要 … 时使用”
• 把关键词写进去（review/security/changelog/migration/docs/test）
• 不要写成一句很空的口号（例如 “helps with coding”）

4.2.2 user-invocable

作用：是否显示在 /skills 列表

• 默认：true
• 建议：
  • 团队对外入口：true
  • 内部中间件 Skill（只给 Subagent 引用）：可以设为 false，减少干扰

4.2.3 context: fork

作用：让 Skill 在“隔离的 fork 上下文”运行（减少污染主对话）

建议：

• 审查/总结/报告类默认 fork
• 需要连续交互、多轮拿上下文才能完成的任务，谨慎使用（否则主对话看不到细节，只拿到结果）

4.2.4 model

作用：指定 Skill 的模型（建议用你配置过的别名）

团队建议：

• 高频 SOP（文档/总结）用更快模型
• 高风险（安全审计/迁移门禁）用更强模型或主对话复核

4.2.5 allowed-tools

作用：白名单：Skill 只能使用这些工具

最小权限原则：

• 只读审查：Read, Grep
• 文档生成：Read, Grep, Write
• 迁移生成：Read, Write（Bash 能不开就不开；确实需要再加）

---

5. Skills 用法

5.1 Skills 命令调用

可以通过如下命令手动调用 Skills：

/skills

从列表里选择某个 Skill 执行即可（最可控、最可复现）。 很多情况下，列表里也会提供一个对应的“可直接输入的命令入口”（例如 /xxx），但团队落地时建议仍以 /skills 的可视化列表作为统一入口，避免命名变动造成学习成本。

当然，当输入的需求与某个 Skills 的 description 足够匹配，Claude 也会尝试自动触发它。

5.2 Subagent 引用 Skills

在 Subagent 的 YAML 里绑定 skills，例如：

---
name: api-tester
description: API 测试专家
skills: api-testing, change-summary
---

这类输出会更稳定，也更像团队工作流。

###= 5.3 Skills 定义规范

① 推荐命名规范（减少调用成本）：

• Skill 目录名：kebab-case，语义明确（change-summary/、api-doc-generator/）
• name：给人看的标题（可以更友好）
• description：像搜索关键词一样写（可触发、可理解）

② 把“输出契约”写死（让结果可验收）：

• Summary（3~5 行）
• Deliverables（产物清单：文件/命令/链接）
• Risks（风险与回滚）
• Test Evidence（测试证据）
• Next Actions（下一步）

③ 把 Skill 当作“流程资产”版本化：

• 提交 Git（像提交脚本一样）
• PR 审核 Skill 变更（因为它影响“团队的默认产出方式”）
• 和 Hooks/Subagents 一起形成 .claude/ 目录的“开箱即用工程规范”

④ 工具边界：建议先收紧 allowed-tools，不够用再放开

⑤ Skill 编写 Checklist：

• description` 可触发：明确 Use when / 当用户要…时使用（别写空话）
• 输出契约固定：Summary/Deliverables/Risks/Test Evidence/Next Actions
• 步骤可执行：每一步都能落到“读哪些文件/产出什么内容”
• 工具最小化：只给完成任务所需的最小 allowed-tools
• 能兜底：写清“信息不足时要反问什么/要我提供什么”

5.3 案例模板

5.3.1 change-summary（PR 描述/发布说明生成器）

---
name: Change Summary Generator
description: Generate PR description / release notes / changelog from code changes. Use when user asks for summary, changelog, release notes, or PR description.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
---

# Change Summary

目标：把变更整理成“可直接粘贴到 PR/发布说明”的结构化内容。

输出契约（必须遵守）：
1) Summary（3~5 行）
2) User Impact（谁会受影响）
3) Risk & Rollback（风险与回滚策略）
4) Test Evidence（跑了什么/没跑为什么）
5) Notes（兼容性/配置变更/迁移说明）

5.3.2 api-doc-generator（API 文档生成器）

---
name: API Documentation Generator
description: Generate API documentation from routes/types/comments. Use when user asks to create API docs or document endpoints.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
  - Write
---

# API Documentation

对每个 endpoint 输出（必须完整）：
- Method / Path / Description
- Auth（是否需要登录/权限）
- Request（Headers/Params/Body Schema）
- Response（Success Schema + Error Codes）
- curl Example（可复制）

额外要求：
- 如果找不到路由定义，说明你查了哪些文件/模式（便于我补上下文）

5.3.3 db-migration-helper（数据库迁移助手：必须可回滚）

---
name: Database Migration Helper
description: Help create safe and reversible database migrations with explicit up/down. Use when user needs to modify database schema.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Write
  - Bash
---

# Database Migration Helper

原则：
1) 必须可回滚（必须有 Down）
2) 高风险操作必须显式标注（drop/rename/backfill）
3) 考虑性能与锁表风险（索引/大表 DDL）

输出契约：
1) Migration Plan（步骤 + 风险点）
2) Up Migration（完整内容）
3) Down Migration（完整内容）
4) Rollout Notes（上线建议：分批/灰度/监控项）
5) Rollback Steps（回滚命令/验证点）

5.3.4 code-review-assistant（结构化代码审查：可执行清单）

---
name: Code Review Assistant
description: Perform comprehensive code reviews focusing on security, correctness, performance, and maintainability. Use when user asks to review code or audit changes.
user-invocable: true
context: fork
allowed-tools:
  - Read
  - Grep
---

# Code Review Assistant

审查范围：
- Correctness（边界/异常/并发）
- Security（鉴权/注入/敏感信息）
- Performance（热路径/IO/复杂度）
- Maintainability（命名/结构/重复/可测试性）

输出契约（必须遵守）：
1) Summary（一段话）
2) Must Fix（每条：文件 + 问题 + 影响 + 修复建议）
3) Should Fix（同上）
4) Nice to Have（可选）
5) Test Suggestions（建议补哪些测试）

---

5.4 与 Hooks/Subagents 组合：把流程做成“装配线”

如果只做 Skills，会得到“更稳定的模板”；但如果把 Skills、Subagents、Hooks 组合起来，就能得到“自动化流水线”，一个最容易落地的团队组合拳：

• Subagent：test-writer（岗位）绑定 Test Generator 类 Skill（SOP）
• Hook：PostToolUse(Write|Edit) 自动格式化 + 最小测试（不阻断）
• Hook：Stop 做最终门禁（测试/lint/git status）
• Skill：change-summary 在最后生成 PR 描述（结构化输出）

这样基本能做到：每次交付都带 测试证据、风险与回滚、可直接粘贴的 PR 总结。

6. 文末

通过阅读本文，相信大家已经系统理解了 Claude Code 中 Skills、Subagents 与 Hooks 的设计理念与工程价值：它们并不是 “会用 AI 就行” 的技巧，而是一套 任务固化、角色分工、事件驱动 的团队化协作机制。通过将常用流程抽象为 Skills（可复用 SOP）、将岗位职责封装为 Subagents（角色隔离、权限可控）、并通过 Hooks 自动触发关键步骤，可以显著提升交付的稳定性、可复用性与可验收性，让复杂任务具备可并行、可自动化、可回滚的工程属性。

希望本文能帮助大家更好地理解并落地 Claude Code 的团队化自动化实践，也欢迎在评论区分享你的 Skill/Agent 设计、Hooks 应用与实践经验。感谢阅读，本文完！