Anthropic 官方指南：构建 Skills 的秘密都在这里

本文将带你全面了解 Claude Agent Skills 的构建方法，从基础概念到实战应用，帮助你快速掌握这一强大的 AI 定制化工具。

前言

你是否遇到过这样的场景：每次和 AI 助手对话，都要重新解释一遍你的偏好、工作流程和领域知识？或者你希望 AI 能够按照特定的流程来处理任务，但每次都需要详细说明？

Agent Skills（智能体技能） 就是为了解决这些痛点而生的。它允许你将特定的工作流程、最佳实践和领域知识打包成可复用的"技能包"，让 AI 一次学习，终身受益。

本文将基于 Anthropic 官方发布的《The Complete Guide to Building Skills for Claude》，带你深入理解 Agent Skills 的核心原理和实战应用。

适合人群

希望定制 AI 工作流的开发者
需要标准化团队 AI 使用的团队负责人
对 AI Agent 技术感兴趣的技术人员
想要提升 AI 使用效率的工程师

你将学到

Agent Skills 的核心概念和设计原则
如何规划和设计一个高质量的 Skill
实战案例：从零构建一个完整的 Skill
常见问题和最佳实践

一、什么是 Agent Skills？

1.1 核心定义

Skill 是一个包含指令集的文件夹，它教会 AI 如何处理特定任务或工作流程。可以将它理解为 AI 的"专业技能证书"。

1.2 为什么需要 Skills？

传统方式的痛点：

markdown 复制代码

❌ 每次对话都要重复解释需求
❌ 输出结果不一致，取决于提示词质量
❌ 团队协作时难以标准化流程
❌ 复杂工作流难以可靠执行

使用 Skills 的优势：

markdown 复制代码

✅ 一次配置，多次复用
✅ 标准化的输出质量
✅ 团队知识沉淀和共享
✅ 复杂流程自动化执行

1.3 典型应用场景

场景类型	示例	价值
文档创建	技术文档、报告、演示文稿	保证格式统一、风格一致
工作流自动化	项目规划、数据分析流程	减少人工干预、提高效率
MCP 增强	与 Notion、Linear 等工具集成	提供最佳实践指导

二、核心架构与设计原则

2.1 文件结构

一个标准的 Skill 文件夹结构如下：

perl 复制代码

my-skill/
├── SKILL.md          # 必需 - 主技能文件
├── scripts/          # 可选 - 可执行脚本
│   ├── validate.py   # 验证脚本
│   └── process.sh    # 处理脚本
├── references/       # 可选 - 参考文档
│   ├── api-guide.md  # API 指南
│   └── examples/     # 示例目录
└── assets/           # 可选 - 资源文件
    └── template.md   # 模板文件

2.2 核心设计原则

原则 1：渐进式披露（Progressive Disclosure）

Skill 采用三层信息加载机制：

yaml 复制代码

# 第一层：YAML Frontmatter（始终加载）
---
name: my-skill
description: 简短描述，用于触发判断
---

# 第二层：SKILL.md 主体（按需加载）
完整的指令和指导内容

# 第三层：链接文件（按需访问）
references/ 和 assets/ 中的详细文档

设计意图： 最小化 Token 使用，同时保持专业性。

原则 2：可组合性（Composability）

多个 Skills 可以同时加载，每个 Skill 应该：

不假设自己是唯一的能力
与其他 Skills 协同工作
避免功能冲突

原则 3：可移植性（Portability）

一次创建，多平台使用：

Claude.ai
Claude Code
API 调用

2.3 YAML Frontmatter 详解

Frontmatter 是 Skill 的"元数据卡片"，决定了何时触发这个技能。

必需字段：

yaml 复制代码

---
name: skill-name-in-kebab-case    # kebab-case 格式
description: |                     # 必须包含两部分
  [做什么] + [何时使用] + [触发短语]
---

可选字段：

yaml 复制代码

