Skills 出现后已经改变了 Agent 开发范式，以往我们主要通过 Tools / MCP 来实现外部接口调用从而增强模型能力，但现在又有了更轻量更专业拓展 Agent 能力的方式，它就是 Skill。

下面的内容是 Claude 官方文档整理过来，值得所有 Agent 开发同学学一手！

什么是 Skill？🎯

核心定义

Skill = 一个文件夹，包含教 Claude 如何处理特定任务的指令集，主要用来存储领域知识。

your-skill-name/
├── SKILL.md              # 必需 - 主文件
├── scripts/              # 可选 - 可执行代码
├── references/           # 可选 - 参考文档
└── assets/               # 可选 - 模板、资源

核心价值

• • ✅ 一次教学，永久受益 - 不用每次对话都重复说明
• • ✅ 跨平台通用 - Claude.ai、Claude Code、API 完全兼容
• • ✅ 可组合 - 多个 Skills 可同时加载协作

三大核心设计原则 🏗️

1️⃣ 渐进式披露（Progressive Disclosure）

# 第一层：YAML frontmatter（总是加载）
---
name: project-planner
description: Sprint planning automation. Use when user says 
"plan sprint" or "create tasks"
---

# 第二层：SKILL.md 正文（相关时加载）
## Instructions
详细的步骤和指导...

# 第三层：链接文件（按需加载）
references/api-guide.md

目的：最小化 token 使用，同时保持专业能力

2️⃣ 可组合性（Composability）

用户可以同时启用多个 Skills：
✅ frontend-design + docx-creator
✅ sentry-code-review + github-workflow
✅ skill-creator + your-custom-skill

设计要求：你的 Skill 不应假设自己是唯一能力

3️⃣ 可移植性（Portability）

同一个 Skill 在所有环境中表现一致：

• • Claude.ai（网页版）
• • Claude Code（桌面应用）
• • Claude API（开发者集成）

三种常见使用场景 📋

Category 1: 文档与资产创建

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

示例：frontend-design skill

---
name: frontend-design
description: Create distinctive, production-grade frontend 
interfaces. Use when building web components, pages, or apps.
---

关键技术：

• • 嵌入式风格指南
• • 模板结构
• • 质量检查清单
• • 无需外部工具

Category 2: 工作流自动化

用途：多步骤流程的一致性方法论

示例：skill-creator skill

---
name: skill-creator
description: Interactive guide for creating new skills. 
Use when user wants to build a skill.
---

关键技术：

• • 分步工作流 + 验证门
• • 通用结构模板
• • 内置审查和改进建议
• • 迭代优化循环

Category 3: MCP 增强

用途：为 MCP 服务器提供工作流指导

示例：sentry-code-review skill

---
name: sentry-code-review
description: Automatically analyze and fix bugs in GitHub PRs 
using Sentry error data. Use when reviewing code with errors.
---

关键技术：

• • 协调多个 MCP 调用序列
• • 嵌入领域专业知识
• • 提供用户原本需要指定的上下文
• • 常见 MCP 问题的错误处理

四、技术要求（Critical Rules）⚠️

文件命名规则

# ✅ 正确
SKILL.md                    # 必须大写，必须这个名字
your-skill-name/            # kebab-case
frontend-design/            # kebab-case

# ❌ 错误
skill.md                    # 小写 - 错误
SKILL.MD                    # 扩展名大写 - 错误
Your_Skill_Name/            # 下划线 - 错误
YourSkillName/              # 驼峰 - 错误
Your Skill Name/            # 空格 - 错误

禁止 README.md

# ❌ 不要在 skill 文件夹内放 README.md
your-skill/
├── SKILL.md       # ✅ 正确
└── README.md      # ❌ 错误

# ✅ 但 GitHub 仓库根目录可以有
your-skill-repo/
├── README.md              # ✅ 给人类看的
└── your-skill/
    └── SKILL.md           # ✅ 给 Claude 看的

