Claude Code Skills 与 Agents 完全指南

一、概念辨析：Skill vs Agent

在深入用法之前，需要先厘清 Skills 和 Agents 的关系。Claude Code 提供了四种扩展机制：MCP 服务器、Skills、自定义 Agents 和 Hooks。其中，Skills 和 Agents 是两种互补的能力扩展方式，而非线性进阶关系：

· Skills：可插拔的能力扩展包，每个 Skill 是一个 SKILL.md 文件夹，为 Claude 注入专项能力，用 /skill-name 即可调用。它教 Claude 遵循自定义工作流，本质上是可复用的指令集。 · Agents（Sub-agents）：隔离上下文中的专用 AI 助手，拥有独立的工具限制、自定义系统提示和指定模型。Claude 可以自动将任务委托给子代理执行。

简单类比：Subagents 是在自己工作空间中的专家，而 Skills 是为主代理添加专业知识。

二、Skills 详细指南

2.1 Skill 是什么

Skill 本质上是一个文件夹，其中包含一个 SKILL.md 文件。该文件分为两部分：顶部的 YAML frontmatter 和下方的 Markdown 正文。

my-skill/
└── SKILL.md

Frontmatter 告诉代理技能的名称和何时使用它，正文则告诉代理加载该技能后应该做什么。

2.2 Skill 的自动触发机制

Skill 的自动触发依赖于 description 字段。Skills 在 Claude Code 的上下文中以名称和描述列表的形式出现，当用户发出请求时，代理会扫描该列表并加载任何描述与请求匹配的 Skill。

这意味着 description 写得越精准，Skill 被正确触发的概率越高。

2.3 创建第一个 Skill

步骤一：创建 Skill 目录

# 个人全局 Skill（所有项目可用）
mkdir -p ~/.claude/skills/my-skill

# 项目级 Skill（仅当前项目）
mkdir -p .claude/skills/my-skill

步骤二：编写 SKILL.md

以 commit-message-writer 为例：

---
name: commit-message-writer
description: Generates structured commit messages following Conventional Commits. Use when writing commit messages or when the user mentions "commit", "commit message", or wants to describe staged changes.
---

# Commit Message Writer

You are a commit message writer. Follow these rules:

1. Read the staged changes using `git diff --cached`
2. Determine the change type: feat, fix, docs, style, refactor, perf, test, chore
3. Identify the scope (optional) - the module or component affected
4. Write a concise subject line under 50 characters
5. Add a blank line, then a detailed body explaining what changed and why
6. Format: `<type>(<scope>): <subject>\n\n<body>`

Example output:

feat(auth): add JWT token refresh mechanism

· Implement refresh token rotation · Add expiry validation middleware · Update authentication service tests

步骤三：测试 Skill

在 Claude Code 会话中，你可以：

· 显式调用：/commit-message-writer · 自然语言触发：说 “帮我写个 commit message”

2.4 Skill 存储位置与优先级

存储位置物理路径适用范围 Personal ~/.claude/skills/ 当前用户的所有项目 Project .claude/skills/ 当前代码库的所有开发者 Plugin 随插件包发布安装插件的用户 Enterprise 企业托管设置组织内所有成员

优先级（从高到低）：Enterprise → Personal → Project → Plugin。

2.5 渐进式披露机制

Skills 采用三层渐进式披露设计：

元数据（第一层）：启动时预加载所有 Skill 的 name 和 description
技能主体（第二层）：判定相关后加载完整的 SKILL.md
附加文件和脚本（第三层）：仅在需要时加载引用的脚本和文档

这种设计确保上下文窗口不被无关内容占用，让 Skill 可以包含海量信息而不担心 token 溢出。

2.6 安装官方 Skills

# 注册官方 Skills 仓库为插件源
/plugin marketplace add anthropics/skills

# 安装文档处理包（含 pdf/xlsx/docx/pptx）
/plugin install document-skills@anthropic-agent-skills

