简打卡
51.76M · 2026-03-28
如何设计一个高质量、生产可用的 Skill？
一个好的 Skill 不是随便写几个指令就完事了，它需要有清晰的结构、明确的边界、可复用的流程，甚至还要考虑 Token 消耗、版本管理等工程问题。
这篇文章要回答的核心问题是： 一个生产可用的 Skill 在结构上应该包含哪些部分？如何设计这些部分才能保证质量和可维护性？从 Prompt 到完整 Skill，需要经历哪些升级？
先看一张图，把一个完整 Skill 的核心组成部分说清楚：
Skill 核心三要素：
三层渐进式加载架构：
这两个概念是理解 Skill 设计的关键：「核心三要素」定义了 Skill 的内容结构，「三层渐进式加载架构」定义了 Skill 的加载机制。接下来我们逐一详解。
元数据是 Skill 的基础信息，相当于它的「身份证」。Agent 通过这些信息判断「是否应该调用这个 Skill」以及「如何调用」。
| 字段名 | 类型 | 必选 | 描述 | 示例 |
|---|---|---|---|---|
name | 字符串 | Skill 的唯一名称，用于识别和调用 | article-illustrator | |
description | 字符串 | Skill 的简短描述，说明它能做什么 | 自动为长文生成配图并插入到合适位置 | |
argument-hint | 字符串 | 提示用户如何提供参数 | 请提供需要配图的 Markdown 文档路径 | |
user-invocable | 布尔值 | 是否允许用户直接调用 | true | |
allowed-tools | 数组 | 允许使用的工具列表 | ["file.read", "image.generate"] | |
hooks | 对象 | 生命周期钩子，如 on_activate、on_completion | {"on_completion": "send_notification"} | |
dependencies | 数组 | 依赖的其他 Skill 或工具 | ["file-operations"] | |
version | 字符串 | Skill 的版本号，用于管理和兼容 | 1.0.0 |
---
name: article-illustrator
description: 自动为长文生成配图并插入到合适位置
argument-hint: 请提供需要配图的 Markdown 文档路径
user-invocable: true
allowed-tools:
- file.read
- file.write
- image.generate
version: 1.0.0
---
指令部分是 Skill 的核心，相当于它的「操作手册」。这部分需要写清楚：这个任务应该怎么做、注意什么、遇到问题怎么办。
## 操作流程
### 1. 结构化分析
- 通读全文，识别适合插入配图的位置（抽象概念、复杂流程、重点结论等）
- 为每个配图位置生成一个简短的描述，说明图片需要表达的内容
### 2. 风格自适应
- 根据文章的语义和情绪选择合适的画面风格：
- 出现「算法 / AI / 系统架构」等关键词 → Tech 风格
- 出现「情感 / 生活 / 个人成长」等关键词 → Warm 风格
- 出现「数据 / 图表 / 统计」等关键词 → Data 风格
### 3. 生成配图
- 调用 `image.generate` 工具，根据选定的风格和内容描述生成图片
- 每张图片生成 2-3 个版本，选择最符合文章风格的那个
### 4. 插入文档
- 将生成的图片路径以 Markdown 格式插入到文章对应位置
- 为每张图片添加合适的 alt 文本，确保可读性和无障碍体验
## 约束与注意事项
- 配图是为了帮助理解，不是单纯装饰页面
- 保持整篇文章的视觉风格一致
- 避免生成包含敏感内容的图片
- 如果生成失败，尝试调整提示词后重新生成
## 错误处理
- 如果找不到合适的配图位置，跳过配图步骤并告知用户
- 如果图片生成失败，记录错误信息并尝试使用备用风格
- 如果插入图片后文档格式出现问题，回滚操作并使用原文档
对于复杂任务，光有指令是不够的，还需要可执行的脚本和工具调用。这部分是 Skill 的「工具箱」，负责真正落地执行。
一个高质量的 Skill 不仅要内容好，还要「加载效率高」。这就用到了 三层渐进式加载架构 的设计理念——让 Agent 只在需要的时候加载需要的内容，避免一次性把所有信息都塞进上下文窗口。
为什么需要渐进式加载？
三层渐进式加载架构的具体实现:
skills 目录下创建 index.json 文件，包含所有 Skill 的元数据 {
"skills": [
{
"name": "article-illustrator",
"description": "自动为长文生成配图并插入到合适位置"
},
{
"name": "weather-checker",
"description": "获取指定城市的天气信息"
}
]
}
SKILL.md 文件SKILL.mdreferences 和 scripts 子目录SKILL.md 中通过相对路径引用这些文件 article-illustrator/
├── SKILL.md # 核心指令文件
├── references/ # 参考资料
│ ├── style-guide.md # 风格指南
│ └── examples/ # 示例
├── scripts/ # 脚本
│ ├── analyze.py # 文章分析脚本
│ └── generate_image.py # 图片生成脚本
└── index.json # 元数据索引
很多人一开始都是从写 Prompt 开始的，然后逐步升级到完整的 Skill。这个过程需要经历三个阶段：
特点：
示例：
你是一个配图专家，请为以下文章生成合适的配图：
[文章内容...]
要求：
1. 为每个重要段落生成一张配图
2. 风格要统一
3. 图片要与内容相关
特点：
示例：
---
name: simple-illustrator
description: 为文章生成配图
---
## 操作流程
1. 分析文章内容，识别重要段落
2. 为每个重要段落生成配图描述
3. 调用图片生成工具
4. 返回图片链接
## 要求
- 风格统一
- 与内容相关
- 避免敏感内容
特点：
目录结构示例：
article-illustrator/
├── SKILL.md # 主文件，包含元数据和指令
├── references/ # 参考资料
│ ├── style-guide.md # 风格指南
│ └── examples/ # 示例
├── scripts/ # 脚本
│ ├── analyze.py # 文章分析脚本
│ └── generate_image.py # 图片生成脚本
└── README.md # 说明文档
核心思想：用最少的 Token 做最多的事，避免不必要的信息加载。
通俗类比：就像写邮件一样，主题要明确，正文要简洁，附件只在需要时再打开。
实践建议：
SKILL.md 文件控制在 500 行以内，超过的内容拆到 references 目录反面例子：把所有内容都塞进一个超长的 SKILL.md 文件，导致每次加载都消耗大量 Token，响应缓慢。
核心思想：根据任务类型，合理设置模型的决策空间，既不过度约束，也不任由发挥。
通俗类比：就像给员工布置任务，创意类工作（如写广告语）需要更多自由，操作类工作（如填写表格）则需要更明确的步骤。
实践建议：
反面例子：给创意写作任务设置过于详细的步骤，或给数据处理任务只提供模糊的目标。
核心思想：信息披露要有层次感，从概览到细节，让模型按需获取信息。
通俗类比：就像查字典，先看目录找到大致位置，再翻到具体页码，最后查看详细解释。
实践建议：
反面例子：一次性把所有详细内容都塞进上下文窗口，或把关键约束隐藏在深层引用中。
核心思想：使用清晰、一致的命名和元数据，让模型和开发者都能快速理解 Skill 的用途。
通俗类比：就像给文件命名，"2024-01-01-项目方案.md" 比 "新建文档1.md" 更容易理解和查找。
实践建议：
article-illustrator，简洁明了自动为长文生成配图并插入到合适位置反面例子：使用模糊的名字如 skill1，或过于冗长的描述，让模型难以理解 Skill 的用途。
核心思想：在高风险场景中，强制模型先制定计划，验证可行性，再执行操作。
通俗类比：就像做实验一样，先设计实验方案，检查设备和材料，再进行实际操作。
实践建议：
反面例子：直接让模型执行高风险操作（如删除文件、调用外部 API），没有任何验证步骤。
核心思想：明确 Skill 的边界和错误处理策略，让模型知道"什么能做、什么不能做、遇到问题怎么办"。
通俗类比：就像产品说明书一样，不仅要说明如何使用，还要说明不能做什么，以及出现故障时如何处理。
实践建议：
反面例子：只说明"要做什么"，不说明"不能做什么"或"遇到问题怎么办"，导致模型在边界情况下不知所措。
核心思想：设计 Skill 时，考虑不同大小、不同能力模型的兼容性，确保在各种环境下都能正常工作。
通俗类比：就像开发软件一样，不仅要在高端设备上测试，还要在中低端设备上验证兼容性。
实践建议：
反面例子：只在大模型上测试 Skill，忽略了小模型的理解能力限制，导致在资源受限的环境中表现差。
| 坑 | 症状 | 避坑指南 |
|---|---|---|
| 时间敏感信息写死 | Skill 过一段时间就失效 | 使用动态变量，如 ${CURRENT_DATE} |
| Windows 路径问题 | 在不同系统上运行失败 | 使用相对路径，避免硬编码绝对路径 |
| 无目录的长文参考 | 内容混乱，难以维护 | 使用 references 目录组织内容 |
| 未跨模型做回归测试 | 在小模型上表现差 | 同时测试大模型和小模型 |
| 过度嵌套引用 | 加载缓慢，容易出错 | 引用层级控制在 1 层以内 |
| 一次性塞满所有内容 | Token 消耗高，响应慢 | 使用渐进式加载，按需读取 |
| 在 reference 里写关键约束 | 模型可能忽略约束 | 关键约束写在主 SKILL.md 中 |
设计一个生产可用的 Skill，需要从「结构」和「加载机制」两个维度入手：
结构上：使用「核心三要素」——Schema/Metadata 定义身份，Instructions/SOP 定义流程，Executable/Scripts/Tools 定义执行能力。
加载机制上：使用「三层渐进式加载架构」——元数据层（启动时加载）、SKILL.md 层（触发时加载）、references/scripts 层（需要时加载），实现渐进式加载，节省 Token。
工程实践上：遵循 7 大设计原则，避免常见坑，从简单的 Prompt 逐步升级到完整的 Skill。
决策路径：
一个高质量的 Skill 不是一蹴而就的，而是需要不断迭代和优化的。但只要掌握了「核心三要素」和「三层渐进式加载架构」的设计理念，你就能构建出真正生产可用的 Skills，让 Agent 成为你的得力助手。
下一篇我们会聊：从 0 到 1 做几个能真用的 Skills，通过具体案例带你实战演练 Skill 的开发全流程。
