Claude官方AI Agent技能编写指南

前言

在使用 Claude、Cursor 或 GitHub Copilot 等 AI 编程助手时，你是否常遇到这些困扰：处理相同任务，AI 每次给出的答案却大相径庭；想让 AI 记住并复用某个工作流，但它总是时好时坏；面对多步骤复杂任务，AI 经常在中间环节出错或遗漏关键步骤。

这些问题的根源，在于 AI 执行任务缺乏稳定性和一致性。为此，Claude 官方提出了“Skill”（技能）这一标准化解决方案。它远不止是一个简单的 Markdown 文件，而是一套旨在提升 AI 助手可靠性与可预测性的完整框架。

近期，Claude 团队发布了长达 30 多页的详细指南《The Complete Guide to Building Skills》。本文将为你提炼其核心精髓，并结合实战经验，手把手教你如何构建高效、可靠的 AI 技能。

一、Skill 的核心：三层渐进式架构

理解 Skill 的关键在于掌握其“渐进式披露”机制。该机制并非将所有信息一次性灌输给 AI，而是根据任务的相关性分层加载，从而在提供充分指导的同时，避免不必要的上下文负担，优化 AI 的响应效率与准确性。

这种设计极为精妙：轻量级的 frontmatter 如同一个常驻的“技能目录”，帮助 AI 快速判断技能适用性。仅当任务高度匹配时，才会加载详细的正文和参考资料，确保了 AI 响应的精准与高效。

二、标准的文件结构规范

一个规范的 Skill 遵循明确的目录结构，这不仅是约定俗成，更是确保 AI 能够正确识别和解析的基础。

your-skill-name/
├── SKILL.md          # 必需 - 技能主文件
├── scripts/          # 可选 - 可执行脚本
│   └── validate.py
├── references/       # 可选 - 参考文档目录
│   └── api-guide.md
└── assets/          # 可选 - 模板等静态资源
    └── template.md

请务必遵守以下硬性规则，细节决定成败：

特别注意：SKILL.md 文件名必须精确匹配，大小写敏感。在目录中放置 README.md 反而可能导致 AI 无法正确识别技能。

三、YAML Frontmatter：决定 Skill 的触发精准度

Frontmatter 是整个 Skill 的“触发器”，其质量直接决定了技能是“精准响应”还是“石沉大海”。描述模糊，AI 可能永远无法调用；描述过于宽泛，则可能导致在不相关场景下误触发。

基础格式

一个最基本的 frontmatter 结构如下：

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

Description 撰写的黄金公式

要确保 AI 准确触发，description 的撰写应遵循一个黄金公式：[核心功能] + [适用场景] + [用户触发关键词]。

优质与劣质描述对比

通过以下示例，可以清晰感受两者的差异：

劣质写法（应避免）：

# ❌ 过于模糊，AI 无法判断使用时机
description: Helps with projects.

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

# ❌ 过于技术化，未使用用户语言
description: Implements the Project entity model with hierarchical relationships.

优质写法（建议参考）：

# ✅ 功能具体 + 触发词明确
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".

可以看出，优质的描述为 AI 绘制了清晰的“任务地图”，不仅界定了能力范围，更用用户实际会使用的口语化关键词指明了调用入口。

调试技巧

若不确定技能为何未触发，可直接询问 AI：“When would you use this skill?”。AI 会基于你写的 description 进行回答。通过其回答，你可以反向诊断并优化描述，使其更符合 AI 的理解逻辑。

四、三类常见的 Skill 应用模式

掌握基础结构后，我们来看看 Skill 在实际应用中的几种典型角色。根据任务性质，主要可分为以下三类。

模式一：文档/资产创建型

适用场景： 需要生成格式统一、质量稳定的输出物，如技术文档、设计稿、代码文件、项目报告等。

关键技术要点：

• 嵌入式风格指南： 在 Skill 中直接定义品牌字体、配色、排版等视觉规范。
• 结构化模板： 提供输出物的标准框架和章节结构。
• 交付前质量检查清单： 确保每次输出都符合预设标准。

示例： 一个前端设计规范 Skill (frontend-design) 的质量检查部分：

## 质量检查清单
最终输出前请确认：
- [ ] 字体层级关系保持一致
- [ ] 配色方案遵循品牌指南
- [ ] 已定义响应式断点
- [ ] 色彩对比度满足无障碍访问标准

模式二：工作流程自动化型

适用场景： 涉及多个步骤的标准化业务流程，需确保每一步都按既定方法论执行，如客户 onboarding、发布流程、数据清洗流水线。

关键技术要点：

• 分步工作流与验证关卡： 明确每一步操作、输入输出及成功标准。
• 通用模板： 为流程中的重复性产出（如工单、通知邮件）提供模板。
• 迭代优化循环： 定义如何根据中间结果动态调整后续步骤。

示例： 新客户入驻（onboarding）工作流编排：

## 工作流：新客户入驻
### 步骤 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

模式三：多工具（MCP）协调型

适用场景： 最复杂的场景，需要串联多个不同服务或工具（MCP）来完成一个端到端流程。

