一、什么是 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 内容设计
下面我解释一下 Skill 的结构，目的是让你理解逻辑，知道该给 AI 提什么需求，不是教你手写代码。
3.1 核心概念
几个关键词需要解释：
（1）"模块化"：Skills 是一个个独立的文件夹，每个 Skill 做一件事。比如"生成 PPT"是一个 Skill，"审校文章"是另一个 Skill。
（2）"能力包"：每个 Skill 文件夹里可以包含：
- SKILL.md（核心指令文件，必需。）
- scripts/（可执行脚本，可选。当 SKILL.md 中引用脚本时，opencode 会执行它。脚本代码不进入上下文，只有执行结果进入。这意味着可以写复杂脚本处理确定性任务，而不占 Token。）
- references/（参考文档，可选。当任务需要更多信息时，opencode 会读取这些文档。采用渐进式披露，平时不加载。）
- assets/（模板和资源，可选。比如报告模板、配置文件、样例数据。）
（3）"自动加载"：你不需要手动告诉 Claude"现在用 XX Skill"。Claude 会根据你的任务描述，自动判断需要哪个 Skill，然后加载。
（4）渐进式披露：分阶段、按需加载。一个 Skill 包含很多内容：核心指令、参考文档、执行脚本、模板资源。但 Claude/OpenCode 等不会一次性把所有内容都加载进上下文。它采用三层加载机制：
第一层：元数据（Metadata）—— 总是加载
- 内容：SKILL.md 文件开头的 YAML 部分，就两个字段：name 和 description。
