Claude 技能构建指南——AI 工作流的标准化范式

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


这就是入门所需的一切。

字段要求：

`name`（必需）：

- 仅使用 kebab-case  
- 不要有空格或大写字母  
- 应与文件夹名一致  

`description`（必需）：

- 必须同时包含：

  – 技能做什么  
  – 何时使用（触发条件）

- 不超过 1024 字符  
- 不允许 XML 标签（`<` 或 `>`）  
- 包含用户可能说出的具体任务  
- 如相关，提及文件类型  

`license`（可选）：

- 若将技能开源，建议填写  
- 常用：`MIT`、`Apache-2.0`  

`compatibility`（可选）：

- 1–500 字符  
- 用于说明环境需求：如预期使用的产品、所需系统包、网络访问需求等  

`metadata`（可选）：

- 任意自定义键值对  
- 推荐：`author`、`version`、`mcp-server`  
- 示例：

```yaml
metadata:
  author: ProjectHub
  version: 1.0.0
  mcp-server: projecthub

安全限制

frontmatter 中禁止包含：

XML 尖括号（< >）
在 name 中包含「claude」或「anthropic」的技能（保留前缀）

原因：frontmatter 会出现在 Claude 的 system prompt 中，恶意内容可能注入指令。

Writing effective skills（编写高效技能）

description 字段

根据 Anthropic 工程博客：

「这一元数据……为 Claude 提供恰到好处的信息，让它知道何时该使用哪个技能，而无需将整个技能内容加载进上下文。」

这就是渐进式披露的第一层。

结构：

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

好的 description 示例：

# 好 - 具体且可执行
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

# 好 - 包含触发短语
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

# 好 - 价值主张清晰
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".

不好的 description 示例：

# 过于模糊
description: Helps with projects.

# 缺少触发条件
description: Creates sophisticated multi-page documentation systems.

# 过于技术向，没有用户会说的触发语
description: Implements the Project entity model with hierarchical relationships.

编写主体指令

在 frontmatter 之后，用 Markdown 写实际指令。推荐结构：根据你的技能改写此模板，将方括号部分替换为具体内容。

---
name: your-skill
description: [...]
---

# Your Skill Name

## Instructions

### Step 1: [First Major Step]

Clear explanation of what happens.

Example:

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

Expected output: [describe what success looks like]

(Add more steps as needed)

Examples

Example 1: [common scenario]

User says: "Set up a new marketing campaign"

Actions:

Fetch existing campaigns via MCP
Create new campaign with provided parameters

Result: Campaign created with confirmation link

(Add more examples as needed)

Troubleshooting

Error: [Common error message] Cause: [Why it happens] Solution: [How to fix]

(Add more error cases as needed)


### 指令编写最佳实践

**要具体可执行**

```markdown
✅ 好：

Run `python scripts/validate.py --input {filename}` to check data format. If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

❌ 不好：

Validate the data before proceeding.

加入错误处理

## Common Issues

### MCP Connection Failed

If you see "Connection refused":

1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect

清晰引用打包资源

在编写查询前，请先查阅 references/api-patterns.md，了解：

限流（rate limiting）指南
分页模式
错误码及其处理方式

使用渐进式披露

保持 SKILL.md 专注于核心指令。将详细文档移至 references/ 并在文中链接。（参见「Core Design Principles」了解三级系统如何运作。）

Testing and iteration（测试与迭代）

技能可以按需求采用不同严谨程度的测试方式：

在 Claude.ai 中手动测试——直接运行查询并观察行为。迭代快速，无需额外配置。
在 Claude Code 中脚本化测试——自动执行测试用例，以便在变更后进行可重复验证。
通过 skills API 进行程序化测试——构建评估套件，系统地针对定义好的测试集运行。

选择与技能质量要求和曝光程度相匹配的测试方式。面向小团队内部使用的技能与面向成千上万企业用户的技能，在测试要求上是不同的。

实践建议：先在单个任务上迭代，再向外扩展

我们发现，最有效的技能创建者通常会先围绕一个具有挑战性的任务反复迭代，直到 Claude 能很好地完成，然后将最终方案抽象为技能。这能充分利用 Claude 的上下文学习（in-context learning），相比一开始就做大而全的测试更快获得有效信号。待基础打牢后，再扩展到多个测试用例以覆盖更多场景。

使用 skill-creator 技能

skill-creator 技能可在 Claude.ai 的插件目录中获取，也可为 Claude Code 下载，能够帮助你构建和迭代技能。如果你已有 MCP server，并清楚前 2–3 个关键工作流，通常可在 15–30 分钟内构建并测试一个可用技能。

创建技能：