Anthropic 官方提供了 17 个开源 Skills，涵盖 PDF、Excel、Word、PPT 处理、前端设计、数据分析等。

2.7 10 个必装 Skills 精选

以下来自社区推荐的必装 Skills：

pdf — PDF 全能处理（提取文字/表格、合并/拆分、OCR 等）
xlsx — Excel/表格处理（读取修改、数据清洗、图表制作）
docx — Word 文档处理（创建、编辑、格式转换）
data-analysis — 全链路数据分析（探查→质检→执行→报告）
frontend-design — 高质量前端界面（React 组件、Dashboard 等）

三、Agents（Sub-agents）详解

3.1 Agent 是什么

Sub-agent 是 Claude Code 中的一项能力：一个独立的代理循环，带有全新的 token 上下文，被派去完成一个目标，完成后返回报告。Sub-agents 的关键优势：

· 上下文隔离：每个子代理有独立的上下文窗口，不污染主代理的对话 · 并行执行：多个子代理可同时运行，提升效率 · 专注分工：每个子代理可配置专属系统提示、模型和工具权限

3.2 如何使用 Sub-agents

最简单的方式是直接在对话中告诉 Claude 使用子代理：

“Write markdown documentation for the context passed to each of the templates in this project. Use sub-agents.”

Claude 会自动将任务拆解为多个子任务，派发子代理并行执行，然后汇总结果。Simon Willison 测试时，Claude 派发了 5 个子代理并行处理模板文档，总耗时约 2 分钟。

3.3 配置自定义 Agent

在 .claude/agents/ 目录下创建 Markdown 文件来定义自定义 Agent：

.claude/agents/
├── coder.md
└── reviewer.md

示例：coder.md

---
name: coder
model: claude-sonnet-4
description: Senior TypeScript engineer, writes clean production code
---

You are a senior TypeScript engineer. Follow strict type safety, use functional patterns where appropriate, write unit tests alongside implementation, and ensure all code passes ESLint and Prettier.

示例：reviewer.md

---
name: reviewer
model: claude-sonnet-4
description: Principal engineer reviewer, focuses on architecture and security
tools: ["Read", "Grep", "Glob"]  # 只读权限，不能修改代码
---

You are a principal engineer conducting code review. Focus on architecture patterns, security vulnerabilities, performance issues, and test coverage.

3.4 自动化 Coder-Reviewer 循环

claude-code-loops 是一个 npm 包，可以快速搭建自动化 Coder-Reviewer 循环：

cd your-project
npx ccl init

echo "Add input validation to all API endpoints" > task.md
bash scripts/loop.sh task.md

该循环的工作流程为：coder → commit → build gate → reviewer → 重复（最多 10 次迭代），当测试通过且 reviewer 给出 LGTM 时自动停止。Coder 和 Reviewer 运行在独立的上下文窗口中，Reviewer 看不到 Coder 的推理过程，确保真正独立的代码审查。

四、典型案例

4.1 模板文档并行生成（Simon Willison）

场景：为 Datasette 项目的所有模板生成上下文文档。

用户输入：Write markdown documentation for the context passed to each of the templates in this project. Use sub-agents.

Claude 的行为：

· 搜索了 47 个模板文件 · 派发了 5 个子代理并行分析不同类型的模板上下文 · 各子代理独立执行（12-26 次工具调用，55k-116k tokens） · 最终生成一份完整的 template_contexts.md 文档

4.2 企业级自动化开发系统（ChrisWiles 4277星项目）

这是一套完整的 Claude Code 配置系统，包含：

· 7 个 Skills：testing-patterns、api-design、数据库模式等 · 2 个专用 Agents：code-reviewer、architect-advisor · 6 个 Commands：快捷指令 · Hooks：自动激活 Skills · GitHub Actions：定时巡检 · MCP 服务器：集成 JIRA、Slack

一个典型工作流：用户输入 /ticket PROJ-123 → Hook 自动激活 JIRA Skills → MCP 从 JIRA 读取 ticket 详情 → Agent 搜索代码库 → Claude 按规范生成代码 → GitHub Actions 自动质检。

