基于《The Complete Guide to Building Skills for Claude》及 Skill Authoring Best Practices 整理。本文面向手动编写 Skill 的开发者——你直接写 SKILL.md、手动测试、手动迭代，涵盖 YAML frontmatter、正文写作、目录结构、分发共享等完整知识。

1. 一句话理解 Skill

Skill 是一组以文件夹形式打包的指令、流程与附加资源，用来教 Agent 在特定任务上稳定地采取正确步骤、调用正确工具、输出符合预期结果。

  • 适合可重复、可标准化的任务

  • 不是一次性 prompt，而是可复用工作方式

  • 可独立使用，也可与 MCP 配合

2. 标准结构

1
2
3
4
5
your-skill-name/
├── SKILL.md
├── scripts/
├── references/
└── assets/

关键规则：

  • SKILL.md 文件名必须完全一致

  • 文件夹名使用 kebab-case

  • skill 文件夹内部不要放 README.md

分层装载（Progressive Disclosure）：

  1. YAML frontmatter（name + description） — 总是进入上下文，负责触发判断

  2. SKILL.md 正文 — Skill 触发后加载，负责主流程

  3. references/scripts/assets — 按需读取，负责细节支撑

SKILL.md 保持精炼（理想 < 500 行），超长说明拆到 references/，并在正文中明确告诉模型何时读取哪个 reference。

3. 三个核心原则

3.1 渐进式披露

同上，三层模型。

3.2 可组合性

你的 skill 应能与其他 skills 共存，不应假设自己是唯一能力来源。

3.3 可移植性

尽量让 skill 可跨 Claude.ai、Claude Code、API 复用；环境要求写进 compatibility。

4. MCP 与 Skill

  • MCP：提供连接与工具访问

  • Skill：提供工作流与最佳实践

  • MCP 解决"能做什么"

  • Skill 解决"应该怎么做"

5. 规划方法

从用例出发，不要一上来就写 SKILL.md。先定义 2–3 个具体用例，每个用例写清：

  • 目标结果

  • 触发方式

  • 执行步骤

  • 所需工具

  • 嵌入的领域知识

常见三类：文档与资产生成、工作流自动化、MCP 增强。

6. 成功标准

定量

  • 触发准确率

  • 工具调用数 / token 消耗

  • API 失败率

定性

  • 用户无需频繁提示下一步

  • 多次执行结果一致

  • 新用户低指导即可完成

7. YAML frontmatter 最小模板

必填字段

1
2
3
4
---
name: your-skill-name
description: 这个 skill 做什么。用户在什么情况下应使用它。
---

完整模板（含官方所有可选字段）

1
2
3
4
5
6
7
8
9
10
11
12
13
---
name: your-skill-name               # 必填，kebab-case，最长 64 字符
description: >                       # 必填，WHAT + WHEN，最长 1024 字符
  这个 skill 做什么。当用户提到 [触发短语] 时使用。
license: MIT                         # 可选，开源许可证
compatibility: claude-code           # 可选，环境要求，1–500 字符
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选，限制工具
metadata:                            # 可选，自定义键值对
  author: Your Team
  version: 1.0.0
  category: workflow-automation
  tags: [project-management, automation]
---

关键规则：

  • name 必填，kebab-case，最长 64 字符，须与文件夹名一致

  • description 必填，最长 1024 字符，必须写清做什么 + 什么时候用，带真实触发短语

  • 禁止 XML 尖括号 < >（安全限制，frontmatter 出现在系统提示中，恶意内容可能注入指令）

  • 名称中禁止使用 claude 或 anthropic（保留字）

  • 描述应使用第三人称

8. 写好 description

推荐公式：

1
[做什么] + [什么时候触发] + [关键能力]

关键原则

  • description 不是普通简介，是 Skill 触发的主要依据

  • 必须同时写清两类信息：这个 Skill 做什么，以及什么时候该调用它

  • 当前模型存在 undertrigger 倾向，因此 description 要写得更主动、更明确，不能过于保守

写法对比（官方示例）

模糊（反例）：

帮助项目。

只描述功能但不写触发（反例）：

创建复杂的多页文档系统。

正确（正例）：

分析 Figma 设计文件并生成开发者交接文档。当用户上传 .fig 文件、要求"设计规范"、"组件文档"或"设计到代码交接"时使用。

管理 Linear 项目工作流，包括冲刺规划、任务创建和状态跟踪。当用户提到"sprint"、"Linear 任务"、"项目规划"或要求"创建 tickets"时使用。