---
name: my-skill
description: 处理 PDF 文档并生成摘要。当用户说"总结 PDF"、"提取文档要点"时使用。
license: MIT                       # 开源许可证
metadata:                          # 自定义元数据
  author: Your Name
  version: 1.0.0
  mcp-server: notion              # 关联的 MCP 服务器
---

安全限制：

❌ 禁止使用 XML 标签（< >）
❌ 名称不能包含 claude 或 anthropic（保留字）

三、规划与设计实战

3.1 明确使用场景

在编写任何代码之前，先明确 2-3 个具体的使用场景。

好的场景定义示例：

markdown 复制代码

Use Case: 项目冲刺规划
Trigger: 用户说"帮我规划这次冲刺"或"创建冲刺任务"
Steps:
  1. 从 Linear 获取当前项目状态（通过 MCP）
  2. 分析团队速度和容量
  3. 建议任务优先级
  4. 在 Linear 中创建带有正确标签和估算的任务
Result: 完全规划好的冲刺，任务已创建

3.2 选择 Skill 类别

根据 Anthropic 的观察，常见的 Skill 类别有三种：

类别 1：文档与资产创建

用途： 创建一致性、高质量的输出

关键技术：

嵌入式风格指南和品牌标准
模板结构保证输出一致
质量检查清单

示例： frontend-design Skill

yaml 复制代码

name: frontend-design
description: 创建独特的、生产级前端界面。用于构建 Web 组件、页面、应用或设计。

类别 2：工作流自动化

用途： 多步骤流程，需要一致的方法论

关键技术：

带验证关卡的逐步工作流
常见结构的模板
内置审查和改进建议

示例： skill-creator Skill

yaml 复制代码

name: skill-creator
description: 创建新技能的交互式指南。引导用户完成用例定义、前置条件生成、指令编写和验证。

类别 3：MCP 增强

用途： 为 MCP 服务器提供的工具访问增加工作流指导

关键技术：

协调多个 MCP 调用序列
嵌入领域专业知识
为常见 MCP 问题提供错误处理

示例： sentry-code-review Skill

yaml 复制代码

name: sentry-code-review
description: 使用 Sentry 错误监控数据自动分析和修复 GitHub PR 中的检测错误。

3.3 定义成功标准

如何知道你的 Skill 是否有效？

定量指标：

指标	目标值	测量方法
触发准确率	90%+	运行 10-20 个应该触发的测试查询
工具调用次数	减少 X%	对比有/无 Skill 的相同任务
API 调用失败率	0 次	监控 MCP 服务器日志

定性指标：

✅ 用户不需要提示下一步
✅ 工作流无需用户纠正即可完成
✅ 跨会话结果一致
✅ 新用户首次即可完成任务

四、编写高质量 Skill

4.1 撰写 Description 字段

黄金公式：

css 复制代码

[做什么] + [何时使用] + [关键能力]

优秀示例：

yaml 复制代码

# ✅ 具体、可操作
description: 分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、询问"设计规范"、"组件文档"或"设计转代码交接"时使用。

# ✅ 包含触发短语
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到"冲刺"、"Linear 任务"、"项目规划"或要求"创建工单"时使用。

# ✅ 清晰的价值主张
description: PayFlow 端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说"入职新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

反面示例：

yaml 复制代码

# ❌ 太模糊
description: 帮助处理项目。

# ❌ 缺少触发条件
description: 创建复杂的多页文档系统。

# ❌ 过于技术化，没有用户触发
description: 实现具有层次关系的项目实体模型。

4.2 编写主要指令

推荐结构模板：

markdown 复制代码

---
name: your-skill
description: [描述]
---

# 你的技能名称

## 指令

### 步骤 1：[第一个主要步骤]
清晰的步骤说明。