从自然语言描述生成技能
自动生成格式正确的 SKILL.md 和 frontmatter
建议触发短语与结构

评审技能：

标记常见问题（如描述模糊、缺少触发条件、结构问题）
识别潜在的过度/不足触发风险
根据技能声明的目的建议测试用例

迭代优化：

在使用技能的过程中遇到边界情况或失败时，将这些案例带回 skill-creator
示例：「Use the issues & solution identified in this chat to improve how the skill handles [specific edge case]」

使用方式：

「Use the skill-creator skill to help me build a skill for [your use case]」

注意：skill-creator 可以帮助你设计和完善技能，但不会执行自动化测试套件，也不会生成量化评估结果。

基于反馈迭代

技能是「活文档」。请计划基于以下信号迭代：

触发不足（Undertriggering）信号：

技能在该触发时没有被加载
用户需要手动启用技能
用户在何时使用技能的问题上需要支持

解决方案：在 description 中增加更多细节和语义，特别是技术术语相关关键词。

触发过度（Overtriggering）信号：

技能在无关查询上被加载
用户主动禁用技能
对技能用途感到困惑

解决方案：添加「负向触发」条件、更明确地限定范围。

执行问题：

结果不一致
API 调用失败
需要用户纠正

解决方案：改善指令、增加错误处理。

Distribution and sharing（分发与分享）

技能让你的 MCP 集成更加完整。当用户比较不同的 connector 时，带技能的一方能更快创造价值，相比只有 MCP 的方案更有优势。

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

个人用户获取技能：

下载技能文件夹
视情况将文件夹打包为 zip
在 Claude.ai 中依次打开 Settings > Capabilities > Skills 上传
或将其放入 Claude Code 的 skills 目录

组织级技能：

管理员可以在整个 workspace 级别部署技能（2025 年 12 月 18 日上线）
自动更新
集中管理

开放标准

我们已将 Agent Skills 作为一个开放标准发布。与 MCP 一样，我们认为技能应该能在工具与平台之间可移植——同一个技能应能在 Claude 或其他 AI 平台中使用。

话虽如此，一些技能是为了充分发挥特定平台能力而设计的；作者可以在技能的 compatibility 字段中说明这一点。我们正与生态系统中的诸多成员合作这一标准，并对早期采纳情况感到振奋。

通过 API 使用技能

对于程序化用例——例如构建利用技能的应用、agent 或自动化工作流——API 提供了对技能管理与执行的直接控制。

关键能力：

/v1/skills 端点用于列出和管理技能
通过 container.skills 参数将技能添加到 Messages API 请求中
通过 Claude Console 进行版本控制与管理
可与 Claude Agent SDK 一起使用，用于构建自定义 agent

何时使用 API，何时使用 Claude.ai：

用例	最佳界面
终端用户直接与技能交互	Claude.ai / Claude Code
开发过程中手动测试与迭代	Claude.ai / Claude Code
个人、临时性工作流	Claude.ai / Claude Code
程序化使用技能的应用	API
大规模生产部署	API
自动化流水线与 agent 系统	API

注意：在 API 中使用技能需要启用 Code Execution Tool 测试版，它为技能运行提供安全环境。

实现细节请参见：

Skills API Quickstart
Create Custom skills
Skills in the Agent SDK

给技能定位（Positioning your skill）

你如何描述技能，将决定用户是否理解其价值并愿意尝试。在 README、文档或营销内容中，遵循以下原则。

突出结果，而非特性：

✅ 好：

"The ProjectHub skill enables teams to set up complete project workspaces in seconds — including pages, databases, and templates — instead of spending 30 minutes on manual setup."

❌ 不好：

"The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools."

强调 MCP + skills 的故事：

「我们的 MCP server 让 Claude 能访问你的 Linear 项目。我们的技能则教 Claude 你团队的冲刺规划工作流。二者结合，实现 AI 驱动的项目管理。」

Patterns and troubleshooting（模式与故障排查）

以下模式来自早期采用者和内部团队创建的技能。它们代表了我们观察到的常见有效方法，而非强制模板。

如何选择方法：问题优先 vs 工具优先

可以类比 Home Depot（家装超市）。你可能带着一个问题走进店里——「我需要修一个厨房橱柜」——店员会帮你找到合适工具。也可能是你先挑选了一把新电钻，然后问它可以如何用在你的具体工作上。

技能也类似：

问题优先（Problem-first）：
「I need to set up a project workspace」→ 你的技能按正确顺序编排合适的 MCP 调用。用户描述想要的结果，技能负责工具细节。
工具优先（Tool-first）：
「I have Notion MCP connected」→ 你的技能教 Claude 最优的工作流和最佳实践。用户已经有工具访问能力，技能提供专业方法论。