PayFlow 端到端客户入职工作流。处理账户创建、支付设置和订阅管理。当用户说"入职新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。

三个正例的共同特点：具体提到产品名和文件类型、包含用户会说的真实短语、明确说明使用场景。

好描述特征

  • 具体

  • 带用户真实说法

  • 写清适用对象/文件类型/场景

  • 强调结果价值

  • 覆盖不同表述风格（正式、口语、缩写、带错别字等）

9. 写好 SKILL.md 正文

推荐结构

  1. 标题与目的（说明要解决的问题和适用边界）

  2. 核心步骤

  3. 示例

  4. 错误处理

  5. references 链接

写作原则

设定适当的自由度（来自 Skill Authoring Best Practices）

Skill 不是越严格越好，需要根据任务特性设定合适的自由度级别：

自由度 形式 适用场景
高自由度 纯文本指令 多种方法均可行、依上下文决策（如代码审查流程）
中自由度 伪代码或带参数的脚本 有首选模式但可接受变化
低自由度 无参或极少参数的特定脚本 脆弱、易出错的操作，需精确步骤（如数据库迁移）

原文用类比说明：窄桥靠近悬崖处需要护栏和精确指示，开阔地带只需大方向。

解释为什么，比堆 MUST 更有效（来自 skill-creator）

如果你发现自己不断写 ALWAYS、NEVER，这通常是黄色信号。更好的方式是说明：

  • 为什么这一步重要

  • 错过会造成什么后果

  • 在什么场景下它最关键

模型能理解意图与因果，不只是机械照做。

用示例约束输出

对于格式要求、命名规则、报告结构，给示例比纯抽象规则更稳定。适合的场景：

  • commit message 格式

  • 报告结构

  • 文件命名

  • 表格格式

  • 输出 JSON / Markdown 模板

保持通用性，避免过拟合

Skill 写作阶段很容易被几个测试样例"绑架"。如果 Skill 只对反复测试的几个案例有效，那它几乎没有价值。

  • 不要为了通过某一条 eval 加入过窄规则

  • 观察失败背后的共性，而不是给单一问题打补丁

  • 优先抽象成可迁移的原则、脚本或模式

最佳实践

  • 指令要具体、可执行

  • 关键校验前置

  • 常见报错给出明确解决方案

  • 长说明放 references/

  • 确定性验证优先脚本化

  • 用祈使句，步骤明确

多域技能按变体组织

如果一个 Skill 覆盖多个云、多种框架或多个场景，不要把所有细节揉在一个长文里。更好的方式：

  • 主 SKILL.md 中做选择逻辑

  • 再指向具体变体文档，如 aws.md、gcp.md、azure.md

需要避免的反模式（来自 Skill Authoring Best Practices）

  • 使用 Windows 风格路径：始终用正斜杠，scripts/helper.py 而非 scripts\helper.py

  • 引用嵌套过深：所有 reference 文件应从 SKILL.md 直接链接（一级引用），避免链式引用

  • 包含时效信息：不要在 Skill 中写入日期或随时间变化的信息；遗留模式用 <details> 折叠标记

  • 术语不一致：选定一个术语（如统一用"API endpoint"）贯穿全文，不要混用同义词

  • 提供过多选项：除非必要，给出默认方案和一个逃生舱口，而非多个并列选择

10. 脚本化重复工作

如果多个测试用例里模型都在重复写类似的辅助代码，说明这些动作应该被 skill 内置到 scripts/ 里。脚本化沉淀的三层收益：

  • 减少重复劳动

  • 提高稳定性

  • 降低 token 与执行波动

11. 测试与迭代

11.1 三种测试层级

  • Claude.ai 手工测试

  • Claude Code 脚本测试

  • API 程序化测试

官方建议： 先在单个具有挑战性的任务上反复迭代直到 Claude 成功，再将成功方案提炼成 Skill，然后扩展到多个测试用例。

跨模型测试（来自 Skill Authoring Best Practices）： 分别用 Haiku（检查指令是否足够详细）、Sonnet（检查是否清晰高效）、Opus（检查是否过度解释）测试同一个 Skill。

11.2 测试提示词设计

好的 eval prompt 应该具体、有上下文、有细节、接近真实输入。包含文件名、路径、业务背景、字段名、语气差异、口语缩写等。

坏例子："Format this data"、"Create a chart" 好例子：包含具体文件、格式要求、业务上下文的完整描述。

