第十八篇：Agent怎么用？区分Commands（即时指令）、Skills（复用能力）、Agents（自主任务）

📌 标签 ：#Agent模式 #Commands #Skills #能力分层

Claude Code 的能力远不止"聊天框里问问题"。它有三层能力体系：Commands 用于高频即时指令，Skills 用于封装可复用的复杂流程，Agents 用于全自动任务执行。理解这三者的区别，你就能从"临时用用"升级到"构建自己的 AI 工具箱"。

---

1. 三层能力速览

层次	触发方式	特点	适用场景	类比
Commands	/命令名	短小、即时、无需配置	高频重复动作（查看成本、清屏、切换模式）	快捷键
Skills	对话中自然触发或 /skill	可复用、可分享、有参数	标准化工作流（生成 PR 描述、创建新组件、运行特定测试）	函数/宏
Agents	自然语言任务描述	自主规划、多步执行、自适应	复杂、一次性的任务（重构模块、调试 bug、迁移代码）	实习生

很多人只用到了 Commands，偶尔用用 Agents，却忽略了最强大的 Skills------团队共享、可积累的 AI 能力资产。

---

2. Commands：即插即用的快捷键

2.1 什么是 Commands？

Commands 是 Claude Code 内置或用户自定义的斜杠快捷指令。它们通常执行一个明确的、不需要多轮对话的操作。

内置 Commands（第 3 篇已介绍）：

• /help、/compact、/clear、/cost、/exit、/mode

实验性/高级内置 Commands：

• /model：切换 Claude 模型
• /add-dir：添加额外目录到上下文
• /init：在当前目录初始化 CLAUDE.md 模板

2.2 自定义 Commands

你可以在项目根目录的 .claude/commands/ 下创建自己的命令。

示例 ：创建一个 /fix-lint 命令，自动修复 ESLint 问题。

创建文件 .claude/commands/fix-lint.md：

---
description: 自动修复当前项目的 ESLint 错误和警告
---

请执行以下步骤：
1. 运行 `npm run lint -- --fix`（如果项目有该脚本）
2. 如果没有，则运行 `npx eslint . --fix`
3. 检查修改了哪些文件，输出文件列表
4. 如果有无法自动修复的错误，列出它们并给出建议

然后你就可以在 Claude Code 中输入 /fix-lint，AI 会执行这个预定义流程。

自定义命令的优点：

• 将重复性工作封装成快捷指令，节省打字时间
• 可以团队共享（提交到 Git）
• 比自然语言更精准（避免歧义）

2.3 何时用 Commands？

• 每天要执行多次的固定操作（如查看成本、清空上下文）
• 有明确步骤但步骤数较少（3-5 步）的任务
• 不需要复杂决策或条件分支的流程

---

3. Skills：可复用的 AI 能力包

3.1 什么是 Skills？

Skills 是 Claude Code 中最具扩展性的能力层。它是一个结构化的提示词模板，可以包含参数、条件逻辑、工具调用，甚至多个步骤。Skills 可以像函数一样被调用，也可以被 AI 在适当时机自动推荐。

Skills 与 Commands 的区别：

• Commands 是用户主动调用的快捷方式。
• Skills 既可以用户主动调用 (/skill name)，也可以在对话中由 AI 根据上下文自动选择并建议使用。

3.2 Skill 的文件结构

Skills 存储在 .claude/skills/ 目录下，每个 Skill 是一个 .md 文件，包含 Frontmatter 元数据和指令内容。

示例 ：创建一个 generate-api-docs Skill。

.claude/skills/generate-api-docs.md：

---
name: generate-api-docs
description: 根据控制器代码生成 API 文档（Markdown 格式）
version: 1.0.0
parameters:
  - name: controller_path
    description: 控制器文件路径，如 src/controllers/UserController.js
    required: true
  - name: output_path
    description: 输出文档路径，默认为 docs/api.md
    required: false
---

# Skill: 生成 API 文档

## 输入
- 控制器文件：{{controller_path}}
- 输出文件：{{output_path || "docs/api.md"}}

## 执行步骤
1. 读取 `{{controller_path}}`，识别所有路由处理函数（Express 或 Fastify 风格）
2. 提取每个路由的 HTTP 方法、路径、参数、请求体格式、返回值
3. 如果存在 JSDoc 注释，优先使用其中的描述
4. 生成 Markdown 表格，包含：端点、方法、参数、描述
5. 将文档写入 `{{output_path}}`，如果文件已存在则追加（保留手动编写的内容）