大多数技能会在这两种方向中偏向其一。清楚你属于哪种有助于选择合适的模式。

模式 1：顺序工作流编排（Sequential workflow orchestration）

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

示例结构：

## Workflow: Onboard New Customer

### Step 1: Create Account

Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment

Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription

Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email

Call MCP tool: `send_email`
Template: welcome_email_template

关键技巧：

明确步骤顺序
步骤之间的依赖关系
每一步进行校验
在失败时提供回滚指引

模式 2：多 MCP 协调（Multi-MCP coordination）

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

示例：从设计到开发移交

### Phase 1: Design Export (Figma MCP)

1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest

### Phase 2: Asset Storage (Drive MCP)

1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links

### Phase 3: Task Creation (Linear MCP)

1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team

### Phase 4: Notification (Slack MCP)

1. Post handoff summary to #engineering
2. Include asset links and task references

关键技巧：

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

模式 3：迭代式优化（Iterative refinement）

适用场景：输出质量通过反复迭代可以显著提高。

示例：报告生成

## Iterative Report Creation

### Initial Draft

1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file

### Quality Check

1. Run validation script: `scripts/check_report.py`
2. Identify issues:
   - Missing sections
   - Inconsistent formatting
   - Data validation errors

### Refinement Loop

1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization

1. Apply final formatting
2. Generate summary
3. Save final version

关键技巧：

明确质量标准
迭代改进流程
使用验证脚本
明确「何时停止迭代」的条件

模式 4：上下文感知的工具选择（Context-aware tool selection）

适用场景：目标相同，但具体工具依赖场景。

示例：文件存储

## Smart File Storage

### Decision Tree

1. Check file type and size
2. Determine best storage location:
   - Large files (>10MB): Use cloud storage MCP
   - Collaborative docs: Use Notion/Docs MCP
   - Code files: Use GitHub MCP
   - Temporary files: Use local storage

### Execute Storage

Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link

### Provide Context to User

Explain why that storage was chosen

关键技巧：

清晰的决策标准
设定兜底方案（fallback）
向用户解释选择原因

模式 5：特定领域智能（Domain-specific intelligence）

适用场景：技能需要提供超越工具访问本身的专业知识。

示例：金融合规（Financial compliance）

## Payment Processing with Compliance

### Before Processing (Compliance Check)

1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

### Processing

IF compliance passed:
- Call payment processing MCP tool
- Apply appropriate fraud checks
- Process transaction

ELSE:
- Flag for review
- Create compliance case

### Audit Trail

- Log all compliance checks
- Record processing decisions
- Generate audit report

关键技巧：

将领域专业知识编码进逻辑
在执行前进行合规校验
完整记录和审计追踪
明确治理与责任边界

故障排查（Troubleshooting）

技能无法上传

错误："Could not find SKILL.md in uploaded folder"
原因：文件名不是严格的 SKILL.md。

解决方案：

将文件重命名为 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"
原因：名字中包含空格或大写字母。

# 错误
name: My Cool Skill

# 正确
name: my-cool-skill

技能不触发

现象：技能从不自动加载。

修复方式：
修改 description 字段。参见「The Description Field」中的好/坏示例。

快速检查：

是否过于泛泛？（如 "Helps with projects" 不会起作用）
是否包含用户可能实际说出的触发短语？
如果与文件类型相关，是否提到相应类型？

调试方法：
问 Claude：

「When would you use the [skill name] skill?」

Claude 会引用 description。根据缺失内容调整之。

技能触发过于频繁

现象：技能在不相关查询中被加载。

解决方案：

添加负向触发条件

description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).

更具体

# 太宽泛
description: Processes documents

# 更具体
description: Processes PDF legal documents for contract review

明确边界范围

description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries.

MCP 连接问题

现象：技能被加载，但 MCP 调用失败。

检查列表：

确认 MCP server 已连接

– Claude.ai：Settings > Extensions > [Your Service]
– 状态应为「Connected」

检查认证信息

– API key 有效且未过期
– 权限/Scope 设置正确
– OAuth token 未过期或已刷新

单独测试 MCP

– 在不使用技能的情况下，请 Claude 直接调用 MCP
– 例如：「Use [Service] MCP to fetch my projects」
– 若失败，则问题在 MCP 而非技能

确认工具名

– 技能中引用的 MCP 工具名称是否正确
– 对照 MCP server 文档
– 工具名区分大小写

指令没有被遵守

现象：技能被加载，但 Claude 不按指令行事。

常见原因：

指令过于冗长

– 保持指令简洁
– 使用项目符号和有序列表
– 将详细参考内容移到单独文件

关键指令被埋没

