Agent Skills 设计详解：大模型开发中的可复用指令封装

---
name: ai-proofreading
description: 系统化降低 AI 检测率，增加人味。使用场景：审校文章、降低 AI 味、初稿完成后。
---

第二层：指令（Instructions）—— 触发时加载

• 内容：SKILL.md 的主体部分，详细的操作指南。
• 加载时机：当用户请求匹配某个 Skill 的 description 时，OpenCode 才加载这个 Skill 的完整内容。
• Token 成本：通常在 3000-5000 tokens。
• 作用：告诉 Claude 具体怎么做。

第三层：资源（Resources）—— 引用时加载

• 内容：scripts/ 目录里的脚本、references/ 目录里的参考文档、assets/ 目录里的模板。
• 加载时机：只有当 SKILL.md 中的指令引用这些文件时才加载。
• Token 成本：几乎无限——脚本执行后只有输出进入上下文，代码本身不占 Token。
• 作用：提供确定性的执行能力和详细的参考资料。

这一设计非常聪明。传统方式将所有规则写在一个文件中，每次对话都加载，若有 3000 多行内容，大约消耗 4 万 tokens。而 Skills 方式平时只加载元数据，需要时额外加载对应 Skill，一次对话通常只用 1-2 个 Skills，总共约 1 万 tokens，节省了 75% 的 Token 消耗。

此外，脚本的魔法在于它可以封装确定性的执行能力。比如图片上传 Skill 里有一个 Python 脚本，负责把图片上传到图床。当 OpenCode 执行这个脚本时，它会生成一条 bash 命令，脚本在本地执行，只有执行结果（图床 URL）返回给 OpenCode。脚本代码本身不进入上下文，所以你可以写一个 500 行的 Python 脚本，处理各种边界情况、错误处理、日志记录，OpenCode 只需要知道'执行这个脚本'，不需要理解每一行代码。

如何创建与规范

创建的方法主要有两种：

1. 直接手动编写，不推荐，因为费时费力，质量因人而异波动较大；
2. 利用 OpenCode，借助官方开源的 skill-creator 创建。例如直接告诉 OpenCode：'帮我创建一个 Skill，用来审校学术论文初稿。要检查事实准确性、去掉 AI 味、控制句子长度、像学术用语'。它会帮你生成符合格式的文件。

无论采用哪种方式，你在创建 Skills 之前都需要明确以下几点：

1. 想清楚要解决什么问题？这个问题是不是重复性的？有没有必要写 Skills。
2. 把工作流程写清楚。
3. 提供足够的 context 和参考资料。

基本结构

一个 Skill 就是一个文件夹，里面至少有一个 SKILL.md 文件，且文件夹的命名要与 SKILL.md 中 YAML Frontmatter 的 name 字段完全一致。

关键内容

每个 SKILL.md 文件都由两部分组成：YAML Frontmatter 和 Markdown 正文。

YAML Frontmatter

Frontmatter 位于文件的最顶端，使用 --- 分隔，用于定义 Skill 的元数据。Agent 正是通过这些元数据来发现和理解 Skill 的用途。一个合法的 SKILL.md 文件必须包含 name 和 description 两个字段。

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

在上面的例子中，name 和 description 是必填项，它们直接影响 Agent 如何识别和选择 Skill。而 license、compatibility 和 metadata 等字段是可选的，用于提供额外的信息。

name 字段的值必须符合特定的命名规范：

• 长度在 1 到 64 个字符之间。
• 只能包含小写字母、数字和单个连字符 -。
• 不能以连字符开头或结尾。
• 不能包含连续的连字符。
• 最重要的一点是，它必须与存放 SKILL.md 文件的目录名完全相同。

description 字段作用是向 Agent 清晰地描述这个 Skill 的功能，以便 Agent 在众多可用 Skill 中做出正确的选择：

• 长度限制在 1 到 1024 个字符之间。
• 描述应该具体、明确，准确传达 Skill 的核心用途。
• 触发关键词很重要。

Markdown 正文

文件的正文部分则使用标准的 Markdown 语法，详细说明 Skill 的使用场景、核心目标、执行逻辑、示例输入/输出及注意事项等。建议控制在 500 行以内，如需更多内容，放到 references/目录下。

这部分内容类似 Prompt 的设计规则。它是 Agent 加载 Skill 后获取的核心指令，因此编写得越清晰，Agent 的执行效果就越好。

案例拆解：skill-creator

为了更深入理解，我们以官方公布的经过充分测试的 skill-creator 为例进行拆解。这是一个元技能（meta-skill），专门指导如何创建其他技能。它将 Claude 从通用人工智能代理转变为具备特定领域专业知识的专业代理。

核心功能

1. 提供 Skills 创建的工作流程和最佳实践。
2. 定义 Skills 的结构和组成要素。
3. 实施渐进式披露设计原则以优化上下文使用。
4. 包含工具脚本和模板文件。
5. 提供验证和打包功能。

设计原则

• 简洁性原则：上下文窗口是公共资源，Skills 应该只添加 Claude 真正需要的信息。每个信息片段都需要评估其 token 成本是否合理。技能设计应偏好简洁的示例而非冗长的解释。
• 适当的自由度：根据任务的脆弱性和可变性设置不同级别的自由度。高自由度基于文本指令，中自由度带参数伪代码，低自由度则是特定脚本，一致性至关重要。
• 渐进式披露：采用三级加载系统管理上下文效率，确保只在必要时加载详细内容。

结构分析

• SKILL.md（必需）：包含前导码（YAML）和正文（Markdown）。前导码是触发机制，正文仅在触发后加载。
• 捆绑资源（可选）：
  • scripts/：可执行代码，用于需要确定性可靠性的任务。
  • references/：文档和参考材料，根据需要加载。
  • assets/：输出中使用的文件，如模板、图标，不加载到上下文中。

创建流程

skill-creator 定义了六个步骤的 Skills 创建流程：

1. 通过具体示例理解 Skills：明确支持的功能和使用场景。
2. 规划可重用 Skills 内容：识别重复性工作，规划资源。
3. 初始化 Skills：运行 init_skill.py 脚本创建目录结构和模板。
4. 编辑 Skills：实现资源，更新 SKILL.md，遵循最佳实践。
5. 打包 Skills：运行 package_skill.py 脚本验证并创建可分发的 .skill 文件。
6. 迭代优化：基于反馈持续改进。

最佳实践

• 文件组织：避免深度嵌套引用，参考文件直接从 SKILL.md 链接；结构化长文件，顶部包含目录；避免信息重复。
• 写作指南：使用命令式/不定式形式，保持简洁。前导码 description 字段应包含'何时使用'的信息，正文中不应重复此部分。

该技能体现了软件工程的最佳实践，包括关注点分离、渐进式披露、资源优化和迭代开发，为创建高质量、可维护的技能提供了完整解决方案。