使用 Agent Skills

理解 OpenCode Agent Skills：放在哪里、怎么写、什么时候加载，以及权限如何控制。

Agent Skill 是一份可以被 OpenCode 按需加载的操作说明。新手可以把它理解成“给 Agent 的专题小手册”：平时只暴露名称和描述，真正需要时才把完整 SKILL.md 放进上下文。

这和把所有规则都写进 AGENTS.md 不同。AGENTS.md 适合放项目长期规则，Skill 适合放某个可复用任务的细节，例如发布流程、PR 审查流程、文档生成流程。

放在哪里

为每个技能名称创建一个文件夹，并在其中放入 SKILL.md。 OpenCode 会搜索以下位置：

项目配置：.opencode/skills/<name>/SKILL.md
全局配置：~/.config/opencode/skills/<name>/SKILL.md
项目 Claude 兼容：.claude/skills/<name>/SKILL.md
全局 Claude 兼容：~/.claude/skills/<name>/SKILL.md
项目代理兼容：.agents/skills/<name>/SKILL.md
全局代理兼容：~/.agents/skills/<name>/SKILL.md

选择位置时按这个顺序判断：只服务当前仓库就放项目目录；多仓库都要用就放全局目录；已经有 Claude Code 技能库时，可以沿用 .claude/skills 兼容入口。

发现机制怎么理解

对于项目本地路径，OpenCode 会从当前工作目录向上遍历，直到到达 git 工作树根目录。在此过程中，它会加载 .opencode/ 中所有匹配的 skills/*/SKILL.md，以及匹配的 .claude/skills/*/SKILL.md 或 .agents/skills/*/SKILL.md。

全局定义也会从 ~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md 和 ~/.agents/skills/*/SKILL.md 中加载。

如果你在子目录启动 OpenCode，仍然希望项目技能生效，就要确认这个子目录还在同一个 git 工作树里。

怎么写 frontmatter

每个 SKILL.md 必须以 YAML frontmatter 开头。仅识别以下字段：

name（必填）
description（必填）
license（可选）
compatibility（可选）
metadata（可选，字符串到字符串的映射）

未知的 frontmatter 字段会被忽略。

最小结构如下：

---
name: git-release
description: Prepare release notes and a safe GitHub release command
license: MIT
compatibility: opencode
---

## When to use

Use this when preparing a tagged release.