如何写出好的 Skill

Skill 是 AI Agent 的”能力插件”——将领域知识、工作流程和工具封装为可复用模块。但写出一个好 Skill 并不简单：它的读者是 AI 而非人类，受限于有限的上下文窗口，需要同时兼顾灵活性与确定性。本文基于 Anthropic 官方的 skill-creator 设计思路和社区实践经验，系统梳理写出好 Skill 的核心原则与实操技巧。

Skill 是什么

Skill 本质上是一个文件夹，包含指令文档、参考资料和可执行脚本。AI 拿到它，就能胜任一项原本不会的特定工作。

1
2
3
4
5

my-skill/
├── SKILL.md          # [必需] 入口：frontmatter + 操作指令
├── scripts/          # [可选] 可执行脚本（确定性操作）
├── references/       # [可选] 参考文档（AI 需要时读取）
└── assets/           # [可选] 产出物模板（直接用于最终输出）

最小形态

最少只需要一个 SKILL.md：

1
2
3
4
5
6
7

---
name: my-skill
description: >-
  当用户需要做某件事时，使用这个技能。
---

按照以下步骤执行...

上半部分是 YAML frontmatter，包含 name 和 description。AI 在每次对话开始时扫描所有已安装 Skill 的 frontmatter，靠 description 来判断是否激活——这是 Skill 被触发的唯一依据。

下半部分是 Markdown 正文，Skill 激活后才加载。

Skill vs Prompt vs Command

Skill 的核心价值：它不是聊天内容，而是打包好的可复用能力。模型发现它、读取它、按它的指令执行，在不同会话中持续生效。

核心原则：给 AI 写指令，不是给人写

写 Skill 时最大的误区就是把 AI 当成人类读者。看一个反面例子：

1
2
3
4
5
6
7
8
9
10
11
12
13

# Code Review Skill

## 背景
本技能基于团队多年的代码审查经验总结而成。

## 审查原则
- 保持专业、建设性的语气
- 关注代码质量而非个人风格
- 平衡严格性和灵活性

## 版本记录
- v1.0: 初始版本
- v1.1: 增加了对 Python 的支持

摘掉”给人看”的滤镜后，问题一目了然：

• “基于多年经验” — AI 不关心技能怎么来的，只关心现在该怎么做
• “保持专业性” — 人类能意会，AI 会把它展开成无数种组合
• “平衡严格性和灵活性” — AI 没有这个直觉，说了等于没说
• “版本记录” — AI 每次唤醒都是全新的，v1.0 还是 v1.1 毫无意义

每一条单独看都不是错，但它们都是写给人看的。问题不在于写得不够多，而在于写错了对象。

AI 已经很聪明了，Skill 只需补充它不知道的东西。每写一段内容前问自己两个问题：

1. “AI 是不是已经知道这个了？”
2. “这段内容值不值得占上下文？”

三大设计维度

维度一：信息放在哪里——三级渐进式加载

上下文窗口是有限的公共资源。skill-creator 设计了分层加载架构，让不同信息在不同时机进入上下文：

• L1 是过滤器 — description 不精确 → 误触发或漏触发
• L2 是操作手册 — 触发后告诉 AI 该怎么做，控制在 500 行以内
• L3 是工具箱 — 其中 scripts 执行而不读入，零 token 成本

L3 四种资源的区别

三种拆分模式

模式 1：高层指南 + 参考文件

1
2
3
4
5
6
7
8

# PDF Processing