11.3 三类测试覆盖

  1. 触发测试 — description 是否能准确触发

  2. 功能测试 — skill 是否按预期执行

  3. 性能对比测试 — with-skill 比 baseline 好在哪

11.4 迭代信号

  • 欠触发：补关键词和场景说明

  • 过触发：缩小范围，增加排除条件

  • 执行不稳：补校验、补错误处理、优化步骤说明

  • 只看最终输出还不够，要读 transcript — 中间路径的低效、冗余、不稳定会掩盖真正问题

12. 分发与共享

推荐做法：

  1. GitHub 公开仓库托管

  2. 面向人类写 README

  3. 在 MCP 文档中解释为何要和 skill 搭配

  4. 提供快速安装指南

对外表达重点：

  • 讲结果，不讲内部实现

  • 讲"连接能力 + 工作流能力"的组合价值

  • 强调节省时间、降低学习成本、提高一致性

13. 五种常见模式

  1. 顺序式工作流编排

  2. 多 MCP 协同

  3. 迭代式精修

  4. 上下文感知式工具选择

  5. 领域智能增强

14. 故障排查

上传失败

  • 检查 SKILL.md

  • 检查 YAML 分隔符和缩进

  • 检查 skill name 是否合规

不触发 / 过触发

  • 优先改 description

  • 让 Claude 复述触发范围做调试

  • 欠触发补真实术语，过触发加限定词

加载了但执行不对

  • 压缩说明，突出关键规则

  • 把模糊要求改成明确校验条件

  • 关键验证脚本化

MCP 调用失败

  • 先验证 MCP 本身是否可用

  • 检查认证、权限、工具名

  • 尝试让 Claude 直接调用 MCP

上下文过大

  • 控制 SKILL.md 大小

  • 把细节移到 references/

  • 不要同时开太多 skills

15. 上线前检查清单（来自 Complete Guide）

开始之前

  • 已确定 2–3 个具体使用场景

  • 已确定所需工具（内置或 MCP）

  • 已规划文件夹结构

开发过程中（来自 Complete Guide）

  • 文件夹以 kebab-case 命名

  • SKILL.md 文件存在（拼写准确，区分大小写）

  • YAML frontmatter 有 --- 分隔符

  • name 字段：kebab-case，无空格，无大写字母

  • description 包含功能（WHAT）和使用时机（WHEN）

  • 无 XML 标签（< >）

  • 指令清晰且可执行

  • 包含错误处理

  • 提供了示例

  • 引用已清晰链接

上传之前（来自 Complete Guide）

  • 已测试在明显任务上的触发

  • 已测试在换句话请求上的触发

  • 已验证不会在无关话题上触发

  • 功能测试通过

  • 工具集成正常（如适用）

  • 已压缩为 .zip 文件

上传之后

  • 在真实对话中测试

  • 监控触发不足/过度触发情况

  • 收集用户反馈

  • 迭代 description 和指令

  • 在 metadata 中更新版本号

16. 可复用模板

1
2
3
4
5
6
7
8
9
10
---
name: projecthub-sprint-planning
description: 管理 Linear/ProjectHub 冲刺规划流程，包括读取当前状态、评估容量、建议优先级并创建任务。适用于用户提到 sprint、迭代规划、创建 tickets、project planning 等场景。
metadata:
  author: Your Team
  version: 1.0.0
  mcp-server: projecthub
  category: workflow-automation
  tags: [sprint-planning, linear, automation]
---

17. 常见误区

误区 1：为少量例子过拟合

后果：当前几个样例看起来更顺，但泛化能力更差。抽象共性，而不是打局部补丁。

误区 2：把 description 写得太保守

后果：Skill 明明该触发，却始终没有被 consult。当前模型倾向 undertrigger，description 应适度主动。

误区 3：把重复劳动留给模型临场发挥

后果：每次都重新造轮子，成本高且不稳定。应沉淀到 scripts/。

误区 4：指令模糊，期待模型自行补全

后果：输出不稳定、不可预期。用具体示例和校验条件替代模糊描述。

18. 延伸阅读

  • The Complete Guide to Building Skills for Claude — Anthropic 官方 Skill 构建完整指南（结构规范、YAML 规范、分发与故障排查）

  • Skill Authoring Best Practices — Anthropic 官方 Skill 写作最佳实践（自由度设定、反模式识别、跨模型测试）

  • anthropics/skills — GitHub 开源仓库，包含 skill-creator 等官方 Skill 示例