Skill 是什么 · 渐进披露 · 与 MCP 的关系
用例 · 成功指标 · 文件结构 · YAML 规范
三层测试 · skill-creator · 过/欠触发
GitHub · API · 组织级部署
五大编排模式 · 常见问题速查
官方资料 · 工具 · 上线检查
一个 文件夹，里面装着一组 指令，
用来教会 Claude 如何处理 特定任务或工作流。
your-skill/
├── SKILL.md # 必需 · 主指令
├── scripts/ # 可选 · 可执行代码
│ ├── process.py
│ └── validate.sh
├── references/ # 可选 · 深度文档
│ └── api-guide.md
└── assets/ # 可选 · 模板/字体/图标
└── template.md
主指令文件，YAML frontmatter + Markdown 正文，必须精确命名
确定性代码：数据处理、校验、API 调用
按需加载的深度文档，避免塞进主指令
产出用的模板、字体、图标、样式
三级加载机制，让 Claude 只在需要时看到必要的内容 —— 最小化 token，最大化专长。
Claude 可同时加载多个 Skill。你的 Skill 应当与其他 Skill 友好共存，不能假设自己是唯一能力。
→ 命名聚焦、职责单一、不抢场景
同一个 Skill 在 Claude.ai、Claude Code、API 三端行为一致。写一次，三处可用。
→ 前提：运行环境能满足 Skill 所需依赖
提供 工具、食材、设备。
让 Claude 连接上你的服务 —— Notion、Asana、Linear。
回答"Claude 能做什么"
提供 分步指令，教 Claude 如何做出一道菜。
把工作流和最佳实践固化下来。
回答"Claude 应当怎么做"
关键洞察：只给 MCP 不给 Skill，用户连上后不知道下一步做什么，每次对话重新摸索，结果参差不齐 —— 往往把问题怪到 connector 头上，其实是工作流指引缺失。
动手前先想清楚：你要解决谁的什么问题？
用例：Sprint 规划 触发：用户说"帮我排这个 sprint" / "创建 sprint 任务" 步骤： 1. 从 Linear（经由 MCP）拉取当前项目状态 2. 分析团队速度与容量 3. 给出优先级建议 4. 在 Linear 创建带标签与估点的任务 结果：完整可执行的 sprint 与任务
生成高一致性、高质量的文档、演示、代码、设计、海报。
示例 frontend-design · docx · pptx · xlsx
关键技巧：嵌入风格指南、模板结构、交付前质量清单，无需外部工具。
需要一致方法论的多步流程，可能跨多个 MCP。
示例 skill-creator
关键技巧：带校验关卡的分步流程、模板、内置评审、迭代优化回路。
为已有 MCP server 提供工作流级别的指引。
示例 Sentry code-review
关键技巧：协调多 MCP 调用顺序、嵌入领域专长、内置错误处理。
注：这是粗略基准，而非精确阈值。接受"基于直觉"的判断。
Claude 就靠 frontmatter 决定要不要加载你的 Skill —— 务必写对。
--- name: your-skill-name description: 做什么。当用户 要求 [具体短语] 时使用。 ---
name · kebab-case，小写，无空格、下划线、大写，与文件夹名一致
description · 必须同时包含：
① 做什么 ② 何时用 ③ 不超过 1024 字符 ④ 禁用 XML 尖括号
✓ notion-project-setup ✗ Notion Project Setup ✗ notion_project_setup ✗ NotionProjectSetup
文件名必须是 SKILL.md（大小写敏感）· 不要放 README.md 进 Skill 文件夹
[做什么] + [何时使用] + [关键能力]
分析 Figma 设计文件，生成开发交接文档。当用户上传 .fig 文件、索要"设计规范"或"组件文档"时使用。
管理 Linear 项目工作流 —— sprint 规划、任务创建、状态追踪。用户提到"sprint"、"Linear 任务"或"创建工单"时触发。
帮你处理项目。（太空）
创建复杂的多页文档系统。（缺触发词）
实现带层级关系的 Project 实体模型。（太技术，没用户侧触发）
运行 python scripts/validate.py --input {filename}。若校验失败，常见问题：缺字段（加到 CSV）、日期格式错（用 YYYY-MM-DD）
校验数据后再继续。（太模糊）
明确列出：常见错误 → 原因 → 解决方案。例如 MCP 连接失败时的三步排查。
主动指向 references：
"写查询前先阅读 references/api-patterns.md，了解限流、分页、错误码。"
SKILL.md 只写核心；详细文档搬到 references/；超过 5000 词时必须拆分。
Skill 是活文档 —— 靠反馈持续进化
确保 Skill 在合适时机加载。
✓ 明显任务触发
✓ 改写说法也能触发
✗ 不相关主题不触发
确认 Skill 产出正确。
✓ 输出有效
✓ API 调用成功
✓ 错误处理可用
✓ 边界情况覆盖
证明比"没有 Skill"更好。
对比：消息数、tool calls、失败 API、token 消耗
黄金建议：先在单个有挑战的任务上迭代到 Claude 能成功处理，再把成功的做法固化成 Skill，然后扩展到更多测试用例 —— 利用 Claude 的 in-context learning，反馈信号比"撒大网测试"快得多。
症状：
对策：
description 加细节与技术关键词，提升触发敏感度
症状：
对策：
加负面触发词（"不用于 X"），description 更具体
调试技巧：直接问 Claude —— "你会在什么时候用 [Skill 名]？" Claude 会复述它理解的 description，照着补齐缺失信息。
Claude.ai 插件目录或 Claude Code 可用 —— 若已有 MCP server 与 2-3 个核心工作流，通常 15-30 分钟即可产出可用 Skill。
从个人工具到开放标准
/v1/skills 端点container.skills 参数开放标准：Agent Skills 已作为开放标准发布。和 MCP 一样，Anthropic 相信 Skill 应当跨工具、跨平台可移植 —— 同一份 Skill 应在 Claude 之外的 AI 平台也能工作。
| 场景 | 最佳落地 |
|---|---|
| 终端用户直接使用 Skill | Claude.ai / Claude Code |
| 开发期的手动测试与迭代 | Claude.ai / Claude Code |
| 个人 / 临时工作流 | Claude.ai / Claude Code |
| 应用以程序化方式调用 Skill | API |
| 规模化生产部署 | API |
| 自动化流水线 + Agent 系统 | API |
注：API 使用 Skill 需要 Code Execution Tool beta —— 提供 Skill 运行所需的安全环境。
从早期采用者沉淀出的通用骨架
适用：多步流程有严格顺序
举例 新客户 onboarding：创建账号 → 绑定支付 → 订阅 → 发欢迎邮件
关键技巧：显式步骤编号、步骤间依赖、每步校验、失败回滚指令。
适用：工作流跨多个服务
举例 设计交接：Figma 导出 → Drive 存储 → Linear 建任务 → Slack 通知工程团队
关键技巧：阶段分离、数据在 MCP 间传递、阶段前置校验、集中错误处理。
适用：输出质量靠迭代提升
举例 报告生成：初稿 → 运行校验脚本 → 识别缺段/格式/数据问题 → 修复 → 重验证 → 达到阈值停止
关键技巧：明确质量标准、逐轮改进、校验脚本、知道何时停止。
适用：同一结果、不同情境用不同工具
举例 文件存储：大文件→云盘 MCP；协作文档→Notion；代码→GitHub；临时→本地
关键技巧：清晰的决策树、兜底选项、向用户解释为什么选这个工具。
当 Skill 要添加"工具访问之外的专业知识"时使用。
| 症状 | 根因 | 对策 |
|---|---|---|
| 上传失败："找不到 SKILL.md" | 文件名大小写错了 | 严格命名为 SKILL.md |
| "Invalid frontmatter" | YAML 缺 --- 分隔符或引号未闭合 | 补齐分隔符、检查引号 |
| "Invalid skill name" | name 有空格或大写 | 改为 kebab-case |
| Skill 加载但不执行指令 | 指令冗长 / 埋太深 / 语义模糊 | 关键放顶部、用 ## Critical、改成祈使句 |
| MCP 调用失败 | 连接断 / 认证失效 / 工具名写错 | 先独立测 MCP、核对工具名大小写 |
| 响应变慢 / 质量下降 | SKILL.md 过大、启用太多 Skill | 搬到 references、<5000 词、精简启用 |
高级技巧：关键校验用脚本实现而非自然语言指令 —— 代码是确定的，语言解释不是。参考 Office 系列 Skill 的实现方式。
SKILL.md 精确拼写--- 分隔符license、allowed-tools< >（安全限制）claude 或 anthropic（保留）原因：frontmatter 出现在 Claude 系统提示中，恶意内容可能注入指令。
Skills 是"组织级知识"的工程化封装。
MCP 让 AI 连上工具，Skills 让 AI 用好工具 —— 前者是连通性，后者是认知与工艺。
对创意内容平台，真正的护城河不在模型，而在"你们家的工艺怎么做出来"这种沉淀。
anthropics/skills原文：The Complete Guide to Building Skills for Claude（Anthropic）
PDF：resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
精读整理：Wayne 研究室 · 2026-04-16 · 中文结构化重组版
本文按 Wayne 研究室规范进行结构化重组、概念翻译与视角补充，并非逐句翻译。原文版权归 Anthropic 所有。