– 将关键指令放在顶部
– 使用 ## Important 或 ## Critical 标题
– 必要时重复关键点

语言含糊不清

# 不好
Make sure to validate things properly

# 好
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

高级技巧：
对关键校验逻辑，考虑打包脚本进行程序化检查，而不是完全依赖文字说明。代码是确定性的，而语言解释可能走样。可参考 Office 相关技能中的实践。

模型「懒惰」

添加明确的鼓励说明：

## Performance Notes

- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps

注意：将这些内容写在用户 prompt 中往往比写在 SKILL.md 更有效。

大上下文（Large context）问题

现象：技能响应缓慢或质量下降。

原因：

技能内容过大
同时启用了过多技能
一次性加载了所有内容，而不是渐进式披露

解决方案：

优化 SKILL.md 体积

– 将详细文档移至 references/
– 用链接代替内联长文
– 尽量将 SKILL.md 控制在 5,000 词以内

减少启用技能数量

– 若同时启用 20–50 个以上技能，评估是否必要
– 推荐按需启用
– 考虑为相关能力构建技能「包」（packs）

Resources and references（资源与参考资料）

如果你在构建第一个技能，建议先阅读「Best Practices Guide」，根据需要再查阅 API 文档。

官方文档

Anthropic 资源：

Best Practices Guide
Skills Documentation
API Reference
MCP Documentation

博客文章：

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

示例技能

公共技能仓库：

GitHub: anthropics/skills
包含可供你自定义的 Anthropic 官方技能

工具与实用程序

skill-creator 技能：

已内置在 Claude.ai 中，同时可用于 Claude Code
可从描述生成技能
进行评审并给出建议
用法示例：「Help me build a skill using skill-creator」

验证：

skill-creator 可以评估你的技能
提问示例：「Review this skill and suggest improvements」

获取支持

技术问题：

常规问题：Claude Developers Discord 中的社区论坛

Bug 汇报：

GitHub Issues: anthropics/skills/issues
请附：技能名称、错误信息、复现步骤

Reference A: 快速检查清单（Quick checklist）

在上传前后使用此清单验证你的技能。如果你想更快入门，可以先用 skill-creator 生成第一版草稿，再按本清单逐项检查是否有遗漏。

开始之前

已识别 2–3 个具体用例
已识别所需工具（内置或 MCP）
已阅读本指南和示例技能
已规划文件夹结构

开发过程中

文件夹采用 kebab-case 命名
存在 SKILL.md 文件，拼写完全正确
YAML frontmatter 使用 --- 分隔符
name 字段：kebab-case，无空格，无大写
description 同时写清「做什么」和「何时使用」
任意位置不包含 XML 标签（< >）
指令清晰且可执行
包含错误处理部分
提供示例
引用的参考资料链接清晰

上传之前

在显然应触发的任务上测试触发情况
在改写/意译任务上测试触发情况
验证在无关话题上不会触发
功能测试通过
工具集成可用（如适用）
已压缩为 .zip 文件

上传之后

在真实对话中测试
观察是否存在触发不足/过度
收集用户反馈
根据反馈迭代 description 和指令
更新 metadata 中的版本号

Reference B: YAML frontmatter

必需字段

---
name: skill-name-in-kebab-case
description: What it does and when to use it. Include specific trigger phrases.
---

所有可选字段示例

```yaml name: skill-name description: [required description] license: MIT # 可选：开源许可证 allowed-tools: "Bash(python:) Bash(npm:) WebFetch" # 可选：限制可用工具

Claude 技能构建指南——AI 工作流的标准化范式

核心观点

跟我们的关联

讨论引子

安全限制

Writing effective skills（编写高效技能）

description 字段

结构：

编写主体指令

Examples

Troubleshooting

Testing and iteration（测试与迭代）

推荐测试方法

使用 skill-creator 技能

基于反馈迭代

Distribution and sharing（分发与分享）

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

开放标准

通过 API 使用技能

推荐做法（现阶段）

给技能定位（Positioning your skill）

Patterns and troubleshooting（模式与故障排查）

如何选择方法：问题优先 vs 工具优先

模式 1：顺序工作流编排（Sequential workflow orchestration）

模式 2：多 MCP 协调（Multi-MCP coordination）

模式 3：迭代式优化（Iterative refinement）

模式 4：上下文感知的工具选择（Context-aware tool selection）

模式 5：特定领域智能（Domain-specific intelligence）

故障排查（Troubleshooting）

Resources and references（资源与参考资料）

官方文档

示例技能

工具与实用程序

获取支持

Reference A: 快速检查清单（Quick checklist）

Reference B: YAML frontmatter

📋 讨论归档