第14章：Agent Skills —— 教 Agent 学会新技能

一句话：用 Skills 文件扩展 Agent 的知识和行为模式，让它不只是会用工具，还知道怎么用好工具。

本章目标

理解 Skills 的概念和它存在的意义
掌握 Skills 文件的编写格式
学会创建你自己的 Skill
理解 Skills 的加载机制和优先级
掌握 Skill 设计的最佳实践
能区分 MCP、Skills 和 Subagents 各自的定位

前置知识

需要先看完第11章（MCP 协议）
需要先看完第12章（Hooks）
需要先看完第13章（多 Agent 协作）

14.1 Skills 是什么？

工具够用了，但 Agent 不知道怎么用好

回想一下前面几章学到的东西：

第10章教了你怎么给 Agent 做自定义工具
第11章教了你用 MCP 接入一大堆现成的工具
第13章教了你怎么让多个 Agent 协作

到这一步，你的 Agent 已经"装备齐全"了 —— 手里有各种工具，身边有一群帮手。但问题来了：

Agent 有了工具，就一定能用好吗？

举个例子。你给一个 Agent 配了 Git 工具，让它帮你提交代码。结果它提交了一个这样的 commit message：

修改了一些文件

技术上来说，这个 commit 没毛病 —— 代码确实提交了。但这个 commit message 写得像坨屎。团队里的其他人看到这种 commit，不骂街才怪。

问题出在哪？Agent 有能力用 Git 工具，但它不知道你们团队的 commit 规范。它不知道你们用的是 Conventional Commits 格式，不知道 feat: 前缀代表新功能，fix: 代表修 Bug。

这就是 Skills 要解决的问题 —— 不是给 Agent 更多的工具，而是教它怎么正确地使用这些工具。

MCP 给你吉他，Skills 给你吉他教程

这个比喻非常贴切，值得多说两句。

MCP（工具接口）就像给你一把吉他：

你有了这个乐器
你能拨弦，能按弦
但你弹出来的东西可能是噪音

Skills（技能文档）就像给你一套吉他教程：

教你怎么调弦
教你基本和弦怎么按
教你一首歌应该怎么弹
教你什么场合该弹什么风格

两者配合起来，你才能弹出好听的曲子。

放到 Agent 的世界里：

	MCP	Skills
给 Agent 的是	"你可以用这些工具"	"你应该这样用这些工具"
信息类型	工具定义（函数签名）	领域知识（操作指南）
格式	代码/配置	Markdown 文档
例子	"这是 git_commit 工具，参数是 message"	"写 commit message 时要用 Conventional Commits 格式"

Skills 的本质：给 Agent 注入领域经验

往深了说，Skills 的本质就是一种结构化的知识注入方式。

你可以把 Skills 想象成给新员工的"工作手册"。新员工入职了，公司给他分配了电脑（工具）、工位（环境）、权限（Permissions）。但他第一天上班还是不知道该怎么干活，因为他不了解公司的业务流程、编码规范、部署规则。

工作手册解决了这个问题 —— 它不是工具，它是知识。

Skills 就是 Agent 的工作手册。

Claude 怎么知道何时使用 Skill？

这是很多人一开始的疑问：Agent 怎么知道什么时候该调用某个 Skill？

答案在于 Skill 文件的 description 字段。当 Agent 遇到一个任务时，它会看所有可用 Skill 的描述，如果发现某个 Skill 的描述跟当前任务相关，就会自动加载并遵循该 Skill 的指令。

这个过程是自主的 —— 你不需要手动告诉 Agent "现在用这个 Skill"。Agent 自己会判断。

就像一个好员工，你不用每次都提醒他"记得按规范写 commit"。他自己就知道 —— 因为他读过手册、记住了规范。

14.2 Skills 文件格式

放在哪里？

Skills 文件放在 .claude/skills/ 目录下。有两个层级：

~/.claude/skills/          <-- 用户级（所有项目通用）
├── git-commit-helper.md
├── code-style-check.md
└── daily-report.md

项目根目录/.claude/skills/  <-- 项目级（本项目专用）
├── deploy-checklist.md
├── api-design-guide.md
└── test-writing-guide.md

用户级 Skills 放在你 home 目录下的 ~/.claude/skills/，不管你在哪个项目里工作，这些 Skills 都可以被 Agent 加载。适合放一些通用的技能，比如 Git 规范、代码风格之类的。

项目级 Skills 放在项目根目录的 .claude/skills/，只有在这个项目里工作时才会被加载。适合放项目特定的技能，比如这个项目的部署流程、API 设计规范等。

文件格式

每个 Skill 是一个 Markdown 文件，包含两个部分：YAML 前置信息（frontmatter）和正文内容。

