Agent Skills 设计详解

（3）"自动加载"：你不需要手动告诉 Claude/OpenCode "现在用 XX Skill"。Claude/OpenCode 会根据你的任务描述，自动判断需要哪个 Skill，然后加载。

（4）渐进式披露：分阶段、按需加载。一个 Skill 包含很多内容：核心指令、参考文档、执行脚本、模板资源。但 Claude/OpenCode 等不会一次性把所有内容都加载进上下文。它采用三层加载机制：

第一层：元数据（Metadata）—— 总是加载

• 内容：SKILL.md 文件开头的 YAML 部分，就两个字段：name 和 description。
• 加载时机：opencode 启动时就加载所有 Skills 的元数据。
• Token 成本：每个 Skill 大约 100 tokens。就算装 50 个 Skills，也就 5000 tokens。
• 作用：让 opencode 知道有哪些 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。
• 作用：提供确定性的执行能力和详细的参考资料。

这一设计非常聪明。

传统方式：所有规则写在一个 xx.md 文件中，每次对话都加载，若有 3000 多行内容，大约 4 万 tokens。每次对话都烧 40000 tokens，不管需不需要。

Skills 方式：

• 平时只加载元数据：50 个 Skills × 100 tokens = 5000 tokens
• 需要审校时，额外加载审校 Skill：+3000 tokens
• 需要配图时，额外加载配图 Skill：+2000 tokens
• 一次对话通常只用 1-2 个 Skills：总共约 10000 tokens

**节省了 75% 的 Token 消耗。**而且，这还没算脚本的优势。

脚本的魔法

Skills 可以包含可执行脚本。比如我的"图片配图与上传"Skill 里有一个 Python 脚本，负责把图片上传到图床。

当 Opencode 执行这个脚本时：

1. opencode 生成一条 bash 命令：python scripts/upload_image.py image.png
2. 脚本在本地执行
3. 只有执行结果（图床 URL）返回给 opencode

脚本代码本身不进入上下文。

所以你可以写一个 500 行的 Python 脚本，处理各种边界情况、错误处理、日志记录。opencode 只需要知道"执行这个脚本"，不需要理解每一行代码。

这是 Skills 比传统 Prompt 方式更强的地方：可以封装确定性的执行能力。

3.2 如何创建

创建的方法主要有两种：

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

但是，无论采用哪种方式，你在创建 skills 之前都需要明确以下几点内容，这是前提：

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

3.3 基本结构

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

3.4 关键内容

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

3.4.1 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 --- ## What I do - Draft release notes from merged PRs - Propose a version bump - Provide a copy-pasteable `gh release create` command ## When to use me Use this when you are preparing a tagged release. Ask clarifying questions if the target versioning scheme is unclear.

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

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

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

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

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

3.4.2 Markdown 正文

文件的正文部分则使用标准的 Markdown 语法，详细说明 Skill 的：

• 使用场景
• 核心目标
• 执行逻辑
• 示例输入/输出
• 注意事项等

建议控制在 500 行以内，如需更多内容，放到 references/目录下。

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

四、Skills 案例拆解

为了更好的理解 skills，就以官方 anthropics 公布的、经过充分测试的其中一个 skills（skill-creator）进行详细的拆解，便拆解、边理解 skills 的构建：

4.1 skill-creator 概述

skill-creator 是一个元技能（meta-skill），专门指导如何创建其他技能。它将 Claude 从通用人工智能代理转变为具备特定领域专业知识的专业代理。该技能提供了完整的技能创建框架、设计原则和实践指南，是 opencode 技能系统的核心组成部分。

技能的主要功能包括：

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

4.2 核心设计原则

4.2.1 简洁性原则

上下文窗口是公共资源，skills 应该只添加 claude 真正需要的信息。每个信息片段都需要评估其 token 成本是否合理。技能设计应偏好简洁的示例而非冗长的解释。

4.2.2 适当的自由度

根据任务的脆弱性和可变性设置不同级别的自由度：

• 高自由度（基于文本的指令）：多种方法有效，决策依赖上下文
• 中自由度（带参数的伪代码或脚本）：存在首选模式，允许一定变化
• 低自由度（特定脚本，少量参数）：操作脆弱易错，一致性至关重要

4.2.3 渐进式披露

采用三级加载系统管理上下文效率：

1. 元数据（名称 + 描述）：始终在上下文中（约 100 词）
2. SKILL.md 正文：技能触发时加载（<5000 词）
3. 捆绑资源：根据需要加载（无限，因为脚本可不读入上下文）

4.3 技能结构分析

4.3.1 SKILL.md（必需文件）

每个技能必须包含 SKILL.md 文件，由两部分组成：

• 前导码（YAML）：包含 name 和 description 字段，是技能触发的主要机制
• 正文（Markdown）：技能的使用说明和指南，仅在技能触发后加载

4.3.2 捆绑资源（可选）

技能可以包含三种类型的捆绑资源：

4.4 渐进式披露设计

渐进式披露是 skill-creator 的核心设计原则，通过三级加载系统优化上下文使用效率：

4.4.1 三级加载系统

1. 第一级：元数据（名称 + 描述） - 始终保持在上下文中，约 100 词，用于技能触发判断
2. 第二级：SKILL.md 正文 - 仅在技能触发后加载，限制在 5000 词以内，包含核心工作流程
3. 第三级：捆绑资源 - 根据任务需要按需加载，脚本可直接执行而不读入上下文

4.4.2 设计模式

skill-creator 提供了三种主要的渐进式披露模式：

• 高级指南与参考文件模式：在 SKILL.md 中提供核心工作流程，详细内容放在参考文件中
• 特定领域组织模式：按领域组织内容，避免加载不相关上下文
• 条件详细信息模式：显示基本内容，链接到高级内容，按需加载

4.5 技能创建流程

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

步骤 1：通过具体示例理解 skills

通过用户示例或生成并验证的示例，明确 skills 应支持的功能和使用场景。

步骤 2：规划可重用 skills 内容

分析每个示例，识别重复性工作，规划 scripts、references 和 assets 资源。

步骤 3：初始化 skills

运行 init_skill.py 脚本创建 skills 目录结构，生成模板文件。

步骤 4：编辑 skills

实现规划的资源，更新 SKILL.md 文件，遵循设计模式和最佳实践。

步骤 5：打包 skills

运行 package_skill.py 脚本进行验证并创建可分发的 .skill 文件。

步骤 6：迭代优化

基于实际使用反馈，持续改进 skills 内容和设计。

4.6 设计模式与最佳实践

4.6.1 技能文件组织

关键组织原则：

• 避免深度嵌套引用：参考文件应直接从 SKILL.md 链接，保持一级深度
• 结构化长文件：超过 100 行的文件应在顶部包含目录
• 避免重复：信息应位于 SKILL.md 或参考文件中，不能同时存在

4.6.2 写作指南

技能文档应使用命令式/不定式形式，保持简洁直接：

• 前导码 description 字段应包含所有'何时使用此技能'的信息
• 正文中不应包含'何时使用'部分，因为仅在触发后加载
• 避免使用不必要的辅助文档文件（README.md、CHANGELOG.md 等）

4.7 总结

skill-creator 技能提供了一个系统化、可扩展的技能创建框架，具有以下核心价值：

• 模块化设计：通过渐进式披露优化上下文使用效率
• 标准化流程：六步创建流程确保技能质量一致性
• 资源重用：scripts、references、assets 资源减少重复工作
• 质量控制：验证和打包脚本确保技能符合标准

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