Skill 的核心要素与渐进式加载架构——如何设计一个生产可用的 Skill？

面对一个新项目，你可能会问：一个可以上生产的 Skill，结构上应该长什么样？需要哪些「硬性要素」？

一、导读

如何设计一个高质量、生产可用的 Skill？

一个好的 Skill 不是随便写几个指令就完事了，它需要有清晰的结构、明确的边界、可复用的流程，甚至还要考虑 Token 消耗、版本管理等工程问题。

这篇文章要回答的核心问题是：一个生产可用的 Skill 在结构上应该包含哪些部分？如何设计这些部分才能保证质量和可维护性？从 Prompt 到完整 Skill，需要经历哪些升级？

二、一张图看懂：生产可用的 Skill 长什么样？

先看一张图，把一个完整 Skill 的核心组成部分说清楚：

Skill 核心三要素：
- Schema / Metadata：Skill 的「身份证」，包含名字、描述、触发词、权限等元数据。
- Instructions / SOP：Skill 的「操作手册」，包含步骤拆解、约束、错误处理等。
- Executable / Scripts / Tools：Skill 的「工具箱」，包含真正干活的代码和工具调用。
三层渐进式加载架构：
- 元数据层（几十 Token）：只告诉 Agent「有啥」，启动时加载。
- SKILL.md 层（几百 Token）：告诉 Agent「怎么用」，触发时加载。
- references / scripts 层（几千 Token）：在真正需要时加载，包含详细逻辑和代码。

这两个概念是理解 Skill 设计的关键：「核心三要素」定义了 Skill 的内容结构，「三层渐进式加载架构」定义了 Skill 的加载机制。接下来我们逐一详解。

三、Skill 核心三要素详解