4.3 金融风控场景 Sub-agent 架构

在金融风控系统中采用 Sub-agent 架构后，系统吞吐量提升 3.2 倍，单任务处理延迟降低 57%。通过将复杂任务拆解为条款提取、风险评估、合规检查三个子代理协同完成，体现了“分而治之”的工程哲学。

4.4 协调器 Skill + 专家 Agent 团队系统

一种突破性的架构设计：通过“协调器 Skill + 专家 Agent”组合实现多专家自动协作。基于两个实战案例——代码先锋（Code Vanguard）和解构重筑者（Deconstructors），构建了完整的 AI 专家团队系统。

五、Commands、Skills、Agents 协作三角

Commands、Skills 和 Agents 并非线性进阶关系，而是不同协作粒度的互补机制：

机制运行机制核心用途 Commands 用户手动输入触发执行重复性原子操作 Skills 根据需求自动匹配描述触发提供专业知识或操作标准 Agents Claude 委派或用户显式调用隔离上下文中处理复杂子任务

这三者构成“协作三角”：Commands 用于即时原子操作，Skills 封装可复用专业能力，Agents 承担目标导向的自主任务。

六、总结与建议

何时使用 Skill vs Agent？

场景推荐使用需要教授 Claude 团队编码规范 Skill 需要生成特定格式的输出（commit message、PR 描述） Skill 需要执行多步骤、可重复的工作流 Skill 需要隔离上下文执行复杂子任务 Agent 需要并行处理多个独立任务 Agent 需要不同权限级别（如只读 reviewer） Agent 需要整合外部工具/API MCP + Skill

学习路径建议

从 CLAUDE.md 开始，定义项目级的全局指令和规范
创建 Commands 封装高频操作的快捷方式
开发 Skills 固化可复用工作流和领域知识
引入 Agents 处理复杂任务的隔离和并行
组合使用 Hooks 实现自动化生命周期触发

Skills 遵循 AgentSkills.io 开放标准，同一份 SKILL.md 文件可在 Claude Code、GitHub Copilot、Cursor 和 Gemini CLI 中使用，具有极好的跨平台可移植性。

没问题，我找到了一些很棒的中文实例，可以帮你更好地理解。Claude Code的Skills和Agents就像是给AI助手搭建的专业“团队”与“工具箱”。

下面是一份结合了具体案例的中文指南，希望可以帮到你。

中文实战案例集锦

· 案例一：API接口生成器 Skill (告别重复粘贴) 一位开发者在重构React项目时，将“TypeScript严格模式”、“错误处理”等要求封装成一个react-refactor Skill。现在只需一句 @react-refactor 就能调用，将原本三天的重构任务缩短至两个下午。 · 案例二：中文技术栈增强 Skill (为国内开发者定制) 有社区用户发现官方Skills生态缺乏对国内技术栈的支持，于是开源了claude-code-zh增强包。安装spring-boot-ddd Skill后，Claude Code就能直接生成符合DDD规范的四层架构代码（领域模型充血、依赖方向正确），而不是简单的贫血模型。 · 案例三：AI测试用例生成器 Skill (提升开发效率) 通过创建一个单元测试生成器 Skill，AI能根据函数代码自动分析逻辑，生成包含边界、正常和异常情况的完整测试用例，节省手动编写时间。 · 案例四：10个即用子代理模板 (组建你的AI小分队) 与其让AI一次性“重构、找bug、写测试”，不如为它分配专属角色，如代码重构专家、Bug分析专家、安全审查专家等，让每个子代理只专注一件事，输出更稳定可靠。 · 案例五：自动化写作流水线 (90%的效率提升) 一位创作者通过将Kimi-K2模型与Claude Code的Subagents和Skills结合，设计了一条自动化写作流水线。这条流水线能帮他完成从资料收集到文章撰写的多项任务，最终节省了高达90% 的文章写作时间。 · 案例六：协调器Skill + 专家Agent (实现团队协作) 针对Claude Code子代理间无法互相调用的限制，有开发者提出“协调器Skill + 专家Agent”的轻量级架构。由协调器在主代理层面分析需求、制定计划并调度专家Agent，实现了架构设计、编码、测试等多角色协同。