示例： 从设计到开发交接的跨平台自动化流程：

### 阶段 1：设计导出 (Figma MCP)
1. 从 Figma 导出设计资产（切图、样式）
2. 生成设计标注文档
3. 创建设计资产清单

### 阶段 2：资产存储 (Google Drive MCP)
1. 在 Drive 中创建项目专属文件夹
2. 上传所有设计资产
3. 生成并设置可共享的访问链接

### 阶段 3：任务创建 (Linear MCP)
1. 在 Linear 中创建对应的开发任务
2. 将资产链接附加到任务描述中
3. 将任务分配给相应的工程团队

### 阶段 4：团队通知 (Slack MCP)
1. 在 #engineering 频道发布交接摘要
2. 消息中需包含资产链接和 Linear 任务引用

此类 Skill 扮演着跨系统“总指挥”的角色，确保数据和指令在不同平台间无缝、准确地流转。

五、指令编写的最佳实践

构建好 Skill 的“骨架”后，如何编写其中的“血肉”——具体指令，才能让 AI 精准执行？

1. 指令需具体、可操作

模糊的指令只会得到模糊的结果。务必把要求拆解为 AI 可以明确执行的动作。

# ❌ 差：指令模糊
Make sure to validate things properly

# ✅ 好：指令具体、可验证
CRITICAL: 在调用 create_project 前，必须验证：
- 项目名称非空
- 至少分配了一名团队成员
- 开始日期不在过去

2. 清晰引用外部资源

如果 Skill 包含参考资料目录，需明确告知 AI 在何时、何处查找信息。

在编写 API 查询代码前，请务必查阅 `references/api-patterns.md`，了解：
- 接口速率限制规范
- 分页查询的标准模式
- 常见错误代码及处理方式

3. 预设错误处理机制

不要假设流程永远顺利。提前为常见错误场景编写应对指南。

## 常见问题处理
### MCP 连接失败
若出现"Connection refused"错误：
1. 确认 MCP 服务器进程正在运行
2. 检查 API 密钥是否有效且未过期
3. 尝试重启连接或使用备用端点

4. 对抗 AI 的“懒惰”倾向

AI 有时会为追求响应速度而牺牲输出质量。明确的指令可以约束这种行为。

## 性能与质量要求
- 请投入足够时间，确保工作彻底完成
- 输出质量优先于响应速度
- 不得跳过任何验证步骤

六、常见问题排查指南

即使遵循指南，实践中仍可能遇到问题。以下是常见问题及其解决方案。

问题 1：Skill 完全不触发

可能原因： description 描述过于模糊，或缺少用户常用的触发关键词。

解决方案：

• 补充用户视角关键词： 思考用户会如何提问，将这些口语化短语加入描述。
• 提及相关文件类型： 如果是处理特定文件的任务，加上文件后缀如 .fig、.csv、.json。
• 利用对话调试： 直接询问 AI “When would you use this skill?”，根据其回答优化描述。

问题 2：Skill 触发过于频繁（误触发）

解决方案： 在 description 中添加“否定触发器”，明确告知 AI 在何种情况下不应使用此技能。

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

问题 3：AI 不遵循或误解指令

AI 忽略指令通常源于：

1. 指令过于冗长： 关键信息被淹没。保持简洁，善用列表和标题。
2. 关键步骤不突出： 使用 ## CRITICAL、## IMPORTANT 等标题强调核心操作。
3. 语言描述存在歧义： 能用代码或脚本明确表达的规则，优先使用代码而非自然语言。

高级技巧： 对于关键的数据验证逻辑，使用调用外部脚本的方式代替文字描述。

请先运行 `scripts/validate.py --input {filename}` 以检查数据格式是否符合规范

记住，代码执行是确定性的，而自然语言解释可能存在歧义。

问题 4：上下文过大导致响应缓慢

解决方案：

• 控制主文件体积： 尽量将 SKILL.md 文件大小控制在 5000 字以内。
• 细节外移： 将详细的 API 文档、背景资料移至 references/ 目录，实现按需加载。
• 精简激活的技能集： 建议同时启用的 Skill 总数少于 20 个，过多会显著影响 AI 的响应性能。

七、Skill 开发与测试检查清单

最后，附上一份从开发到测试的完整检查清单，助你查漏补缺，打造高质量的 AI 技能。

开发阶段检查项

• 技能文件夹使用 kebab-case 命名（短横线连接）
• 根目录下存在 SKILL.md 文件（拼写精确）
• YAML frontmatter 被 --- 分隔符正确包裹
• name 字段为 kebab-case，不含空格
• description 字段包含“功能描述”与“触发条件”
• description 字符数少于 1024
• 内容中未使用 XML 标签（如 ）
• 操作指令清晰、具体、可执行
• 包含常见错误处理指南
• 提供了典型的使用示例

测试阶段检查项

• 在明确相关的任务请求下能正确触发 ✅
• 对用户同义改述的请求也能正确触发 ✅（例如，“做个文档” vs “生成一份说明”）
• 在不相关的主题下不会误触发 ❌
• 技能执行的功能输出符合预期
• 集成的外部工具（MCP）调用有效