3.1 Schema / Metadata：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`

元数据示例

yaml 复制代码

---
name: article-illustrator
description: 自动为长文生成配图并插入到合适位置
argument-hint: 请提供需要配图的 Markdown 文档路径
user-invocable: true
allowed-tools:
  - file.read
  - file.write
  - image.generate
version: 1.0.0
---

3.2 Instructions / SOP：Skill 的「操作手册」

指令部分是 Skill 的核心，相当于它的「操作手册」。这部分需要写清楚：这个任务应该怎么做、注意什么、遇到问题怎么办。

编写原则

清晰明确：每一步都要具体可操作，避免模糊的描述。
有边界：明确说明「什么能做、什么不能做」，避免模型「瞎发挥」。
可复用：流程应该标准化，能适用于不同的具体场景。
错误处理：说明遇到常见问题时应该如何处理。

指令结构示例

markdown 复制代码

## 操作流程

### 1. 结构化分析
- 通读全文，识别适合插入配图的位置（抽象概念、复杂流程、重点结论等）
- 为每个配图位置生成一个简短的描述，说明图片需要表达的内容

### 2. 风格自适应
- 根据文章的语义和情绪选择合适的画面风格：
  - 出现「算法 / AI / 系统架构」等关键词 → Tech 风格
  - 出现「情感 / 生活 / 个人成长」等关键词 → Warm 风格
  - 出现「数据 / 图表 / 统计」等关键词 → Data 风格

### 3. 生成配图
- 调用 `image.generate` 工具，根据选定的风格和内容描述生成图片
- 每张图片生成 2-3 个版本，选择最符合文章风格的那个

### 4. 插入文档
- 将生成的图片路径以 Markdown 格式插入到文章对应位置
- 为每张图片添加合适的 alt 文本，确保可读性和无障碍体验

## 约束与注意事项

- 配图是为了帮助理解，不是单纯装饰页面
- 保持整篇文章的视觉风格一致
- 避免生成包含敏感内容的图片
- 如果生成失败，尝试调整提示词后重新生成

## 错误处理

- 如果找不到合适的配图位置，跳过配图步骤并告知用户
- 如果图片生成失败，记录错误信息并尝试使用备用风格
- 如果插入图片后文档格式出现问题，回滚操作并使用原文档

3.3 Executable / Scripts / Tools：Skill 的「工具箱」

对于复杂任务，光有指令是不够的，还需要可执行的脚本和工具调用。这部分是 Skill 的「工具箱」，负责真正落地执行。

常见脚本类型

Python 脚本：处理数据、调用 API、执行复杂逻辑
Bash 脚本：文件操作、系统命令、自动化流程
配置文件：存储模板、参数、常量等

四、三层渐进式加载架构：渐进式加载的艺术

一个高质量的 Skill 不仅要内容好，还要「加载效率高」。这就用到了 三层渐进式加载架构 的设计理念------让 Agent 只在需要的时候加载需要的内容，避免一次性把所有信息都塞进上下文窗口。

为什么需要渐进式加载？

节省 Token：避免加载不需要的内容，降低成本
提高速度：启动时只加载轻量信息，响应更快
扩展性好：可以挂很多 Skills，而不会挤爆上下文窗口

三层渐进式加载架构的具体实现:

4.1. 元数据层（几十 Token）

内容：只包含 Skill 的名字和简短描述
加载时机：Agent 启动时
作用：让 Agent 知道「有哪些 Skill 可用」
技术实现 ：
- 在 skills 目录下创建 index.json 文件，包含所有 Skill 的元数据
- Agent 启动时只读取此文件，不加载具体 Skill 内容
- 示例：

json 复制代码

    {
      "skills": [
        {
          "name": "article-illustrator",
          "description": "自动为长文生成配图并插入到合适位置"
        },
        {
          "name": "weather-checker",
          "description": "获取指定城市的天气信息"
        }
      ]
    }

4.2. SKILL.md 层（几百 Token）

内容：包含元数据、核心指令、基本流程
加载时机：当 Agent 认为需要使用该 Skill 时
作用：让 Agent 知道「这个 Skill 怎么用」
技术实现 ：
- 每个 Skill 目录下必须包含 SKILL.md 文件
- Agent 根据用户请求或任务需求，动态加载对应 Skill 的 SKILL.md
- 加载触发机制：当用户输入包含 Skill 相关关键词，或 Agent 分析任务需要特定 Skill 时

4.3. references / scripts 层（几千 Token）

内容：包含详细逻辑、代码、模板、示例等
加载时机：当 Agent 执行具体步骤需要时
作用：让 Agent 能「真正把事情做好」
技术实现 ：
- 在 Skill 目录下创建 references 和 scripts 子目录
- SKILL.md 中通过相对路径引用这些文件
- 只有当 Agent 执行到需要具体代码或模板的步骤时，才加载对应文件
- 文件结构示例：

bash 复制代码

    article-illustrator/
    ├── SKILL.md              # 核心指令文件
    ├── references/           # 参考资料
    │   ├── style-guide.md    # 风格指南
    │   └── examples/         # 示例
    ├── scripts/              # 脚本
    │   ├── analyze.py        # 文章分析脚本
    │   └── generate_image.py # 图片生成脚本
    └── index.json            # 元数据索引

五、从 Prompt 到 Skill 的三个升级

很多人一开始都是从写 Prompt 开始的，然后逐步升级到完整的 Skill。这个过程需要经历三个阶段：

5.1 阶段一：一次性 Prompt

特点：

只是一段自然语言描述
一次性使用，不可复用
没有结构，全靠模型理解

示例：

markdown 复制代码

你是一个配图专家，请为以下文章生成合适的配图：

[文章内容...]

要求：
1. 为每个重要段落生成一张配图
2. 风格要统一
3. 图片要与内容相关

5.2 阶段二：可复用的 SKILL.md

特点：

结构化的 Markdown 文档
包含元数据和指令
可复用，可维护

示例：

yaml 复制代码

---
name: simple-illustrator
description: 为文章生成配图
---

## 操作流程
1. 分析文章内容，识别重要段落
2. 为每个重要段落生成配图描述
3. 调用图片生成工具
4. 返回图片链接

## 要求
- 风格统一
- 与内容相关
- 避免敏感内容

5.3 阶段三：完整 Skill

特点：

包含「核心三要素」完整结构
有脚本和工具调用能力
支持渐进式加载
工程化管理

目录结构示例：

bash 复制代码

article-illustrator/
├── SKILL.md          # 主文件，包含元数据和指令
├── references/       # 参考资料
│   ├── style-guide.md    # 风格指南
│   └── examples/         # 示例
├── scripts/          # 脚本
│   ├── analyze.py        # 文章分析脚本
│   └── generate_image.py # 图片生成脚本
└── README.md         # 说明文档

5.4 升级过程中的关键决策

何时拆分成脚本：当逻辑复杂、需要重复执行、涉及外部 API 调用时
何时使用引用文件：当内容过多、需要分类管理、只在特定场景使用时
如何设计接口：保持参数简洁，使用默认值，提供清晰的错误处理
如何管理版本：使用语义化版本号，记录变更日志，考虑向后兼容

六、7 大设计原则

1. 极简与 Token 经济学

核心思想：用最少的 Token 做最多的事，避免不必要的信息加载。

通俗类比：就像写邮件一样，主题要明确，正文要简洁，附件只在需要时再打开。

实践建议：

主 SKILL.md 文件控制在 500 行以内，超过的内容拆到 references 目录
引用层级控制在 1 层以内，避免 "引用套引用" 的复杂结构
只在真正需要时才加载详细内容，如复杂的代码示例或模板

反面例子 ：把所有内容都塞进一个超长的 SKILL.md 文件，导致每次加载都消耗大量 Token，响应缓慢。

2. 自由度控制

核心思想：根据任务类型，合理设置模型的决策空间，既不过度约束，也不任由发挥。

通俗类比：就像给员工布置任务，创意类工作（如写广告语）需要更多自由，操作类工作（如填写表格）则需要更明确的步骤。

实践建议：

高自由度（创意生成、头脑风暴）：只给方向和目标，不限制具体实现方式
中自由度（文档撰写、代码审查）：提供结构和关键要求，允许在细节上发挥
低自由度（数据处理、合规检查）：提供明确的步骤和判断标准，严格约束输出格式

反面例子：给创意写作任务设置过于详细的步骤，或给数据处理任务只提供模糊的目标。

3. 渐进式披露的正确姿势

核心思想：信息披露要有层次感，从概览到细节，让模型按需获取信息。

通俗类比：就像查字典，先看目录找到大致位置，再翻到具体页码，最后查看详细解释。

实践建议：

第一层（元数据）：只包含名字和简介，启动时加载
第二层（SKILL.md）：包含核心指令和流程，触发时加载
第三层（references）：包含详细逻辑和代码，需要时加载

反面例子：一次性把所有详细内容都塞进上下文窗口，或把关键约束隐藏在深层引用中。

4. 命名与元数据规范

核心思想：使用清晰、一致的命名和元数据，让模型和开发者都能快速理解 Skill 的用途。

通俗类比：就像给文件命名，"2024-01-01-项目方案.md" 比 "新建文档1.md" 更容易理解和查找。

实践建议：

name ：使用小写字母+连字符的格式，如 article-illustrator，简洁明了
description ：用一句话说清楚能做什么，如 自动为长文生成配图并插入到合适位置
触发词：在 description 中包含常见的相关词汇，便于模型识别和路由

反面例子 ：使用模糊的名字如 skill1，或过于冗长的描述，让模型难以理解 Skill 的用途。

5. PVE（Plan--Validate--Execute）实践

核心思想：在高风险场景中，强制模型先制定计划，验证可行性，再执行操作。

通俗类比：就像做实验一样，先设计实验方案，检查设备和材料，再进行实际操作。

实践建议：

Plan（规划）：让模型先输出执行计划，包括步骤、工具和预期结果
Validate（验证）：检查计划的可行性、安全性和正确性
Execute（执行）：按照验证后的计划执行操作，并监控结果

反面例子：直接让模型执行高风险操作（如删除文件、调用外部 API），没有任何验证步骤。

6. 错误处理与边界情况

核心思想：明确 Skill 的边界和错误处理策略，让模型知道"什么能做、什么不能做、遇到问题怎么办"。

通俗类比：就像产品说明书一样，不仅要说明如何使用，还要说明不能做什么，以及出现故障时如何处理。

实践建议：

明确边界：在指令中清楚说明任务的范围和限制
优雅降级：当遇到错误时，提供备用方案，如"如果 API 调用失败，尝试使用本地缓存数据"
日志记录：记录关键步骤和错误信息，便于后续分析和优化

反面例子：只说明"要做什么"，不说明"不能做什么"或"遇到问题怎么办"，导致模型在边界情况下不知所措。

7. 跨模型兼容性

核心思想：设计 Skill 时，考虑不同大小、不同能力模型的兼容性，确保在各种环境下都能正常工作。

通俗类比：就像开发软件一样，不仅要在高端设备上测试，还要在中低端设备上验证兼容性。

实践建议：

避免模型特定特性：不使用只在特定模型上可用的功能
测试不同大小的模型：同时在大模型（如 Claude 3 Opus）和小模型（如 Claude 3 Haiku）上测试
考虑小模型的理解能力：使用更简单、更直接的语言描述复杂概念

反面例子：只在大模型上测试 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 的「核心三要素」内容
再想加载：设计好「三层渐进式加载架构」的拆分方式
后做实现：从 Prompt 开始，逐步添加脚本和引用
持续优化：根据使用情况调整结构和加载策略

一个高质量的 Skill 不是一蹴而就的，而是需要不断迭代和优化的。但只要掌握了「核心三要素」和「三层渐进式加载架构」的设计理念，你就能构建出真正生产可用的 Skills，让 Agent 成为你的得力助手。

参考资源

Anthropic Skills 官方仓库 ：https://github.com/anthropics/skills
Agent Skills 官方标准 ：https://agentskills.io

下一篇我们会聊：从 0 到 1 做几个能真用的 Skills，通过具体案例带你实战演练 Skill 的开发全流程。