---
name: skill-name
description: 一句话描述这个 Skill 的用途和触发时机
---

## 正文内容

这里写具体的指令、步骤、规则等。

我们来拆解一下每个部分：

YAML Frontmatter（前置信息）

这部分用三个横杠 --- 包裹，用 YAML 格式写。

---
name: git-commit-helper
description: 帮助用户创建规范的 git commit message，当用户想要提交代码时自动触发
---

name（名称）：

这个 Skill 的唯一标识
建议用小写英文加横杠，比如 git-commit-helper
不要用中文，不要用空格

description（描述）：

这是最最最重要的字段！
Agent 根据这个描述来判断什么时候该触发这个 Skill
描述要写清楚两件事：(1) 这个 Skill 干什么，(2) 什么时候应该用它
写得太模糊，Agent 可能该用的时候不用
写得太宽泛，Agent 可能不该用的时候也用了

好的描述和差的描述对比：

差的描述	好的描述
"帮助用户"	"帮助用户创建规范的 git commit message，当用户想要提交代码时自动触发"
"代码检查"	"在用户编写或修改代码后，按照项目的 ESLint 规则检查代码风格并自动修复"
"部署"	"在用户准备部署应用到生产环境时，执行一系列预部署检查并生成部署报告"

正文内容

正文用标准 Markdown 写。你可以用标题、列表、代码块、表格 —— 任何 Markdown 语法。

正文里通常包含：

工作流程：一步一步告诉 Agent 该怎么做
规则和约束：什么可以做，什么不可以做
格式模板：输出应该长什么样
异常处理：遇到问题该怎么办

下面是一个完整的例子：

---
name: git-commit-helper
description: 帮助用户创建规范的 git commit message，当用户想要提交代码时自动触发
---

## 工作流程

当用户想要提交代码时，按以下步骤操作：

1. 先用 Bash 运行 `git diff --staged` 查看暂存的更改
2. 如果没有暂存的更改，提醒用户先 `git add`
3. 分析变更内容，理解改了什么
4. 按 Conventional Commits 规范生成 commit message
5. 让用户确认 commit message
6. 确认后执行 `git commit -m "..."`

## Commit Message 格式

():

```

Type 类型

feat: 新功能
fix: 修复 bug
docs: 文档变更
style: 代码风格调整（不影响功能）
refactor: 代码重构
test: 测试相关
chore: 构建/工具变更

规则

subject 不超过 50 个字符
subject 用英文，首字母小写，不加句号
body 可以用中文，解释"为什么"而不是"做了什么"
如果改动涉及多个模块，scope 用逗号分隔

异常处理

如果 git diff --staged 为空，告诉用户："还没有暂存的更改，请先用 git add 添加要提交的文件。"
如果改动量太大（超过 500 行），建议用户拆分成多个 commit
如果无法确定 type，默认用 chore


---

## 14.3 编写你的第一个 Skill

光说不练假把式，我们来动手写第一个 Skill。

### 需求分析

假设你们团队有一个约定：每次提交代码前，要确保 commit message 符合 Conventional Commits 规范。但团队里总有人（也许就是你）偷懒写"fix bug"、"update code"之类的垃圾 commit message。

我们来写一个 Skill，教 Agent 在帮你提交代码时自动遵守这个规范。

### 第一步：创建目录

```bash
# 在你的项目根目录下
mkdir -p .claude/skills

第二步：创建 Skill 文件

在 .claude/skills/ 下创建一个文件 git-commit-helper.md：

---
name: git-commit-helper
description: 帮助用户创建规范的 git commit message，当用户想要提交代码或者说"提交"、"commit"时自动触发
---

## 工作流程

当用户想要提交代码时，按以下步骤操作：

1. 先用 Bash 运行 `git status` 查看当前状态
2. 再用 Bash 运行 `git diff --staged` 查看暂存的更改
3. 如果没有暂存的更改，提醒用户先用 `git add` 添加文件
4. 分析变更内容，理解改了什么
5. 按 Conventional Commits 规范生成 commit message
   - feat: 新功能
   - fix: 修复 bug
   - docs: 文档变更
   - style: 代码风格调整
   - refactor: 代码重构
   - test: 测试相关
   - chore: 构建/工具变更
6. 把生成的 commit message 展示给用户确认
7. 用户确认后，执行 `git commit -m "..."`
8. 提交完成后，显示 `git log --oneline -1` 确认结果

## 格式规范

commit message 格式：

():

Co-Authored-By: AI Assistant


### 规则

