一、什么是 Agent Skills
构建高效的 AI Agent 系统时,我们往往希望它能遵循特定的、可复用的操作流程,比如按固定格式创建 Git Release、执行代码检查或生成符合规范的文档。OpenCode Agent Skill 提供了一种机制,允许我们将这些指令和行为封装起来,供 Agent 在需要时发现并调用。
一个 Skill 本质上是一份包含特定指令的 Markdown 文件,它定义任务名称、描述及具体执行步骤。通过这种方式,我们可以将复杂、重复的工作流程标准化,让 Agent 像调用工具一样精确执行预定义任务。这不仅提升了协作效率,也确保了输出结果的规范性。
简单来说,Skills 的核心价值在于:把重复的指令打包,按需加载。
二、配置路径
创建一个 Skill 的过程很直接,核心是在指定目录中放置名为 SKILL.md 的文件。OpenCode 会在特定路径下搜索该文件,分为项目本地和全局两种,方便我们将 Skill 应用于特定项目或在所有项目中共享。
1. 项目本地路径
允许将 Skill 与代码仓库绑定,其他开发者克隆后也能立即使用。OpenCode 会从当前工作目录向上搜索至 Git 根目录,加载符合以下模式的文件:
.opencode/skill/<skill-name>/SKILL.md.claude/skills/<skill-name>/SKILL.md
2. 全局路径
用于存放通用、与具体项目无关的 Skill,对所有项目可见(Windows 下实测路径示例):
~/.config/opencode/skill/<skill-name>/SKILL.md~/.claude/skills/<skill-name>/SKILL.md~/.agents/skills/<skill-name>/SKILL.md
其中 <skill-name> 是目录名,必须与 Skill 本身的名称保持一致。这种结构使得每个 Skill 的定义都清晰隔离在自己的文件夹内。
三、内容设计与结构
理解 Skill 的结构逻辑至关重要,这决定了如何向 AI 提出需求。
1. 核心概念
- 模块化:Skill 是独立的文件夹,每个只做一件事。例如'生成 PPT'是一个 Skill,'审校文章'是另一个。
- 能力包:每个文件夹可包含:
SKILL.md(核心指令,必需)scripts/(可执行脚本,可选。引用时执行,结果进入上下文,代码本身不占 Token)references/(参考文档,可选。渐进式披露,平时不加载)assets/(模板和资源,可选)
- 自动加载:无需手动告诉 Agent 使用哪个 Skill,它会基于任务描述自动判断并加载。
- 渐进式披露:分阶段、按需加载内容,避免一次性塞满上下文。
2. 三层加载机制
第一层:元数据(Metadata)
- 内容:
SKILL.md开头的 YAML 部分,仅含name和description。 - 时机:启动时加载所有 Skills 的元数据。
- 成本:约 100 tokens/Skill。50 个 Skills 约 5000 tokens。
- 作用:让系统知道有哪些可用 Skill。
--- name: ai-proofreading description: 系统化降低