## 验证
- 确保生成的文档至少包含一个端点
- 检查是否有明显的格式错误（如未闭合的表格）

3.3 如何调用 Skills

方式一：自然语言触发

用 generate-api-docs 技能为 src/controllers/ProductController.js 生成文档，输出到 docs/product-api.md

AI 会识别 generate-api-docs 这个 Skill 名称并执行。

方式二：显式调用

/skill generate-api-docs controller_path=src/controllers/UserController.js

方式三：AI 自动建议

当你输入"生成 API 文档"时，AI 可能会提示：

我注意到你有一个技能 "generate-api-docs" 可以完成这个任务。是否要使用？(y/n)

3.4 高级 Skills：条件逻辑与多步骤

Skills 可以包含条件分支、循环和错误处理（通过自然语言描述）。

示例 Skill：refactor-to-typescript

---
name: refactor-to-typescript
description: 将 JavaScript 文件转换为 TypeScript，包括添加类型定义、修改导入导出
---

# Skill: JS 到 TS 迁移

## 步骤
1. 读取目标 `.js` 文件，分析其导出内容
2. 检查项目中是否已有 `.d.ts` 类型定义文件。如果有，优先复用；如果没有，根据代码推断类型。
3. 创建 `.ts` 文件，将代码复制过去。
4. 为函数参数和返回值添加类型注解。如果推断复杂，使用 `any` 但添加 `// TODO: 改进类型` 注释。
5. 修改所有引用该文件的导入语句，将 `.js` 扩展名改为 `.ts`（如果项目配置允许省略扩展名，则只改导入路径）。
6. 运行 `tsc --noEmit` 检查类型错误，自动修复可修复的错误。
7. 如果错误无法修复，输出错误列表并请求用户介入。

## 条件逻辑
- 如果文件已经存在同名的 `.d.ts`，跳过类型推断步骤，直接引用。
- 如果文件使用了 CommonJS (`module.exports`)，保留原格式或询问用户是否转为 ES modules。

3.5 何时用 Skills？

• 标准化流程：代码审查、文档生成、测试脚手架、依赖升级检查。
• 团队协作：确保所有人用相同的方式使用 AI（而不是每人一套 prompt）。
• 积累最佳实践：将你摸索出的高效工作流固化，供未来复用。
• 复杂但确定的任务：步骤较多（10-20 步），但逻辑相对固定。

---

4. Agents：自主任务执行者

4.1 什么是 Agents？

Agents 是 Claude Code 的默认运行模式 ------当你输入一个自然语言任务而不使用 /command 或调用 Skill 时，AI 自动进入 Agent 模式。

Agent 的特点是：

• 自主规划：AI 自己决定需要读哪些文件、执行哪些命令、调用哪些工具。
• 多步迭代：可以执行几十轮工具调用，直到完成任务。
• 自适应：遇到错误能尝试其他路径，不需要你提前规定所有步骤。

4.2 Agent 与 Skill 的关系

• Skill 是 Agent 的模板：一个 Skill 本质上是一个"精心设计的 Agent 初始指令 + 参数约束"。
• Agent 是灵活的执行器：即使没有预定义 Skill，Agent 也能完成任务，只是可能效率较低或容易走弯路。

换句话说：

Skill = 预设好路线的导航
Agent = 只给目的地，自己找路

4.3 何时用 Agents？

• 探索性任务：你不知道具体步骤，让 AI 自己摸索。
• 一次性复杂任务：重构、迁移、调试，不会经常做第二次。
• 任务逻辑不确定：需要根据中间结果调整后续步骤（如"修复所有失败的测试"）。

如果你发现某个 Agent 任务成功且以后还会再用，就应该把它封装成 Skill。

---

5. 三者对比与选型决策树

用户需求
    │
    ├─ 是高频重复动作？ ────→ Yes ──→ 用 Command
    │                           （如 /cost, /clear）
    │
    ├─ 有标准化流程且会反复用？ ──→ Yes ──→ 用 Skill
    │                              （如 /skill generate-api-docs）
    │
    └─ 复杂、一次性、不确定步骤？ ──→ Yes ──→ 用 Agent
                                   （自然语言描述）

实际案例决策：

需求	选哪个	原因
清空当前会话上下文	Command (/clear)	一步操作，无变化
每次写新组件都要生成同名测试文件	Skill (/skill add-test)	流程固定，可参数化
今天刚发现的诡异 bug，不知道原因	Agent	需要 AI 探索，无法预先定义步骤
每天看成本	Command (/cost)	极简
将项目从 Webpack 迁移到 Vite	Agent（然后可选封装 Skill）	复杂、多步骤，但成功后可以封装供团队复用