- subject 不超过 50 个字符
- subject 用英文，首字母小写，结尾不加句号
- body 是可选的，如果改动比较复杂就加上
- body 用来解释"为什么做这个改动"，而不是"做了什么改动"
- 如果一次改动涉及多个文件但属于同一个功能，合成一个 commit
- 如果改动涉及不相关的多个功能，建议用户拆分成多个 commit

## 异常处理

- 如果工作区很脏（大量未暂存的更改），先问用户是要全部提交还是选择性提交
- 如果检测到 .env 或含有密钥的文件被暂存了，立即警告用户并阻止提交
- 如果改动量超过 500 行，建议用户考虑拆分 commit

第三步：在 SDK 中启用 Skills

如果你是通过 Claude Agent SDK 编程使用的，需要在配置中开启 Skills：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "帮我提交一下代码",
  options: {
    // 启用 Skills 加载
    settingSources: ["user", "project"],
    // 允许使用 Skill 工具
    allowedTools: ["Bash", "Read", "Write", "Edit", "Skill"],
    cwd: "/path/to/your/project"
  }
})) {
  // 处理消息...
}

关键的两个配置：

settingSources: ["user", "project"] —— 告诉 SDK 从用户目录和项目目录加载配置和 Skills
allowedTools 中包含 "Skill" —— 允许 Agent 使用 Skill 工具

第四步：测试

现在对你的 Agent 说"帮我提交代码"。如果一切配置正确，Agent 会：

自动识别到这个请求和 git-commit-helper Skill 相关
按照 Skill 里定义的工作流程一步步执行
先检查 git 状态，分析变更，生成规范的 commit message
让你确认后才真正提交

恭喜，你的第一个 Skill 写好了！

14.4 Skills 的加载机制

两级加载

Skills 的加载分两级，就像手机上的全局设置和 App 内设置：