快速上手指南 (中文版)

这部分我会用纯中文示例，带你快速创建第一个Skill和Agent。

打造你的第一个中文Skill

我们以创建一个“周报生成器”Skill为例。

创建目录和文件：在你的项目根目录下执行以下命令。

# 创建Skill目录
mkdir -p .claude/skills/week-report

# 创建并编辑SKILL.md文件 (将下面代码块内容粘贴进去)
cat > .claude/skills/week-report/SKILL.md << 'EOF'
---
name: 周报生成器
description: 自动生成周报，支持中文，带任务清单、问题、计划。当用户说“写周报”、“周报生成”时使用。
version: 1.0
---
# 周报生成技能

## 你的任务
- 根据用户提供的本周完成事项、遇到的问题和下周计划，自动整理成标准格式并输出Markdown。

## 输出模板
**本周完成**
- ...

**阻塞&问题**
- ...

**下周计划**
- ...

**需要支持**
- ...
EOF

重启Claude Code并测试：重启后，在聊天界面直接说：用周报生成器帮我写这周的周报：本周完成了登录页和支付接口对接，卡在了一个第三方SDK的兼容性问题。下周准备做用户中心和权限系统，Claude就会自动套用模板了！

配置一个中文专家Agent

现在，我们来创建一个专门审查代码的“资深审查员”Agent。

创建配置文件：在项目根目录执行以下命令。

mkdir -p .claude/agents/
cat > .claude/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: 专家代码审查员。用于审查代码的质量、安全性和可维护性。当用户说“审查代码”、“代码Review”或“检查这段代码”时使用。
tools: Read, Grep, Glob, Bash
model: inherit
---
您是一位确保高标准代码质量和安全性的高级代码审查员。
被调用时：
2. 运行 `git diff` 查看最近的更改。
3. 专注于修改的文件，并立即开始审查。

## 审查清单
- 代码是否简单易读？
- 命名是否良好？
- 有没有重复代码？
- 是否有适当的错误处理？
- 是否泄露了 API 密钥或敏感信息？
- 是否进行了必要的输入验证？

## 输出格式
按优先级反馈：
- **关键问题**（必须修复）
- **警告**（建议修复）
- **建议**（可以改进的点）

请提供具体修复示例。
EOF

使用方法：配置完成后，当你需要审查代码时，直接在Claude Code中说使用 code-reviewer 子代理检查我最近的更改即可。

中文常用Skills速查表

Skill 名称描述适用场景周报生成器自动将碎片化信息整理为格式化的周报。每周工作总结、进度汇报。 API文档生成器根据代码或接口描述生成标准的OpenAPI文档。后端接口开发、团队协作与对接。单元测试生成器为Python/JS/Go函数自动生成测试用例。提升代码质量和测试覆盖率。 Spring Boot DDD 指导AI生成符合DDD规范的四层架构代码。 Java后端项目开发，特别是采用DDD思想时。

中文常用Agents速查表

Agent 名称描述适用场景 code-reviewer 专家代码审查员，专注于代码质量、安全与可维护性。代码提交前审查、PR Review。 debugger 调试专家，擅长分析错误和测试失败的原因。遇到Bug、测试报错时。测试用例生成器自动为代码生成全面的单元测试。需要快速为现有代码补充测试。安全审查专家专门审查代码中的安全漏洞和隐患。涉及认证、授权、数据处理等关键模块开发时。

总结

简单来说，Skills（能力包）负责固化你的“专业知识与规范”，让你能一键调用；而 Agents（专家代理）则帮你组建一支各司其职的“AI专家小分队”，专门处理复杂任务。

掌握了这两种模式，你就不仅能“用”AI，更是在“指挥”一支高效的AI开发团队了。