第 1 章：基础（Fundamentals）

什么是 Skill？

Skill 是一个文件夹，包含：

  • SKILL.md（必需）：用 Markdown 写的指令文件，顶部带 YAML frontmatter
  • scripts/（可选）：可执行代码（Python、Bash 等）
  • references/（可选）：按需加载的参考文档
  • assets/（可选）：模板、字体、图标等输出素材

核心设计原则

1) 渐进式披露（Progressive Disclosure）

Skills 使用三级系统：

  • 第一层（YAML frontmatter）：始终加载进系统提示词（system prompt）。它只提供“Claude 判断何时该用这个 skill”的最小信息，不把全部内容塞进上下文。
  • 第二层（SKILL.md 正文）：当 Claude 判断这个 skill 与当前任务相关时才加载，包含完整指令与指导。
  • 第三层（链接文件）：skill 目录里的其他文件（references/assets/scripts 等），Claude 只在需要时再自行读取。

这种渐进式披露能在保留专业能力的同时，最大化节省 token。

2) 可组合性（Composability）

Claude 可以同时加载多个 skills。你的 skill 应该能与其它 skill 共存，而不是假设“自己是唯一能力”。

3) 可移植性（Portability）

Skills 在 Claude.ai、Claude Code、以及 API 上表现一致：写一次，到处可用（只要运行环境支持你需要的依赖）。

面向 MCP 构建者：Skills + Connectors

💡 如果你只是在做 standalone skills、没有 MCP，可以先跳到“规划与设计”，之后再回来也行。

如果你已经有一个可工作的 MCP server，你最难的部分其实已经完成了。Skill 是叠在上面的“知识层”——把你已经知道的工作流与最佳实践固化下来，让 Claude 能稳定复用。

厨房类比

  • MCP 提供“专业厨房”：工具、食材、设备的可访问性。
  • Skills 提供“菜谱”：一步一步把东西做出来的操作方法。

两者结合，让用户无需自己摸索每一步，就能完成复杂任务。

它们如何协作

  • MCP（连接性 / Connectivity）：把 Claude 接入你的服务（Notion、Asana、Linear 等），提供实时数据访问与工具调用。
  • Skills（知识 / Knowledge）：教 Claude 如何有效使用你的服务，沉淀工作流与最佳实践。

这对你的 MCP 用户为什么重要

没有 skills 时：

  • 用户连上你的 MCP，却不知道下一步怎么用
  • 支持工单会变成“我如何用你集成完成 X？”
  • 每次对话从零开始，结果不一致（因为每个人 prompt 不一样）
  • 用户会把“不会用”归因到 connector 上

有 skills 时：

  • 常用工作流会在合适时机自动激活
  • 工具调用更一致、更可靠
  • 最佳实践被嵌入每次交互
  • 降低学习成本

第 2 章：规划与设计（Planning and design）

从用例开始

在写任何东西前，先明确 2–3 个你的 skill 要支持的具体用例。

一个好的用例定义例子：

  • 用例：项目 Sprint 规划
  • 触发：用户说“帮我规划这个 sprint”或“创建 sprint 任务”
  • 步骤：
  • 通过 Linear（MCP）拉取当前项目状态
  • 分析团队速度与容量
  • 建议任务优先级
  • 在 Linear 里创建任务，带正确的标签与估算
  • 结果：一个完整规划好的 sprint（任务都创建好了）

自问：

  • 用户想达成什么？
  • 这需要怎样的多步工作流？
  • 需要哪些工具（内建或 MCP）？
  • 需要嵌入哪些领域知识与最佳实践？

常见 skill 用例分类

我们观察到三类常见用例：

类别 1：文档与资产生成（Document & Asset Creation）

用于：稳定生成一致、高质量输出（文档、演示、应用、设计、代码等）。

例：frontend-design skill（也可参考 docx/pptx/xlsx/ppt 等 skills）

关键技巧：

  • 内置风格指南与品牌规范
  • 模板结构保证一致性
  • 交付前质量检查清单
  • 不依赖外部工具：用 Claude 内建能力完成

类别 2：工作流自动化（Workflow Automation）

用于：有一致方法论的多步流程，可能跨多个 MCP server 协同。

例：skill-creator skill

关键技巧：

  • 分步骤、带校验门槛（validation gates）的流程
  • 常见结构模板
  • 内置 review 与改进建议
  • 迭代式 refinement loop

类别 3：MCP 增强（MCP Enhancement）

用于：给 MCP 工具访问“加工作流指导层”。

例：来自 Sentry 的 sentry-code-review skill：结合 Sentry 的监控数据（MCP）自动分析并修复 GitHub PR 中的 bug。

关键技巧：

  • 串行协调多个 MCP 调用
  • 内置领域知识
  • 补齐用户本来要自己描述的上下文
  • 为常见 MCP 异常提供错误处理

定义成功标准

你怎么知道 skill “有效”？这里给的是目标/基准，不是严格阈值。

定量指标：

  • 在 90% 的相关查询中能触发 skill
  • 测量：准备 10–20 条应触发的测试 query，统计自动加载 vs 需要手动启用
  • 在 X 次工具调用内完成工作流
  • 测量：对比启用/不启用 skill 的工具调用次数与 token 消耗
  • 每个工作流 0 次失败 API 调用
  • 测量：看 MCP server 日志，统计重试率与错误码

定性指标：

  • 用户无需不断提示“下一步是什么”
  • 工作流能在不需要用户纠错的情况下完成
  • 跨 session 输出一致

技术要求

文件结构

your-skill-name/
├── SKILL.md              # 必需：主文件
├── scripts/              # 可选：可执行脚本
│   ├── process_data.py
│   └── validate.sh
├── references/           # 可选：文档
│   ├── api-guide.md
│   └── examples/
└── assets/               # 可选：模板等
    └── report-template.md