```bash
python scripts/fetch_data.py --project-id PROJECT_ID

预期输出：[描述成功的结果]

（根据需要添加更多步骤）

示例

示例 1：[常见场景]

用户说："设置一个新的营销活动"

操作：

通过 MCP 获取现有活动
使用提供的参数创建新活动结果：活动已创建，带有确认链接

（添加更多示例）

故障排除

错误：[常见错误消息]

原因：[为什么发生] 解决方案：[如何修复]

（添加更多错误案例）

shell 复制代码

### 4.3 最佳实践

#### 1. 具体且可操作

```markdown
# ✅ 好的示例
运行 `python scripts/validate.py --input {filename}` 检查数据格式。
如果验证失败，常见问题包括：
- 缺少必需字段（添加到 CSV）
- 日期格式无效（使用 YYYY-MM-DD）

# ❌ 不好的示例
在继续之前验证数据。

2. 清晰引用资源

markdown 复制代码

在编写查询之前，请参考 `references/api-patterns.md` 了解：
- 速率限制指南
- 分页模式
- 错误代码和处理

3. 使用渐进式披露

保持 SKILL.md 聚焦于核心指令，将详细文档移至 references/。

4. 包含错误处理

markdown 复制代码

## 常见问题

### MCP 连接失败
如果看到 "Connection refused"：
1. 验证 MCP 服务器正在运行：检查 Settings > Extensions
2. 确认 API 密钥有效
3. 尝试重新连接：Settings > Extensions > [你的服务] > Reconnect

五、测试与迭代

5.1 测试方法

方法 1：手动测试（Claude.ai）

优点： 快速迭代，无需设置 适用： 初期开发、快速验证

方法 2：脚本化测试（Claude Code）

优点： 可重复验证，跨变更测试 适用： 稳定版本、回归测试

方法 3：程序化测试（Skills API）

优点： 系统化评估套件 适用： 企业部署、大规模使用

5.2 推荐测试流程

测试 1：触发测试

目标： 确保 Skill 在正确时机加载

测试用例：

markdown 复制代码

应该触发：
✅ "帮我设置一个新的 ProjectHub 工作区"
✅ "我需要在 ProjectHub 中创建一个项目"
✅ "为 Q4 规划初始化一个 ProjectHub 项目"

不应该触发：
❌ "旧金山的天气如何？"
❌ "帮我写 Python 代码"
❌ "创建一个电子表格"（除非 ProjectHub Skill 处理表格）

测试 2：功能测试

目标： 验证 Skill 产生正确输出

测试示例：

markdown 复制代码

测试：创建包含 5 个任务的项目
给定：项目名称 "Q4 Planning"，5 个任务描述
当：Skill 执行工作流
那么：
- 项目在 ProjectHub 中创建
- 5 个任务创建，属性正确
- 所有任务链接到项目
- 无 API 错误

测试 3：性能对比

目标： 证明 Skill 改善了结果

对比维度：

维度	无 Skill	有 Skill
用户指令	每次都要提供	自动执行
往返消息	15 条	2 条
API 失败	3 次	0 次
Token 消耗	12,000	6,000

5.3 迭代改进

问题 1：触发不足

信号：

Skill 不在应该加载时加载
用户手动启用
支持问题："何时使用？"

解决方案： 在描述中添加更多细节和关键词

问题 2：过度触发

信号：

Skill 为不相关查询加载
用户禁用它
对用途的困惑

解决方案： 添加负面触发器，更加具体

yaml 复制代码

description: CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用 data-viz skill）。

问题 3：指令未遵循

常见原因和解决方案：

原因	解决方案
指令过于冗长	保持简洁，使用项目符号
指令被埋没	将关键指令放在顶部，使用 `## Important`
语言模糊	使用明确的、命令式语言
模型"懒惰"	添加明确鼓励："花时间彻底完成"

六、常见模式与最佳实践

6.1 模式 1：顺序工作流编排

适用场景： 用户需要按特定顺序执行多步骤流程

示例结构：

markdown 复制代码

## 工作流：新客户入职

### 步骤 1：创建账户
调用 MCP 工具：`create_customer`
参数：name, email, company

### 步骤 2：设置支付
调用 MCP 工具：`setup_payment_method`
等待：支付方式验证

### 步骤 3：创建订阅
调用 MCP 工具：`create_subscription`
参数：plan_id, customer_id（来自步骤 1）

