一、什么是 Agent Skills
在与 AI Agent 协作开发时，我们常常希望它能遵循一些特定的、可复用的操作流程，比如按照固定格式创建 Git Release、执行项目代码检查、或是生成符合团队规范的文档。OpenCode Agent Skill 提供了一种机制，允许我们将这些可复用的指令和行为封装起来，供 Agent 在需要时发现并调用。
一个 Skill 本质上是一份包含了特定指令的 Markdown 文件，它定义了一项任务的名称、描述以及具体的执行步骤。通过这种方式，我们可以将复杂的、重复性的工作流程标准化，让 Agent 能够像调用工具一样，精确、一致地执行这些预定义的任务。这不仅提升了协作效率，也确保了输出结果的规范性。
总而言之，Skills 的核心价值在于：把重复的指令打包，按需加载。
二、OpenCode 配置 Skill
创建一个 Skill 的过程非常直接，核心是在指定的目录中放置一个名为 SKILL.md 的文件。
OpenCode 会在特定路径下搜索 SKILL.md 文件。这些路径分为项目本地和全局两种，方便我们将 Skill 应用于特定项目或是在所有项目中共享。
项目本地路径允许我们将 Skill 与代码仓库绑定在一起，当其他开发者克隆项目后，也能立即使用这些为项目定制的 Skill。OpenCode 会从当前工作目录向上搜索，直到 Git 仓库的根目录，并加载所有符合以下模式的 Skill 文件：
.opencode/skill/<skill-name>/SKILL.md.claude/skills/<skill-name>/SKILL.md
全局路径则用于存放那些通用的、与具体项目无关的 Skill。这些 Skill 定义在用户的主目录下，对所有项目都可见（Windows 下全局路径实测下来为：C:\Users\用户名\.config\opencode\skills）：
~/.config/opencode/skill/<skill-name>/SKILL.md~/.claude/skills/<skill-name>/SKILL.md~/.agents/skills/<skill-name>/SKILL.md
这里的 <skill-name> 是一个目录名，它必须与 Skill 本身的名称保持一致。这种目录结构使得每个 Skill 的定义都清晰地隔离在自己的文件夹内。
三、Skills 内容设计
3.1 核心概念
几个关键词需要解释：
（1）"模块化"：Skills 是一个个独立的文件夹，每个 Skill 做一件事。比如"生成 PPT"是一个 Skill，"审校文章"是另一个 Skill。
（2）"能力包"：每个 Skill 文件夹里可以包含：
- SKILL.md（核心指令文件，必需。）
- scripts/（可执行脚本，可选。当 SKILL.md 中引用脚本时，opencode 会执行它。脚本代码不进入上下文，只有执行结果进入。这意味着可以写复杂脚本处理确定性任务，而不占 Token。）
- references/（参考文档，可选。当任务需要更多信息时，opencode 会读取这些文档。采用渐进式披露，平时不加载。）
- assets/（模板和资源，可选。比如报告模板、配置文件、样例数据。）
（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 执行这个脚本时：
- opencode 生成一条 bash 命令：python scripts/upload_image.py image.png
- 脚本在本地执行
- 只有执行结果（图床 URL）返回给 opencode
脚本代码本身不进入上下文。
所以你可以写一个 500 行的 Python 脚本，处理各种边界情况、错误处理、日志记录。opencode 只需要知道"执行这个脚本"，不需要理解每一行代码。
这是 Skills 比传统 Prompt 方式更强的地方：可以封装确定性的执行能力。
3.2 如何创建
创建的方法主要有两种：
- 直接手撸，不推荐，因为费时费力，质量因人而异波动较大；
- 利用 opencode，借助官方开源的 skill（skill-creator）创建。（例如：直接告诉 opencode："帮我创建一个 Skill，用来审校学术论文初稿。要检查事实准确性、去掉 AI 味、控制句子长度、像学术用语"。它会帮你生成符合格式的文件，生成的过程及结果如下：）
但是，无论采用哪种方式，你在创建 skills 之前都需要明确以下几点内容，这是前提：
- 想清楚要解决什么问题？这个问题是不是重复性的？有没有必要写 skills
- 把工作流程写清楚
- 提供足够的 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 技能系统的核心组成部分。
技能的主要功能包括：
- 提供 skills 创建的工作流程和最佳实践
- 定义 skills 的结构和组成要素
- 实施渐进式披露设计原则以优化上下文使用
- 包含工具脚本和模板文件
- 提供验证和打包功能
4.2 核心设计原则
4.2.1 简洁性原则
上下文窗口是公共资源，skills 应该只添加 claude 真正需要的信息。每个信息片段都需要评估其 token 成本是否合理。技能设计应偏好简洁的示例而非冗长的解释。
4.2.2 适当的自由度
根据任务的脆弱性和可变性设置不同级别的自由度：
- 高自由度（基于文本的指令）：多种方法有效，决策依赖上下文
- 中自由度（带参数的伪代码或脚本）：存在首选模式，允许一定变化
- 低自由度（特定脚本，少量参数）：操作脆弱易错，一致性至关重要
4.2.3 渐进式披露
采用三级加载系统管理上下文效率：
- 元数据（名称 + 描述）：始终在上下文中（约 100 词）
- SKILL.md 正文：技能触发时加载（<5000 词）
- 捆绑资源：根据需要加载（无限，因为脚本可不读入上下文）
4.3 技能结构分析
4.3.1 SKILL.md（必需文件）
每个技能必须包含 SKILL.md 文件，由两部分组成：
- 前导码（YAML）：包含 name 和 description 字段，是技能触发的主要机制
- 正文（Markdown）：技能的使用说明和指南，仅在技能触发后加载
4.3.2 捆绑资源（可选）
技能可以包含三种类型的捆绑资源：
| 资源类型 | 描述与用途 |
|---|---|
| scripts/ | 可执行代码（Python/Bash 等），用于需要确定性可靠性或重复编写的任务 |
| references/ | 文档和参考材料，根据需要加载到上下文中，如数据库模式、API 文档、公司政策等 |
| assets/ | 输出中使用的文件（模板、图标、字体、示例文档等），不加载到上下文中 |
4.4 渐进式披露设计
渐进式披露是 skill-creator 的核心设计原则，通过三级加载系统优化上下文使用效率：
4.4.1 三级加载系统
- 第一级：元数据（名称 + 描述） - 始终保持在上下文中，约 100 词，用于技能触发判断
- 第二级：SKILL.md 正文 - 仅在技能触发后加载，限制在 5000 词以内，包含核心工作流程
- 第三级：捆绑资源 - 根据任务需要按需加载，脚本可直接执行而不读入上下文
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 资源减少重复工作
- 质量控制：验证和打包脚本确保技能符合标准
该技能体现了软件工程的最佳实践，包括关注点分离、渐进式披露、资源优化和迭代开发，为创建高质量、可维护的技能提供了完整解决方案。
