一文讲清 CLAUDE.md、Skills、MCP、Hooks 的实战用法

二、Skills：可复用的操作手册

2.1 它是什么

Skills 是可复用的工作流模板 —— 告诉 Agent 遇到特定场景该怎么一步步做。

如果 CLAUDE.md 是 ” 员工手册 “，那 Skills 就是各种标准操作流程（ SOP ）。比如 ” 怎么做代码审查 ” ” 怎么部署上线 ” ” 怎么调试问题 “。

关键特点：

• 按需加载，不用不占上下文
• 可以手动触发（/skill-name）
• 也可以让 Claude 自动判断何时使用

2.2 Skills vs CLAUDE.md：何时用哪个

判断标准：

• 如果 Claude 应该始终知道 → CLAUDE.md
• 如果 Claude 有时需要 → Skills

例子：

• ” 用 pnpm 不要用 npm ” → CLAUDE.md（ 每次都要知道 ）
• ” 怎么做 code review ” → Skill（ 只在审查代码时需要 ）

2.3 Skills 的两种类型

参考型 Skills（ 知识库 ）

• 提供参考信息：API 文档、设计规范、架构说明
• Claude 自动判断何时需要
• 例子：API 风格指南、错误处理模式

操作型 Skills（ 工作流 ）

• 可调用的流程：用 /skill-name 手动触发
• 例子：/deploy、/code-review、/generate-docs
• 适合有明确步骤的任务

2.4 文件结构

一个 Skill 本质上是一个文件夹，包含以下内容：

code-review/
├── SKILL.md        # 必须：主文件，包含指令（注意必须全大写）
├── scripts/        # 可选：可执行脚本（Python、Bash 等）
├── references/     # 可选：参考文档，按需加载
└── assets/         # 可选：模板、图标等资源

其中 SKILL.md 是核心，由 YAML 头部 + Markdown 正文组成。

Skill 存放位置：

• 项目级：.claude/skills/（ 团队共享 ）
• 用户级：~/.claude/skills/（ 个人使用 ）

2.5 渐进式加载：省 token 的秘密

Skills 有一个精妙的设计 —— 渐进式加载（ Progressive Disclosure ），分三层：

• 1、YAML 头部：始终加载到 Agent 上下文中，让 Agent 知道”有这个 Skill ” 和”什么时候该用 “
• 2、SKILL.md 正文：Agent 判断当前任务需要时才加载，包含完整的操作指令
• 3、关联文件：references / 和 scripts / 中的内容，Agent 执行过程中按需读取

这个设计的好处是省 token。你可以装 50 个 Skills，但 Agent 只会加载当前真正需要的那几个。

2.6 怎么写一个 Skill

一个完整的 Skill 示例：

---
name: code-review
description: 代码审查流程，确保代码质量和规范一致性。
Use when user asks to " review code ", " check PR ", or " 审查代码 ".
---
## 审查流程
1. 读取变更文件列表（ git diff ）
2. 对照项目的代码规范逐文件检查：
   - 命名是否符合规范
   - 是否有安全漏洞（ XSS、SQL 注入等 ）
   - 是否有明显的性能问题
3. 输出审查报告，按严重程度分级：
   - 🔴 必须修复
   - 🟡 建议优化
   - 🟢 可以忽略
4. 如果发现 🔴 级别问题，阻止合并
## Troubleshooting
Error: No diff found
Cause: Working on main branch with no changes
Solution: Switch to feature branch first

关键要点：

description 必须包含触发条件：

• ❌ ” Helps with code review “（ 太模糊 ）
• ✅ ” Use when user asks to ‘ review code ‘ or ‘ check PR ‘ “（ 具体的触发词 ）

步骤要具体可执行：

• ❌ ” 确保代码质量 “（ 模糊 ）
• ✅ ” 检查命名、安全漏洞、性能问题 “（ 具体 ）

考虑异常情况：

• 加上 Troubleshooting 部分

2.7 触发方式

手动触发：/code-review

用户明确调用，Agent 立即加载并执行

自动识别：请帮我审查一下代码

Agent 根据 description 中的触发条件（ ” review code ” ）自动加载对应 Skill

2.8 省上下文技巧

对于有副作用的操作型 Skill（ 如部署、提交代码 ），建议使用：

---
name: deploy
description: Deploy to production
disable-model-invocation: true
---

disable-model-invocation: true 让这个 Skill 对 Claude 完全隐藏，直到你手动调用。这样：

• 节省上下文（ 不加载 description ）
• 避免误触发（ 只有你主动调用才执行 ）

2.9 核心定位

Skills 是可复用的流程知识。写一次，反复用。

适合的场景：

• 团队统一工作标准（ 所有人的 code review 流程一致 ）
• 个人固化最佳实践（ 每次 debug 都按同一套方法论排查 ）
• 复杂流程不遗漏（ 发布上线要检查 10 个步骤，Skill 帮你记住 ）