### 步骤 4：发送欢迎邮件
调用 MCP 工具：`send_email`
模板：welcome_email_template

关键技术：

显式步骤排序
步骤间依赖关系
每阶段验证
失败时的回滚指令

6.2 模式 2：多 MCP 协调

适用场景： 工作流跨多个服务

示例：设计到开发交接

markdown 复制代码

## 阶段 1：设计导出（Figma MCP）
1. 从 Figma 导出设计资产
2. 生成设计规范
3. 创建资产清单

## 阶段 2：资产存储（Drive MCP）
1. 在 Drive 中创建项目文件夹
2. 上传所有资产
3. 生成共享链接

## 阶段 3：任务创建（Linear MCP）
1. 创建开发任务
2. 将资产链接附加到任务
3. 分配给工程团队

## 阶段 4：通知（Slack MCP）
1. 在 #engineering 发布交接摘要
2. 包含资产链接和任务引用

关键技术：

清晰的阶段分离
MCP 间的数据传递
进入下一阶段前的验证
集中式错误处理

6.3 模式 3：迭代改进

适用场景： 输出质量随迭代提高

示例：报告生成

markdown 复制代码

## 初始草稿
1. 通过 MCP 获取数据
2. 生成第一版报告
3. 保存到临时文件

## 质量检查
1. 运行验证脚本：`scripts/check_report.py`
2. 识别问题：
   - 缺少章节
   - 格式不一致
   - 数据验证错误

## 改进循环
1. 解决每个识别的问题
2. 重新生成受影响的章节
3. 重新验证
4. 重复直到满足质量阈值

## 最终定稿
1. 应用最终格式
2. 生成摘要
3. 保存最终版本

关键技术：

显式质量标准
迭代改进
验证脚本
知道何时停止迭代

6.4 模式 4：上下文感知工具选择

适用场景： 相同结果，根据上下文使用不同工具

示例：智能文件存储

markdown 复制代码

## 决策树
1. 检查文件类型和大小
2. 确定最佳存储位置：
   - 大文件（>10MB）：使用云存储 MCP
   - 协作文档：使用 Notion/Docs MCP
   - 代码文件：使用 GitHub MCP
   - 临时文件：使用本地存储

## 执行存储
基于决策：
- 调用适当的 MCP 工具
- 应用特定于服务的元数据
- 生成访问链接

## 向用户提供上下文
解释为什么选择该存储

关键技术：

清晰的决策标准
回退选项
关于选择的透明度

6.5 模式 5：领域特定智能

适用场景： Skill 添加超出工具访问的专业知识

示例：财务合规

markdown 复制代码

## 处理前（合规检查）
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 检查制裁名单
   - 验证司法管辖区允许
   - 评估风险等级
3. 记录合规决策

## 处理
如果合规通过：
- 调用支付处理 MCP 工具
- 应用适当的欺诈检查
- 处理交易
否则：
- 标记以供审查
- 创建合规案例

## 审计跟踪
- 记录所有合规检查
- 记录处理决策
- 生成审计报告

关键技术：

嵌入逻辑的领域专业知识
行动前合规
全面的文档
清晰的治理

七、分发与共享

7.1 当前分发模式（2026年1月）

个人用户：

下载 Skill 文件夹
压缩文件夹（如需要）
上传到 Claude.ai：Settings > Capabilities > Skills
或放置在 Claude Code skills 目录

组织级 Skills：

管理员可部署工作区范围（2025年12月18日发布）
自动更新
集中管理

7.2 推荐分发方法

步骤 1：托管在 GitHub

markdown 复制代码

- 公共仓库用于开源 Skills
- 清晰的 README（供人类访问者）
- 示例用法和截图

步骤 2：在 MCP 仓库中记录

markdown 复制代码

- 从 MCP 文档链接到 Skills
- 解释一起使用的价值
- 提供快速入门指南

步骤 3：创建安装指南

markdown 复制代码

# 安装 [你的服务] Skill