五、YAML Frontmatter - 最重要的部分 🎯

最小必需格式

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

字段要求

name（必需）

# ✅ 正确
name: notion-project-setup
name: frontend-design
name: sentry-code-review

# ❌ 错误
name: Notion Project Setup    # 有空格
name: notion_project_setup    # 下划线
name: NotionProjectSetup      # 驼峰

description（必需）

必须同时包含两部分：

# ✅ 正确 - 包含"做什么"和"何时用"
description: Creates sprint plans from Linear data. Use when 
user says "plan sprint" or "create tasks for this week".

# ❌ 错误 - 只说了做什么
description: Creates sprint plans from Linear data.

# ❌ 错误 - 只说了何时用
description: Use when planning sprints.

要求：

• • < 1024 字符
• • 清晰的触发条件
• • 不要用 XML 标签

六、成功标准 📊

定量指标

✅ 90% 相关查询能触发 Skill
   测试方法：运行 10-20 个测试查询，统计自动触发率

✅ 在 X 次工具调用内完成工作流
   测试方法：对比有/无 Skill 的工具调用次数

✅ 每个工作流 0 次 API 调用失败
   测试方法：监控 MCP 服务器日志，追踪重试率

定性指标

✅ 用户无需提示 Claude 下一步
   评估方法：测试时记录需要重定向的次数

✅ 工作流无需用户纠正即可完成
   评估方法：同一请求运行 3-5 次，比较输出一致性

✅ 跨会话结果一致
   评估方法：新用户首次尝试能否成功

七、MCP + Skills 的关系 🔌

厨房类比

MCP = 专业厨房
├── 提供工具、食材、设备
├── 连接 Claude 到你的服务
└── 实时数据访问

Skills = 食谱
├── 一步步的制作指南
├── 最佳实践和工作流
└── 如何有效使用服务

为什么 MCP 需要 Skills？

# ❌ 没有 Skills
用户连接 MCP → 不知道下一步做什么
每次对话从头开始 → 结果不一致
支持工单："怎么用你的集成做 X？"

# ✅ 有 Skills
预构建工作流自动激活 → 一致可靠
最佳实践嵌入每次交互 → 学习曲线低
用户体验提升 → 减少支持成本

八、快速开始 🚀

时间预期

第一个可用 Skill：15-30 分钟
使用工具：skill-creator skill

开发流程

1. 定义用例（2-3 个具体场景）
   ├── 用户想完成什么？
   ├── 需要哪些多步骤工作流？
   └── 需要哪些工具？

2. 创建 SKILL.md
   ├── 写 YAML frontmatter
   ├── 写主要指令
   └── 添加示例

3. 测试迭代
   ├── 运行测试查询
   ├── 检查触发率
   └── 优化描述和指令

4. 分发共享
   ├── GitHub 仓库
   ├── 团队内部
   └── 社区分享

九、关键要点总结 💡

核心概念

1. Skill = 文件夹 + SKILL.md + 可选资源
2. 渐进式披露 = 三层信息结构
3. 一次创建 = 全平台通用
4. 可组合 = 多 Skills 协作

文件命名

✅ SKILL.md（大写）
✅ kebab-case（文件夹名）
❌ README.md（禁止）
❌ 空格/下划线/驼峰（禁止）

YAML 必需字段

---
name: kebab-case-name
description: What + When (< 1024 chars)
---

三大使用场景

1. 文档创建（无需外部工具）
2. 工作流自动化（多步骤流程）
3. MCP 增强（工具 + 知识）

十、下一步行动 🎬

1. 阅读完整指南的其他章节：
   ├── Testing and Iteration
   ├── Distribution and Sharing
   └── Patterns and Troubleshooting

2. 使用 skill-creator 创建第一个 Skill

3. 测试和迭代

4. 分享给团队或社区

这份指南的目标：让你在一次坐下来的时间内（15-30 分钟）就能构建一个可用的 Skill。