Anthropic 官方教程：建立 Skills 的秘密都在这里

前言

你是否遇到过以下痛点：

• 每次和 AI 助手对话，都得重新解释自己的偏好和工作流程。话说回来，
• 想让 AI 按照特定流程处理任务。但每次都要详细说明，
• 团队协作时无法标准化 AI 使用流程，导致输出质量参差不齐。

Agent Skills 正是为解决这些问题而生。它把工作流程、常用方法和领域知识打包成可复用的“技能包”。让 AI 一次学习，终身受益。

一、什么是 Agent Skills？

主要定义

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

为什么需要 Skills？

传统方式的痛点：

• 输出结果不一致，取决于提示词质量。
• 团队协作时难以标准化流程。
• 复杂工作流难以可靠执行。

使用 Skills 的优势：

• 标准化输出质量。
• T团队知识沉淀和共享。
• 复杂流程自动化执行。

典型使用场景

二、主要架构与设计原则

文件结构示例

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

再看主要设计原则，渐进式披露

…Skill采用三层信息加载机制：YAML Frontmatter -> SKILL.md 主体 -> references & assets 按需访问。怎么说呢，这样可以最小化 Token 使用，同时保持专业性。怎么说呢，

原则 ：可组合性

• 不假设自己是唯一能力；支持多 Skill 并行加载；避免功能冲突，

原则 ：可移植性

• 一次创建，多网站使用：Claude.ai / Claude Code / API 调用等。

YAML Frontmatter详解

• 禁止使用XML标签；名称不能包含关键字“claude”或“anthropic”。

三、规划与设计实战

明确使用场景

先确定一个具体且可衡量的目标，例如：“帮我规划这次冲刺”或“创建冲刺任务”。如果没有清晰目标，你将陷入无意义循环——每一次调用都像重新学习一样耗时耗力。BINGO 提示：# 从 Linear 获取当前项目状态 → 分析速度 & 容量 → 建议优先级 → 在 Linear 创建任务。完成后你会得到一个已创建好的冲刺列表，而不是一堆未完成的待办事项。这一步骤就像搭配 “起点 + 步骤 + 输出” 的三段式剧本，让 AI 明白你的意图而不是猜测。

推荐操作

• 目标导向先写下结果，接下来逆向拆解步骤。
• 关键词定位把关键触发词写进 description 字段，以确保准确匹配。
• 验证反馈先在 Claude.ai 中手动测试一次看是否能按预期触发。

选择 Skill 类别

成功指标

* 定性指标 *

• :: 使用者无需提示接下来 :: 工作流能完整运行。无需人工干预 :: 会话间保持一致 :: 新使用者首次就可以完成任务 :: 完全由 Skill 控制产出，不再依赖提示语调变化::

  ---

  编写 Description 字段

  yaml description: 分析 Figma 设计文件并生成开发者交接文档。当使用者上传 .fig 文件并询问 "设计规范" 或 "组件文档" 时使用。description: 帮助处理项目。

  指令结建立议

  markdown

  指令名称

  步骤 A:

  说明第一步先操作。怎么说呢，bash python scripts/fetch_data.py --project_id PROJECT_ID

  输出这方面。

  成功后返回明确结果，如 "数据已提取"。

  ---

  示例

  **情境这方面，** 使用者说：“设置一个新的营销活动” 再看**操作顺序，** 1️⃣ 检索现有活动 2️⃣ 创建新活动 ➡️ 返回确认链接

  ---

  故障排除

  常见错误及修复

  错误消息	原因	修复方案
  “Could not find SKILL.md in uploaded folder”	文件命名错误	确认目录内存在 SKILL.md
  “Invalid frontmatter”	YAML 格式不正确 或引号未闭合	用 --- 包裹字段。并检查引号闭合

  性能问题

  • 大上下文导致响应慢 – 将冗余内容移至 references/保持 SKILL.md 在几千 token 内。
  • 过度触发 – 添加负面触发器，例如 “不要用于简单的数据探索”。

  ---

  四、高质量 Skill 编写技巧

  1️⃣ 黄金公式 — + + 2️⃣ 简洁明了 — 避免长句子，用列表呈现步骤。3️⃣ 显式错误处理 — 在指令顶部加入 “如果出现 X 错误，请尝试 Y 操作”。

  ---

  五 测试 &️迭代

  手动测试

  适用于快速验证新技能。

  脚本化测试

  确保跨版本兼容，可重复执行。

  API 测试

  适用于公司级部署，全量回归检测。

  推荐流程的观点是，

  1️⃣ ✅ 正确触发检查 2️⃣ ✅ 功能完整性验证 3️⃣ ⚖️ 性能对比评估

  ---

  六 常见模式 & 常用方法

  顺序工作流编排

  yaml 至于steps，- name: 创建账户 再看tool，create_customer 至于params，name: $name email这方面，$email ...

  多 MCP 协调

  yaml phase这方面。- name: 存储资产 ...

  上下文感知工具选择

  yaml if file_size>=10MB: use cloud_storage_mcp elif file_type == 'doc': use notion_mcp ...

  ---

  七 分发 & 分享

  1️⃣ 打包为 .zip 并上传至 Claude.ai Settings → Capabilities → Skills 或托管于 GitHub。

  2️⃣ 为组织级 Skill 开启 workspace‑level 部署，以便所有成员共享。

  ---

  八 故障排除细节

  Skill 无法上传: 检查 SKILL.md 命名；确认 YAML 前后都有 ---.

  Skill 不触发: 描述太宽泛，缺少实际使用者语言；添加具体短语或负面关键词。话说回来，

  MCP 调用失败: 验证服务器连接状态和权限配置；确认工具名称大小写匹配，

  ---

  九 资源 & 支持渠道

  官方文档: Best Practices Guide,Skills Documentation,API Reference。MCP Documentation 社区支持: Claude Developers Discord / GitHub Issues 实用工具: skill‑creator Skill 自动生成模板；validate.py 校验脚本

  ---

  十 快速检查清单

  ✔️ 已确定具体用例 ✔️ 已识别所需工具 ✔️ 已审阅官方样例 ✔️ 已规划文件夹结构 ✔️ 所有字段符合命名规范 ✔️ 已手动测试触发 ✔️ 已压缩为 .zip

  ---

  十一 & 展望

  A. Skills 是一次配置。多次复用 —— 减轻提示词维护负担，提高团队协同效率。

  B. 设计原则决定实现质量——渐进披露避免 Token 消耗；可组合性防止冲突，可移植性拓宽使用范围。

  C. 持续迭代才是硬核竞争力——从小案例开始，不断收集反馈并调整描述和指令。话说回来，

  以后方向这方面。更多网站支持、更丰富样例、更完善评估框架，让 Agent Skills 成为真正开放环境的一部分。不论你是个人开发者还是公司负责人。只要掌握这些秘诀，就能在 AI 助手时代抢占先机！