## 1. 下载 Skill
- 克隆仓库：`git clone https://github.com/yourcompany/skills`
- 或从 Releases 下载 ZIP

## 2. 在 Claude 中安装
- 打开 Claude.ai > Settings > Skills
- 点击 "Upload skill"
- 选择 Skill 文件夹（压缩）

## 3. 启用 Skill
- 切换开启 [你的服务] skill
- 确保你的 MCP 服务器已连接

## 4. 测试
- 问 Claude："在 [你的服务] 中设置一个新项目"

7.3 定位你的 Skill

关注结果，而非功能：

markdown 复制代码

# ✅ 好的示例
"ProjectHub Skill 使团队能够在几秒钟内设置完整的项目工作区------包括页面、数据库和模板------而不是花费 30 分钟进行手动设置。"

# ❌ 不好的示例
"ProjectHub Skill 是一个包含 YAML frontmatter 和 Markdown 指令的文件夹，它调用我们的 MCP 服务器工具。"

突出 MCP + Skills 故事：

markdown 复制代码

"我们的 MCP 服务器让 Claude 访问你的 Linear 项目。
我们的 Skills 教会 Claude 你的团队冲刺规划工作流。
一起，它们实现 AI 驱动的项目管理。"

八、故障排除指南

8.1 Skill 无法上传

错误： "Could not find SKILL.md in uploaded folder"

原因： 文件未准确命名为 SKILL.md

解决方案：

bash 复制代码

# 重命名为 SKILL.md（区分大小写）
# 验证：ls -la 应显示 SKILL.md

错误： "Invalid frontmatter"

常见错误：

yaml 复制代码

# ❌ 错误 - 缺少分隔符
name: my-skill
description: Does things

# ❌ 错误 - 引号未闭合
name: my-skill
description: "Does things

# ✅ 正确
---
name: my-skill
description: Does things
---

错误： "Invalid skill name"

原因： 名称包含空格或大写

yaml 复制代码

# ❌ 错误
name: My Cool Skill

# ✅ 正确
name: my-cool-skill

8.2 Skill 不触发

症状： Skill 从不自动加载

解决方案： 修改 description 字段

快速检查清单：

是否太通用？（"帮助处理项目" 不会工作）
是否包含用户实际会说的触发短语？
如果相关，是否提到了相关文件类型？

调试方法：

问 Claude："你何时会使用 [skill name] skill？" Claude 会引用描述。根据缺失内容调整。

8.3 Skill 触发过于频繁

症状： Skill 为不相关查询加载

解决方案：

添加负面触发器

yaml 复制代码

description: CSV 文件的高级数据分析。用于统计建模、回归、聚类。不要用于简单的数据探索（改用 data-viz skill）。

更加具体

yaml 复制代码

# 太宽泛
description: 处理文档

# 更具体
description: 处理 PDF 法律文档以进行合同审查

明确范围

yaml 复制代码

description: PayFlow 电子商务支付处理。专门用于在线支付工作流，不用于一般财务查询。

8.4 指令未遵循

常见原因：

指令过于冗长
- 保持指令简洁
- 使用项目符号和编号列表
- 将详细参考移至单独文件
指令被埋没
- 将关键指令放在顶部
- 使用 ## Important 或 ## Critical 标题
- 如需要重复关键点
语言模糊

markdown 复制代码

# ❌ 不好
确保正确验证事物

# ✅ 好
关键：在调用 create_project 之前，验证：
- 项目名称非空
- 至少分配了一个团队成员
- 开始日期不在过去

高级技巧： 对于关键验证，考虑捆绑一个脚本，以编程方式执行检查，而不是依赖语言指令。代码是确定性的；语言解释不是。

8.5 MCP 连接问题

症状： Skill 加载但 MCP 调用失败

检查清单：

验证 MCP 服务器已连接
- Claude.ai：Settings > Extensions > [你的服务]
- 应显示 "Connected" 状态
检查认证
- API 密钥有效且未过期
- 授予了适当的权限/范围
- OAuth 令牌已刷新
独立测试 MCP
- 要求 Claude 直接调用 MCP（不使用 skill）
- "使用 [Service] MCP 获取我的项目"
- 如果失败，问题在 MCP 而非 skill
验证工具名称
- Skill 引用正确的 MCP 工具名称
- 检查 MCP 服务器文档
- 工具名称区分大小写