关键规则

  • SKILL.md：必须精确命名为 SKILL.md（大小写敏感），不接受任何变体。
  • skill 文件夹命名：必须 kebab-case（如 notion-project-setup），不能有空格/下划线/大写。
  • skill 文件夹内不要放 README.md：人看的 README 应放在 repo 顶层；skill 内的说明写在 SKILL.md 或 references/。

YAML frontmatter：最重要的部分

YAML frontmatter 决定 Claude 是否加载你的 skill。

最小格式：

---
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：说明环境要求（产品、系统包、网络需求等）
  • metadata：自定义 key-value（作者/版本/mcp-server 等）

安全限制（frontmatter 禁止）：

  • XML 尖括号 < >
  • skill 名称中含 “claude” 或 “anthropic”（保留前缀）

第 3 章：测试与迭代（Testing and iteration）

skills 的测试可以有不同严谨度：

  • Claude.ai 手工测试：直接提问观察行为；迭代快
  • Claude Code 脚本化测试：把测试用例自动化，方便回归
  • Skills API 程序化测试：搭评测套件系统化跑测试集

选择与你的质量要求、skill 的曝光规模匹配的测试方式。

小贴士：先把一个难点任务打穿再扩展

最有效的做法往往是：先选一个“最难/最关键”的任务，把它迭代到 Claude 能稳定成功；然后把成功的方法抽成 skill。等 foundation 稳了，再拓展更多测试用例覆盖。

推荐测试覆盖三块

1) 触发测试：该触发时触发；换说法也触发；无关话题不触发。

2) 功能测试：输出正确；API 调用成功；错误处理有效；边界条件覆盖。

3) 性能对比：与 baseline 对比是否减少来回、减少失败调用、减少 token。

skill-creator 的用途

skill-creator（Claude.ai 插件目录 / Claude Code 可下载）能帮你：

  • 从自然语言描述生成 skill
  • 产出正确格式的 SKILL.md + frontmatter
  • 建议触发词与结构
  • Review skills：指出常见问题（描述太泛、缺 triggers、结构问题、过/欠触发风险），并给测试用例建议
  • 迭代改进：把失败案例带回去，让它帮你调整 skill 对 edge case 的处理

第 4 章：分发与分享（Distribution and sharing）

skills 会让你的 MCP 集成更完整：用户比较 connectors 时，带 skills 的方案能更快让用户获得价值。

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

个人用户获取 skills：

  1. 下载 skill 文件夹
  2. 必要时打 zip
  3. 在 Claude.ai：Settings > Capabilities > Skills 上传
  4. 或放入 Claude Code 的 skills 目录

组织级 skills：

  • 管理员可以 workspace-wide 部署（2025-12-18 上线）
  • 支持自动更新与集中管理

开放标准

Agent Skills 已被发布为开放标准（类似 MCP）。目标是让 skill 可在不同工具和平台间可移植。当然，有些 skill 会充分利用某个平台特性，作者可在 compatibility 字段注明。

通过 API 使用 skills

API 适用于更程序化的场景（应用/代理/自动化工作流）：

  • /v1/skills：列出与管理 skills
  • 通过 container.skills 参数把 skills 加入 Messages API
  • Claude Console 里做版本控制与管理
  • 可与 Claude Agent SDK 协作

第 5 章：模式与排错（Patterns and troubleshooting）

这些模式来自早期采用者与内部团队实践：它们是“常见有效做法”，不是硬规范。

选择你的 framing：以问题为先 vs 以工具为先

  • 问题优先：用户说“我要达成 X”，skill 负责编排 MCP 调用；用户讲结果，skill 处理工具。
  • 工具优先：用户说“我已经接了 Notion MCP”，skill 教 Claude 最优工作流与最佳实践；用户有 access，skill 提供 expertise。

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

适用：必须按特定顺序执行的多步流程。

要点：明确步骤顺序、步骤依赖、每步校验、失败回滚。

Pattern 2：多 MCP 协同（Multi-MCP coordination）

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

要点：分阶段、跨服务传数据、进入下一阶段前校验、集中错误处理。

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

适用：输出质量会随着迭代显著提升。

要点：明确质量标准、循环改进、用脚本校验、知道何时停止。

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

适用：同一目标在不同上下文用不同工具更优。

要点：明确决策树、备选方案、对用户透明解释。

Pattern 5：领域智能（Domain-specific intelligence）

适用：skill 的价值在于“领域知识”，而不仅是工具访问。

要点：把领域规则编码进流程（如合规优先）、留下审计轨迹、治理清晰。

Troubleshooting（排错）

  • 上传失败：通常是找不到 SKILL.md（命名不对）或 frontmatter YAML 格式错误。
  • 不触发：多半是 description 太泛或缺少用户会说的 triggers。
  • 触发过多：加 negative triggers、缩小范围、澄清适用场景。
  • MCP 连接问题：先确认 MCP 本身能独立调用；再核对工具名大小写；看鉴权/权限。
  • 指令不被遵循：指令过长、关键点埋太深、语言模糊；可把关键校验写成脚本更稳。
  • 大上下文导致慢/降质：控制 SKILL.md 规模，细节下沉到 references/，减少同时启用的 skills。

第 6 章：资源与参考（Resources and references）

  • 官方文档（Anthropic Resources / Skills Documentation / API Reference / MCP Documentation）
  • 博客：介绍 Agent Skills、工程实践、如何为 Claude Code 构建 skills 等
  • 示例仓库：anthropics/skills（可克隆后改成自己的）
  • 工具：skill-creator（生成/Review/给建议）
  • 支持渠道：Claude Developers Discord 社区、GitHub Issues（anthropics/skills/issues）

End.