## Quick start
Extract text with pdfplumber: [code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

AI 只在需要时才加载 FORMS.md 等大文件。

模式 2：按领域组织

1
2
3
4
5
6

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md
    ├── sales.md
    └── product.md

用户问销售指标时，只加载 sales.md。

模式 3：条件性细节

基础功能直接展示，高级功能按需链接，避免一次性加载所有内容。

常见层错位

维度二：给 AI 多大自由度——自由度光谱

AI 擅长语义理解和创造性工作，但不擅长精确格式控制、长度约束、命名规范——这些”脆弱操作”。

1
2
3

高自由度（文字指令）  →  多种方案都对，依赖上下文判断
中自由度（带参脚本）  →  有最佳实践但允许变通
低自由度（精确脚本）  →  做对只有一种方式，做错有一百种方式

核心判断标准：

1. 做错了后果多严重？ — 越严重 → 越低自由度
2. 有多少种”正确”的做法？ — 越多 → 越高自由度

实操：什么该封装成脚本？

1
2
3
4
5
6
7
8
9

每次执行结果必须一样      → 脚本
涉及精确格式/长度约束     → 脚本
涉及命名规范转换          → 脚本
需要校验规则匹配          → 脚本
同样的代码每次都要重新写   → 脚本

需要理解上下文            → 文字指令
有多种合理做法            → 文字指令
需要创造性判断            → 文字指令

脚本的核心优势是执行而不读入——零 token 成本，你可以把任意复杂的确定性逻辑封装进去。

维度三：质量保障链

skill-creator 用三个脚本形成一条确定性保障链，夹住中间的创造性步骤：

1
2
3
4
5
6
7
8

init_skill.py（输入保障）
  命名标准化 + 目录结构 + 模板生成 → 确保起点正确
       ↓
  AI 创造性编写（高自由度）
  → SKILL.md 内容、references、自定义 scripts
       ↓
quick_validate.py（输出保障）
  frontmatter 格式 + 命名规范 + 长度约束 → 确保终点合规

简洁：根本约束

什么不该放进 Skill

skill-creator 明确列出的禁止清单：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

Skill 的读者是 AI，不是人类开发者。AI 不需要安装指南、更新日志、快速参考这些”人类辅助文档”。

用反模式代替正面描述

“做什么”描述一个无限大的可行域，AI 在里面随机游走。”不做什么”在可行域上画边界，AI 的行为空间被收窄到你想要的范围。

以写作风格 Skill 为例，与其写”请用温暖、克制、有洞察力的语气写作”，不如列一份反模式清单：

每一条都是具体的、可检测的、有明确修正方案的。

做完”反转测试”：每一条正面指导，能不能改写成”不要做 X”的形式？如果可以，改写后通常更精确。

设计类 Skill 的高级技巧

以下来自对 Anthropic 官方 algorithmic-art 和 canvas-design Skill 的深度拆解。

1. 拔高定位

不是”画一张图”，而是”创立一个美学流派”。Skill 应把任务从”生成一件作品”提升到”创建一套体系”，让模型的所有后续推理都围绕这个体系展开。

2. 双阶段结构：理念先行，代码是表达工具

1
2

Phase 1: 哲学/设计理念 → 用结构化维度约束思考方向
Phase 2: 代码/视觉实现 → 将抽象理念映射为具体实现

强制抽象层在前，避免模型直接掉进”写代码、调参数”的局部最优。

3. 为抽象概念提供可操作的维度

把”美学理念”映射到具体的技术对象：

• 噪声函数和随机模式
• 粒子行为和场动力学
• 时间演化和系统状态
• 参数变化和涌现复杂性

每一条都同时是美学语言 + 技术对象，方便直接映射到代码结构。

4. 模板化：定义 FIXED 和 VARIABLE

明确告诉模型哪些是固定不变的（布局、品牌色、按钮），哪些是可自由发挥的（算法逻辑、颜色区域）。这样每次输出都有统一体验，也减少预期外的”惊喜”。

5. 最后一轮精修：不做加法做乘法

把”最后 10% 的工艺感”也编码进 Skill：

如果下一步的本能是”多加一个图标/特效”，请暂停。
问自己：有没有可以删掉的东西？有没有可以对齐、合并、强化的关系？
只允许修改已有元素的位置、间距、权重和颜色。

六步创建流程

Step 1：理解技能——用具体例子建立共识

先搞清楚 Skill 要支持哪些场景。问用户（或问自己）：

• 这个技能应该支持什么功能？
• 能给一些使用这个技能的具体例子吗？
• 用户会说什么话来触发这个技能？

完成标志：对技能的功能范围有清晰认知。

Step 2：规划可复用的内容

对每个具体例子分析：

1. 从零开始做这件事，需要什么？
2. 其中哪些会被反复使用？

反复使用的东西 → 封装成 scripts/references/assets。

Step 3：初始化技能

使用脚本初始化目录结构，生成模板文件和 agents/openai.yaml。初始化是脆弱操作，用脚本消除出错可能。

Step 4：编辑技能

阶段一：先实现 scripts/references/assets 可复用资源。

阶段二：更新 SKILL.md：

• Frontmatter：描述技能做什么 + 具体什么时候用。所有 “when to use” 信息放这里。
• Body：写给 AI 的操作指令。统一使用祈使语气。只写 AI 不知道的程序性知识和领域细节。

Step 5：校验技能

运行校验脚本，检查 YAML frontmatter 格式、必需字段、命名规则。

Step 6：迭代

好的 Skill 不是一次写成的。在真实任务上使用，发现吃力的地方，找出 SKILL.md 或资源如何更新，实施变更后重新测试。

Skill 检查清单

以下清单可用于自查或交给 AI 自检：

结构与层级

• 所有 “when to use” 信息在 description 中，不在 body 中
• body 控制在 500 行以内，超出部分拆到 references
• 所有 references 从 SKILL.md 直接链接，无多层嵌套
• 信息不在 SKILL.md 和 references 之间重复
• 长 reference 文件（>100 行）顶部有目录

简洁

• 没有多余的辅助文档（README、CHANGELOG 等）
• 优先用具象示例代替冗长解释
• “不做什么”的约束多于”做什么”的泛泛描述
• 每句话都值得它占用的 token

自由度分配

• 确定性操作（格式、长度、命名）已封装为脚本
• 创造性判断留给文字指令引导
• 关键输出有校验脚本保障合规

指令质量

• 使用祈使语气（不定式）
• 判断条件明确（什么时候用 / 什么时候不用）
• 出错处理清晰（失败了怎么办、怎么回退）
• 有具体的正例和反例

实际验证

• 在真实场景中测试过
• 触发准确（不被误触发，不被漏触发）
• 输出质量稳定、可复现

总结

写出好 Skill 的本质可归纳为一句话：

用最少的 token，在正确的层级，给 AI 最精准的约束，让它在边界内自由发挥。

具体来说：

1. 简洁 — 只放 AI 不知道的内容，示例优于文字，”不做什么”优于”做什么”
2. 分层加载 — description 做过滤器，body 做操作手册，scripts/references 按需取用
3. 自由度光谱 — 脆弱操作脚本锁死，创造性工作文字引导
4. 六步流程 — 理解 → 规划 → 初始化 → 编辑 → 校验 → 迭代

Skill 不是写完就完事的文档，而是在实际使用中不断打磨出来的。每次使用后看看哪里吃力、哪里低效，在下一次迭代中改进。

参考链接

• How to Write a Good Skill — hello-agents
• 深度拆解 Claude 官方 Skills — 00’s Blog
• Anthropic Skills — 官方 Skill 集合
• Superpowers — 完整 Skill 开发方法论