---

6. 实战：从 Agent 到 Skill 的演进

初始阶段：你有一个任务"为新功能生成 PR 描述"。你输入：

分析当前分支相比于 main 的变更，生成一份 PR 描述，包括变更摘要、测试情况、截图链接占位符。

Agent 执行成功，输出了一份漂亮的描述。第二天你又需要做同样的事，再次输入一模一样的自然语言。第三天......

优化阶段：你发现这个任务步骤固定（git diff → 读变更文件 → 分析影响范围 → 生成 Markdown）。于是你将其封装为 Skill。

创建 .claude/skills/generate-pr-description.md：

---
name: generate-pr-description
description: 根据 git diff 生成标准 PR 描述
---

# Skill: 生成 PR 描述

## 步骤
1. 运行 `git diff main...HEAD --stat` 获取变更统计
2. 运行 `git diff main...HEAD --name-only` 获取变更文件列表
3. 读取关键文件（如 package.json、README、主要业务逻辑文件）了解变更意图
4. 生成以下格式的描述：

## 变更摘要
[一句话总结]

## 详细变更
- [文件A]: [修改说明]
- [文件B]: [修改说明]

## 测试
- [ ] 单元测试通过
- [ ] 手动测试：[场景]

## 截图
（待补充）

5. 将生成的描述保存到 `.github/PULL_REQUEST_TEMPLATE/draft.md`，并告知用户已准备就绪。

然后每次只需输入 /skill generate-pr-description，10 秒内获得标准化 PR 描述。

---

7. 团队共享 Skills

Skills 文件存储在项目目录的 .claude/skills/ 下，可以提交到 Git。团队成员 clone 仓库后，所有 Skills 自动可用。

团队最佳实践：

• 建立 skills/README.md，列出所有可用 Skill 及用途。
• 定期 code review Skills 本身（AI 的指令也需要维护）。
• 为 Skill 添加版本号，变更时更新日志。

示例团队 Skill 库：

• enforce-code-style：自动格式化并修复常见风格问题
• write-changelog：根据 Git log 生成 CHANGELOG.md 草稿
• security-audit：运行 npm audit 并尝试自动修复非破坏性漏洞
• db-migration-review：检查 Prisma 迁移文件是否可逆

---

8. 常见问题

Q1: Command 和 Skill 的区别好像很模糊？

Command 通常没有参数或参数极简，适合"开关"类操作。Skill 可以有结构化参数、复杂逻辑、多步骤。技术上，你也可以把 Command 实现为调用 Skill，但直接内置 Command 更快。

Q2: 我可以覆盖内置 Command 吗？

可以。在 .claude/commands/ 下创建同名文件（如 help.md）会覆盖内置 /help。不建议，除非你确定需要。

Q3: Skill 的调用是否消耗 token？

是的。Skill 的内容（即 .md 文件）会被注入到上下文中，相当于你手动输入了那些指令。但 Skill 通常设计得简洁高效，比每次重新描述节省 token。

Q4: Agent 会主动建议使用 Skill 吗？

目前（2026 年版本）需要用户事先启用"自动技能建议"设置（/settings 中开启）。未来版本可能会默认开启。

Q5: 我可以从社区下载 Skills 吗？

Anthropic 尚未提供官方 Skills 市场，但你可以手动导入他人分享的 .md 文件。注意安全审查。

---

9. 下篇预告

掌握了 Commands、Skills、Agents 的分层能力，你的 Claude Code 使用水平已经超过 90% 的用户。但 AI 的"记忆"和"预算"是有限的------下一篇我们将学习 Token 与配额管理：如何控制成本、不烧穿 AI 预算。

👉 下一篇： Token与配额管理：如何控制成本、不烧穿AI预算

---

思考题（自测理解）

1. 你每天要运行三次 npm run test:unit -- --watch。你会创建一个 Command、Skill 还是直接用 Agent？为什么？
2. 团队有一个标准化流程：每次发版前，需要更新版本号、生成 changelog、打 tag、推送到 GitHub。请设计一个 Skill 的大致结构（写出步骤即可）。
3. 假设你写了一个 Skill "refactor-react-to-vue"，但它的步骤中有一步需要用户确认是否保留原有的 React Hooks 逻辑。你如何在 Skill 中表达这个条件分支？

---

Commands 是快手，Skills 是工匠，Agents 是探险家。学会在正确的时间用正确的角色。下一站，我们聊聊"钱"------Token 配额。