加载顺序：
1. 用户级 Skills：~/.claude/skills/*.md     （先加载）
2. 项目级 Skills：.claude/skills/*.md       （后加载）

用户级 Skills（~/.claude/skills/）：

不管你在哪个项目里，都会被加载
适合放通用技能：Git 规范、代码风格、常用工作流
就像你的个人习惯 —— 不管去哪个公司，你都会用这套方式工作

项目级 Skills（.claude/skills/）：

只在当前项目中生效
适合放项目特定的技能：部署流程、API 设计规范、测试策略
就像公司的规章制度 —— 只在这家公司适用

优先级规则

如果用户级和项目级有同名的 Skill，项目级优先。

为什么？因为项目级的规则更具体、更贴近当前工作场景。就像法律一样 —— 地方法规在不违反宪法的前提下，优先于全国性的通用规定。

举个例子：

~/.claude/skills/code-style.md
→ 规定了"用4个空格缩进"

.claude/skills/code-style.md
→ 规定了"用2个空格缩进"（因为这个项目用的是 Prettier 默认配置）

在这个项目里，Agent 会用 2 个空格缩进 —— 项目级覆盖了用户级。

SDK 中的配置

在 Claude Agent SDK 中，通过 settingSources 控制从哪里加载 Skills：

// 只加载项目级 Skills
settingSources: ["project"]

// 只加载用户级 Skills
settingSources: ["user"]

// 两个都加载（推荐）
settingSources: ["user", "project"]

如果你不设置 settingSources，默认不会加载任何 Skills。所以这个配置别忘了。

Skills 的发现与匹配

Agent 不会一上来就把所有 Skills 的内容都塞进上下文里 —— 那太浪费 Token 了。

实际的流程是这样的：

Agent 启动时，读取所有 Skill 文件的 name 和 description
用户发来一个请求
Agent 根据请求内容，匹配哪些 Skill 的 description 和当前任务相关
只加载相关的 Skill 的完整内容到上下文中
按照 Skill 的指令执行

这就是为什么 description 那么重要 —— 它是 Agent 决定"要不要加载这个 Skill"的唯一依据。

想象一下图书馆的场景：description 就是书脊上的书名。你找书时先看书名，觉得相关才会把书抽出来翻。如果书名写得不清楚，你可能会错过一本好书。

14.5 Skill 设计原则

写 Skill 不难，写好 Skill 不容易。这里总结了几条实用的设计原则。

原则一：description 是灵魂

前面说了很多遍了，再强调一次：description 决定了这个 Skill 会不会被触发。

写 description 的诀窍：

说清楚干什么：不是"帮助用户"（太模糊），而是"帮助用户创建规范的 git commit message"
说清楚什么时候触发：不是"和代码相关时"（太宽泛），而是"当用户想要提交代码时"
可以列举触发关键词：比如"当用户说'提交'、'commit'、'push 代码'时触发"

# 差的 description
description: 帮助用户处理代码

# 好的 description
description: 当用户想要提交代码（commit）或推送代码（push）时，帮助生成符合 Conventional Commits 规范的 commit message

原则二：指令要步骤化

不要写一大段话告诉 Agent 该怎么做。要写成一步一步的清单。

Agent 的大脑（LLM）和人一样 —— 看到一段长文字容易迷糊，看到一个编号列表就清晰多了。

## 差的写法

当用户想要提交代码时，你需要先查看 git 状态，然后查看暂存的更改，
分析变更内容并理解改了什么，然后按照规范生成 commit message，
展示给用户确认，确认后执行提交。

## 好的写法

当用户想要提交代码时，按以下步骤操作：

1. 运行 `git status` 查看当前状态
2. 运行 `git diff --staged` 查看暂存的更改
3. 如果没有暂存更改，提醒用户先 `git add`
4. 分析变更内容，理解改了什么
5. 按 Conventional Commits 规范生成 commit message
6. 展示给用户确认
7. 确认后执行 `git commit -m "..."`

原则三：包含异常处理

现实世界不是理想世界。你的 Skill 必须告诉 Agent 遇到问题该怎么办。

常见的异常场景：

工具执行失败了怎么办？
用户给的信息不完整怎么办？
结果不符合预期怎么办？
遇到安全风险怎么办？

## 异常处理

- 如果 `git diff --staged` 为空：告诉用户"还没有暂存的更改"
- 如果 commit 执行失败（比如 pre-commit hook 不通过）：
  1. 显示错误信息
  2. 分析错误原因
  3. 建议修复方案
- 如果检测到敏感文件（.env、密钥文件）被暂存：
  1. 立即警告用户
  2. 不要执行 commit
  3. 建议把这些文件加入 .gitignore

原则四：明确指定工具

告诉 Agent 该用什么工具来完成任务，不要让它自己猜。

## 好的写法 —— 明确指定工具

1. 用 **Bash** 运行 `git diff --staged`
2. 用 **Read** 读取项目根目录的 `.eslintrc` 文件
3. 用 **Grep** 搜索代码中的 TODO 注释
4. 用 **Write** 生成报告文件

## 差的写法 —— 模糊

1. 检查暂存的更改
2. 看看项目配置
3. 找找 TODO
4. 写个报告

原则五：留有弹性

Skill 是指南，不是死板的脚本。给 Agent 一些灵活处理的空间。

## 太死板（不好）

commit message 必须恰好 50 个字符，subject 必须用英文，
body 必须包含至少 3 行描述。

## 有弹性（好）

- subject 建议不超过 50 个字符，但如果实在需要可以适当放宽
- subject 优先用英文，如果项目是中文团队且用中文更清楚也可以
- body 是可选的，简单的改动可以不写 body

原则六：保持专注

一个 Skill 只做一件事。不要试图在一个 Skill 里塞进去太多功能。

好：
  - git-commit-helper.md  → 只管 commit
  - code-review.md        → 只管代码审查
  - deploy-checklist.md   → 只管部署检查

差：
  - do-everything.md      → 又管 commit 又管 review 又管部署

14.6 实战 Skills 集

光讲原则没意思，来看几个完整的、可以直接拿去用的 Skill。

Skill 1：代码风格检查

这个 Skill 教 Agent 在你写完代码后自动检查代码风格。

创建文件 .claude/skills/code-style-check.md：

---
name: code-style-check
description: 在用户编写或修改代码后，检查代码是否符合项目的编码规范。当用户说"检查代码"、"review"、"看看代码有没有问题"时触发
---

## 工作流程

1. 确定要检查的文件范围
   - 如果用户指定了文件，就检查指定的文件
   - 如果没有指定，用 Bash 运行 `git diff --name-only` 找到最近修改的文件
2. 用 Read 读取需要检查的文件
3. 用 Read 读取项目的配置文件（如果存在的话）：
   - `.eslintrc` 或 `.eslintrc.js` 或 `eslint.config.js`
   - `.prettierrc`
   - `tsconfig.json`
4. 根据项目配置和通用最佳实践，检查以下方面：

### 检查清单

- [ ] **命名规范**：变量名、函数名是否有意义，是否符合项目风格（camelCase/snake_case）
- [ ] **函数长度**：单个函数是否超过 50 行（建议拆分）
- [ ] **嵌套深度**：if/for 嵌套是否超过 3 层
- [ ] **魔法数字**：是否有未定义为常量的硬编码数字
- [ ] **错误处理**：async 函数是否有 try-catch，Promise 是否有 .catch
- [ ] **类型安全**：TypeScript 项目中是否有 any 类型
- [ ] **注释**：复杂逻辑是否有注释说明
- [ ] **console.log**：是否有遗留的调试日志
- [ ] **安全问题**：是否有硬编码的密钥、密码、Token

### 输出格式

检查完成后，按以下格式输出报告：

代码检查报告

总体评分：X/10

问题列表

严重问题（必须修复）

[文件名:行号] 问题描述建议：修复方案

建议改进（推荐修复）

[文件名:行号] 问题描述建议：修复方案

风格建议（可选）

[文件名:行号] 问题描述建议：修复方案

总结

一两句话概括代码质量


## 异常处理

- 如果找不到任何代码文件，告诉用户"没有找到需要检查的代码文件"
- 如果项目没有配置文件，按照通用的最佳实践来检查
- 如果代码量太大（超过 20 个文件），建议用户缩小检查范围

Skill 2：项目初始化

这个 Skill 教 Agent 根据用户选择的技术栈自动创建项目。

创建文件 .claude/skills/project-init.md：

---
name: project-init
description: 帮助用户从零开始创建一个新项目，支持 React、Vue、Express、Next.js 等框架。当用户说"创建项目"、"初始化项目"、"新建项目"、"搭建项目"时触发
---

## 工作流程

1. 向用户确认以下信息（如果用户没有说明的话）：
   - 项目名称
   - 技术框架（React / Vue / Express / Next.js / Fastify）
   - 是否使用 TypeScript（默认是）
   - 包管理器偏好（npm / pnpm / yarn，默认 pnpm）

2. 根据用户选择，按下面的模板创建项目结构

3. 安装依赖

4. 验证项目能正常启动

## 框架模板

### React + TypeScript 项目

```bash
# 使用 Vite 创建
pnpm create vite {project-name} --template react-ts
cd {project-name}
pnpm install

创建完成后，额外配置：

添加 .prettierrc 文件
添加 .eslintrc.cjs 文件
更新 tsconfig.json，启用 strict 模式
添加 .gitignore
初始化 git 仓库

Express + TypeScript 项目

mkdir {project-name}
cd {project-name}
pnpm init
pnpm add express
pnpm add -D typescript @types/express @types/node ts-node nodemon

创建目录结构：

{project-name}/
├── src/
│   ├── index.ts          # 入口文件
│   ├── routes/
│   │   └── index.ts      # 路由定义
│   └── middleware/
│       └── errorHandler.ts
├── tsconfig.json
├── .gitignore
├── .prettierrc
└── package.json

src/index.ts 内容模板：

import express from "express";

const app = express();
const port = process.env.PORT || 3000;

app.use(express.json());

app.get("/", (req, res) => {
  res.json({ message: "Hello World" });
});

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

Vue + TypeScript 项目

pnpm create vue@latest {project-name}
# 选择 TypeScript、Vue Router、Pinia
cd {project-name}
pnpm install

完成后

用 Bash 运行 ls -la 确认文件结构正确
尝试启动项目（pnpm dev 或 pnpm start），确认能跑起来
初始化 git 仓库：git init && git add -A && git commit -m "chore: init project"
告诉用户项目创建完成，并说明启动方式

异常处理

如果目标目录已存在，问用户是否覆盖
如果包管理器没安装，尝试用 npm 代替并提醒用户安装
如果依赖安装失败，显示错误信息并建议解决方案


### Skill 3：部署检查清单

这个 Skill 教 Agent 在部署前执行一系列检查。

创建文件 `.claude/skills/deploy-checklist.md`：

```markdown
---
name: deploy-checklist
description: 在用户准备部署应用到生产环境之前，执行预部署检查清单。当用户说"部署"、"deploy"、"上线"、"发版"时触发
---

## 工作流程

在部署之前，逐项检查以下内容。每一项都要实际执行验证，不能只靠看代码猜测。

### 第一步：代码状态检查

1. 用 Bash 运行 `git status`
   - 确认没有未提交的更改
   - 如果有，提醒用户先提交或 stash
2. 用 Bash 运行 `git branch --show-current`
   - 确认当前在正确的分支上（通常是 main 或 release）
   - 如果不在，警告用户
3. 用 Bash 运行 `git log origin/main..HEAD --oneline`
   - 显示即将部署的 commit 列表
   - 让用户确认这些是要部署的内容

### 第二步：测试检查

4. 用 Bash 运行项目的测试命令（`pnpm test` 或 `npm test`）
   - 所有测试必须通过
   - 如果有失败的测试，停止部署流程
5. 如果项目有 lint 配置，运行 `pnpm lint`
   - 确保没有 lint 错误

### 第三步：安全检查

6. 用 Grep 搜索代码中是否有硬编码的敏感信息：
   - 搜索 `password`、`secret`、`api_key`、`token`（排除 .env.example）
   - 搜索疑似 API Key 的字符串模式（如 `sk-xxx`、`ghp_xxx`）
7. 确认 `.env` 文件在 `.gitignore` 中
8. 用 Bash 运行 `pnpm audit`（或 `npm audit`）检查依赖漏洞
   - 如果有高危漏洞，警告用户

### 第四步：配置检查

9. 用 Read 读取 `package.json`
   - 确认 version 号已经更新
   - 确认 scripts 中有正确的 build 和 start 命令
10. 如果有 Dockerfile，用 Read 读取并检查：
    - 基础镜像是否是稳定版本（不是 latest）
    - 是否有多阶段构建
    - 是否暴露了正确的端口

### 第五步：构建检查

11. 用 Bash 运行 `pnpm build`（或项目的构建命令）
    - 构建必须成功
    - 检查构建输出是否有警告

## 输出格式

检查完成后，生成部署检查报告：

部署检查报告

时间：YYYY-MM-DD HH:mm 分支：main 最新 commit：xxxxxxx

检查结果

检查项	状态	备注
代码已提交	PASS/FAIL
分支正确	PASS/FAIL
测试通过	PASS/FAIL
Lint 通过	PASS/FAIL
无敏感信息	PASS/FAIL
无依赖漏洞	PASS/WARN/FAIL
版本号已更新	PASS/FAIL
构建成功	PASS/FAIL

结论

[READY TO DEPLOY] 或 [NOT READY - 有 X 项未通过]


## 异常处理

- 如果找不到测试命令，跳过测试检查但标记为 WARN
- 如果构建命令失败，显示完整错误日志
- 如果有任何 FAIL 项，明确建议用户先修复再部署

Skill 4：日报生成

这个 Skill 教 Agent 根据 git 记录自动生成工作日报。

创建文件 .claude/skills/daily-report.md：

---
name: daily-report
description: 分析今天的 git 提交记录和代码变更，自动生成工作日报。当用户说"写日报"、"生成日报"、"今天干了什么"时触发
---

## 工作流程

1. 用 Bash 获取今天的日期：`date +%Y-%m-%d`
2. 用 Bash 获取今天的 git 提交记录：
   ```bash
   git log --since="today 00:00" --until="today 23:59" --format="%h %s (%an, %ar)" --all

用 Bash 获取今天的文件变更统计：

git diff --stat $(git log --since="today 00:00" --format="%H" --all | tail -1)^..HEAD

如果有多个仓库，可以切换目录分别查看
分析提交记录，归类和总结
生成日报

日报格式

# 工作日报

**日期**：YYYY-MM-DD（星期X）
**姓名**：[从 git config user.name 获取]

## 今日完成

1. **[功能/模块名]**：简要描述做了什么
   - 具体细节1
   - 具体细节2
   - 相关 commit：abc1234, def5678

2. **[功能/模块名]**：简要描述做了什么
   - 具体细节
   - 相关 commit：ghi9012

## 代码统计

- 提交次数：X 次
- 新增代码：+XXX 行
- 删除代码：-XXX 行
- 涉及文件：X 个

## 明日计划

（如果能从 TODO 注释或 Issue 中推断，列出来；否则标记"待填写"）

## 遇到的问题

（如果 commit message 中有 fix 类型的提交，说明遇到了什么 Bug 以及怎么解决的）

规则

日报要简洁，每项不超过两行描述
用中文写，但技术术语保持英文
commit 记录要归类，不要逐条罗列
如果今天没有任何提交，告诉用户"今天暂无 git 提交记录"

异常处理

如果不在 git 仓库中，提醒用户
如果今天没有提交记录，尝试获取最近一天的记录
如果 git log 命令报错，检查 git 是否正确安装和配置


---

## 14.7 MCP vs Skills vs Subagents 对比

到这一章为止，我们已经学了三种扩展 Agent 能力的方式：MCP、Skills 和 Subagents。很多人会搞混它们，所以这里做一个系统的对比。

### 一句话区分

- **MCP**：给 Agent 新的手臂（能力扩展）
- **Skills**：给 Agent 大脑里装经验（知识注入）
- **Subagents**：给 Agent 找来帮手（任务委托）

### 详细对比

| 特性 | MCP | Skills | Subagents |
|------|-----|--------|-----------|
| **是什么** | 工具接口协议 | 知识文档 | 独立的 Agent |
| **定义在** | 代码/配置文件 | Markdown 文件 | 代码/配置文件 |
| **存放位置** | mcpServers 配置 | .claude/skills/ 目录 | agents 配置或 .claude/agents/ |
| **干什么** | 提供新的工具和能力 | 提供领域知识和操作指南 | 执行被委托的子任务 |
| **生活类比** | 手臂（执行能力） | 大脑里的经验（知识） | 同事（协作者） |
| **什么时候用** | 需要 Agent 调用外部系统 | 需要 Agent 遵循特定规范 | 任务太复杂，需要分工 |
| **触发方式** | Agent 主动选择调用 | 根据 description 自动匹配 | 主 Agent 分配任务 |
| **运行时消耗** | 工具调用的 Token + API 调用 | 加载到上下文的 Token | 子 Agent 的完整 Token |

### 实际场景对比

让我们用一个具体的场景来理解：**你想让 Agent 帮你管理 GitHub Issues**。

**用 MCP 解决**（给工具）：
- 接入 GitHub MCP Server
- Agent 获得了 `create_issue`、`list_issues`、`close_issue` 等工具
- Agent 能操作 GitHub 了，但它不知道你们团队怎么管理 Issues

**用 Skills 解决**（给知识）：
- 写一个 `github-issue-management.md` Skill
- 教 Agent：Issue 标题格式、标签规范、优先级定义、分配规则
- Agent 知道你们的规范了，但它没有工具去操作 GitHub

**两者结合**（最佳实践）：
- MCP 提供操作 GitHub 的工具
- Skill 提供你们团队管理 Issues 的规范
- Agent 既能操作，又知道怎么操作正确

**加上 Subagent**（如果任务复杂）：
- 主 Agent 负责理解用户需求
- 子 Agent 1 负责 Issue 分类和标签
- 子 Agent 2 负责查找相关代码和分析影响范围
- 子 Agent 3 负责生成 Issue 报告

### 选择指南

你需要 Agent 做什么新操作？ → 用 MCP（给它工具）

你需要 Agent 按特定方式做事？ → 用 Skills（给它知识）

你需要 Agent 处理复杂的多步骤任务？ → 用 Subagents（给它帮手）

通常情况下 → 三者配合使用效果最好


### 一个类比帮你记住

想象你要开一家餐厅：

- **MCP** = 厨房里的设备（烤箱、冰箱、炒锅） —— 没有设备，厨师没法干活
- **Skills** = 菜谱和烹饪规范 —— 没有菜谱，厨师不知道该做什么菜、放多少盐
- **Subagents** = 厨房里的帮手（帮厨、配菜员、洗碗工） —— 一个人忙不过来，需要分工协作

一个好餐厅需要三者兼备。

---

## 14.8 Skills 生态

### 个人 Skills 库

随着你使用 Skills 的时间越来越长，你会积累越来越多的 Skill 文件。建议你把它们管理起来：

~/.claude/skills/ ├── git/ │ ├── commit-helper.md │ ├── branch-naming.md │ └── pr-review.md ├── coding/ │ ├── code-style-check.md │ ├── test-writing.md │ └── refactoring-guide.md ├── workflow/ │ ├── daily-report.md │ ├── deploy-checklist.md │ └── incident-response.md └── writing/ ├── api-docs.md ├── changelog.md └── meeting-notes.md


你甚至可以用一个 Git 仓库来管理你的 Skills，在不同电脑之间同步：

```bash
# 把 skills 目录变成一个 Git 仓库
cd ~/.claude/skills
git init
git add -A
git commit -m "init: my personal skills collection"

# 推送到 GitHub（私有仓库）
git remote add origin git@github.com:yourname/my-claude-skills.git
git push -u origin main

NanoClaw 的 Skills 模式

如果你了解 NanoClaw 项目，你会发现它把 Skills 当作核心的扩展机制。NanoClaw 的理念是：

Agent 的核心代码尽量简洁（只有几百行）
所有领域知识都通过 Skills 文件提供
社区可以贡献 Skills，共享知识

这种模式的好处是：你不需要改代码就能让 Agent 学会新技能。就像给手机装 App 一样 —— 不需要改手机的操作系统，装一个 App 就能获得新功能。

团队共享 Skills

在团队协作中，Skills 特别有用。你可以把团队的编码规范、部署流程、代码审查标准全部写成 Skills，放在项目的 .claude/skills/ 目录下：

# 团队项目的 Skills
.claude/skills/
├── team-code-style.md       # 团队编码规范
├── api-design-guide.md      # API 设计指南
├── deploy-procedure.md      # 部署流程
├── incident-playbook.md     # 故障处理手册
├── onboarding-helper.md     # 新人入职指引
└── pr-review-standards.md   # PR 审查标准

好处是显而易见的：

新人友好：新来的同事用 Agent 时，Agent 自动就知道团队规范
一致性：所有人的 Agent 都遵循同样的规范，产出一致
知识沉淀：团队的最佳实践被文档化了，不会因为人员流动而丢失
持续迭代：Skills 是 Markdown 文件，可以用 Git 管理版本，可以 code review

社区 Skills

虽然目前还没有一个统一的 Skills 市场或仓库，但社区已经开始在 GitHub 上分享 Skills 了。你可以：

搜索 GitHub 上的 claude-skills 主题
在 Anthropic 社区论坛找到别人分享的 Skills
把你觉得好用的 Skills fork 到自己的仓库

未来，很可能会出现类似 "Skills Hub" 的平台，让开发者可以像安装 npm 包一样安装 Skills。

动手练习

练习1：创建"代码风格检查"Skill

目标：创建一个 Skill，让 Agent 在你修改代码后自动检查代码风格。

步骤：

在你的项目中创建 .claude/skills/ 目录
创建 code-review.md 文件
编写 Skill 内容，要求：
- description 要清晰（什么时候触发）
- 工作流程要步骤化
- 包含具体的检查项（命名、缩进、错误处理等）
- 有明确的输出格式
- 有异常处理
测试：对 Agent 说"帮我检查一下代码"，看它是否按照你的 Skill 执行

验证标准：

Agent 能自动识别并加载你的 Skill
Agent 按照步骤逐项检查
输出格式符合你在 Skill 中定义的格式

练习2：创建"项目初始化"Skill

目标：创建一个 Skill，让 Agent 根据你选择的框架自动搭建项目。

步骤：

创建 project-scaffold.md Skill 文件
支持至少 3 种框架（React、Express、Vue 任选其三）
每种框架要有完整的项目结构定义
要包含：初始化、安装依赖、配置文件、启动验证

验证标准：

对 Agent 说"帮我创建一个 Express + TypeScript 项目"
Agent 应该自动创建项目结构、安装依赖、生成配置文件
项目能正常启动

练习3：创建"部署检查清单"Skill

目标：创建一个 Skill，让 Agent 在部署前执行完整的检查流程。

步骤：

创建 pre-deploy.md Skill 文件
检查项至少包含：
- Git 状态检查（是否有未提交的更改）
- 测试是否通过
- 是否有安全漏洞（敏感信息、依赖漏洞）
- 构建是否成功
生成检查报告，用表格展示每项的通过/失败状态

验证标准：

对 Agent 说"我要部署了，帮我检查一下"
Agent 逐项执行检查
最终输出一个清晰的检查报告，标明哪些通过了哪些没通过

进阶挑战：组合使用 MCP + Skills

如果你已经在第11章配置了 GitHub MCP Server，试试这个：

创建一个 issue-triage.md Skill
Skill 内容：定义你的 Issue 分类规范（Bug / Feature / Enhancement / Question）、标签规则、优先级定义
结合 GitHub MCP 工具，让 Agent 自动对新 Issue 进行分类和标签

这个练习综合了 MCP（提供 GitHub 操作工具）和 Skills（提供分类知识），是非常贴近真实工作场景的用法。

本章小结

来回顾一下这一章学到的要点：

Skills 是什么：Skills 是 Markdown 文件，给 Agent 注入领域知识和操作指南。MCP 给工具（能力），Skills 给知识（智慧）。
文件格式：放在 .claude/skills/ 目录下，包含 YAML frontmatter（name + description）和 Markdown 正文（工作流程 + 规则 + 异常处理）。
description 是灵魂：Agent 根据 description 来判断什么时候触发哪个 Skill。写得好，Agent 就聪明；写得差，Agent 就迷糊。
两级加载：用户级（~/.claude/skills/，通用）和项目级（.claude/skills/，专用），项目级优先。
设计六原则：
- description 要精准
- 指令要步骤化
- 包含异常处理
- 明确指定工具
- 留有弹性
- 保持专注（一个 Skill 一件事）
三者对比：
- MCP = 手臂（提供能力）
- Skills = 经验（提供知识）
- Subagents = 同事（提供帮手）
- 三者配合使用效果最好
Skills 生态：可以用 Git 管理个人 Skills 库，团队可以共享 Skills 确保一致性，社区正在形成 Skills 分享的生态。

下一章预告

到这一章为止，第三篇"学跑步"就全部结束了。你已经掌握了自定义工具、MCP 协议、Hooks、多 Agent 协作和 Skills —— 这些是构建复杂 Agent 系统的全部核心技术。

下一章我们进入第四篇"上赛道"，开始聊生产部署的话题。第15章会讲 System Prompt 工程 —— 怎么给 Agent 写一份好的"人设说明书"，让它在真实场景中表现得稳定、可靠、符合预期。这是从"Demo 级 Agent"到"生产级 Agent"的关键一步。