8.6 大上下文问题

症状： Skill 似乎慢或响应降级

原因：

Skill 内容太大
同时启用的 Skills 太多
加载了所有内容而非渐进式披露

解决方案：

优化 SKILL.md 大小
- 将详细文档移至 references/
- 链接到参考而非内联
- 保持 SKILL.md 在 5,000 字以内
减少启用的 Skills
- 评估是否同时启用了 20-50 个以上的 Skills
- 建议选择性启用
- 考虑相关能力的 Skill "包"

九、资源与参考

9.1 官方文档

Anthropic 资源：

博客文章：

Introducing Agent Skills
Engineering Blog: Equipping Agents for the Real World
Skills Explained
How to Create Skills for Claude
Building Skills for Claude Code
Improving Frontend Design through Skills

9.2 工具和实用程序

skill-creator Skill：

内置于 Claude.ai，可用于 Claude Code
可从描述生成 Skills
审查并提供推荐
使用："Help me build a skill using skill-creator"

验证：

skill-creator 可以评估你的 Skills
询问："Review this skill and suggest improvements"

9.3 示例 Skills

公共 Skills 仓库：

GitHub: anthropics/skills
包含 Anthropic 创建的可定制 Skills

生产就绪的示例：

Document Skills - PDF、DOCX、PPTX、XLSX 创建
Example Skills - 各种工作流模式
Partner Skills Directory - 来自 Asana、Atlassian、Canva、Figma、Sentry、Zapier 等的 Skills

9.4 获取支持

技术问题：

一般问题：Claude Developers Discord 社区论坛
Bug 报告：GitHub Issues - anthropics/skills/issues
包含：Skill 名称、错误消息、重现步骤

十、快速检查清单

10.1 上传前检查

开发阶段：

确定了 2-3 个具体用例
识别了工具（内置或 MCP）
审查了本指南和示例 Skills
规划了文件夹结构

开发期间：

上传前：

在明显任务上测试了触发
在释义请求上测试了触发
验证不在不相关主题上触发
功能测试通过
工具集成工作（如适用）
压缩为 .zip 文件

10.2 上传后检查

十一、总结与展望

核心要点回顾

Skills 是 AI 定制化的强大工具
- 一次配置，多次复用
- 标准化工作流程
- 团队知识沉淀
设计原则至关重要
- 渐进式披露：最小化 Token 使用
- 可组合性：与其他 Skills 协同
- 可移植性：跨平台使用
质量源于迭代
- 从具体用例开始
- 持续测试和改进
- 收集用户反馈
Description 是关键
- 清晰说明做什么和何时使用
- 包含触发短语
- 避免过度泛化

进阶学习建议

实践出真知
- 使用 skill-creator 构建第一个 Skill
- 从简单场景开始，逐步增加复杂度
- 研究官方示例 Skills
深入理解 MCP
- 学习 Model Context Protocol
- 了解 MCP 服务器的工作原理
- 探索 MCP + Skills 的协同效应
关注社区动态
- 加入 Claude Developers Discord
- 关注 GitHub 仓库更新
- 参与社区讨论和分享
持续优化
- 监控 Skill 使用数据
- 根据反馈迭代改进
- 探索新的应用场景

未来展望

Agent Skills 作为开放标准，正在快速发展：

更多的平台和工具支持
更丰富的示例和模式
更完善的测试和评估工具
更活跃的社区生态

掌握 Skills 构建能力，将让你在 AI 时代占据先机。

最后

如果这篇文章对你有帮助，欢迎：

点赞 👍 收藏 ⭐
关注我，获取更多 AI 技术干货
评论区交流，分享你的 Skills 构建经验

有问题欢迎在评论区讨论，我会及时回复！

Happy Coding! 🚀