Agent skills 让 OpenCode 能够从你的 repo 或 home directory 中发现可复用的指令。 Skills 会通过原生的 skill tool 按需加载 —— agent 可以看到有哪些可用 skills，并在需要时加载完整内容。

放置文件（Place files）

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

  • Project config：.opencode/skill/<name>/SKILL.md
  • Global config：~/.config/opencode/skill/<name>/SKILL.md
  • Project Claude-compatible：.claude/skills/<name>/SKILL.md
  • Global Claude-compatible：~/.claude/skills/<name>/SKILL.md

理解发现机制（Understand discovery）

对于 project-local 路径，OpenCode 会从你当前的 working directory 开始向上遍历，直到到达 git worktree。

在这个过程中，它会加载沿途所有 .opencode/ 目录下匹配的 skill/*/SKILL.md，以及所有匹配的 .claude/skills/*/SKILL.md。

同时，也会从以下全局路径加载定义：

  • ~/.config/opencode/skill/*/SKILL.md
  • ~/.claude/skills/*/SKILL.md

编写 frontmatter（Write frontmatter）

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

  • name（必填）
  • description（必填）
  • license（可选）
  • compatibility（可选）
  • metadata（可选，string-to-string map）

未知的 frontmatter 字段会被忽略。

校验名称（Validate names）

name 必须：

  • 长度为 1–64 个字符
  • 仅包含小写字母和数字，并使用单个连字符 - 分隔
  • 不能以 - 开头或结尾
  • 不能包含连续的 --
  • 必须与包含该 SKILL.md 的目录名一致

等价的正则表达式：

  1. ^[a-z0-9]+(-[a-z0-9]+)*$

遵守长度规则（Follow length rules）

description 的长度必须是 1–1024 个字符。 描述要足够具体，方便 agent 正确选择对应的 skill。

使用示例（Use an example）

创建 .opencode/skill/git-release/SKILL.md，内容如下：

  1. ---
  2. name: git-release
  3. description: Create consistent releases and changelogs
  4. license: MIT
  5. compatibility: opencode
  6. metadata:
  7.   audience: maintainers
  8.   workflow: github
  9. ---
  11. ## What I do
  13. - Draft release notes from merged PRs
  14. - Propose a version bump
  15. - Provide a copy-pasteable `gh release create` command
  17. ## When to use me
  19. Use this when you are preparing a tagged release.
  20. Ask clarifying questions if the target versioning scheme is unclear.

识别 tool 描述（Recognize tool description）

OpenCode 会在 skill tool 的描述中列出所有可用 skills。 每个条目包含 skill name 和 description：

  1. <available_skills>
  2.   <skill>
  3.     <name>git-release</name>
  4.     <description>Create consistent releases and changelogs</description>
  5.   </skill>
  6. </available_skills>

agent 可以通过调用 tool 来加载某个 skill：

  1. skill({ name: "git-release" })

配置权限（Configure permissions）

你可以在 opencode.json 中使用基于 pattern 的权限规则，控制 agent 可以访问哪些 skills：

  1. {
  2.   "permission": {
  3.     "skill": {
  4.       "*": "allow",
  5.       "pr-review": "allow",
  6.       "internal-*": "deny",
  7.       "experimental-*": "ask"
  8.     }
  9.   }
  10. }
Permission 行为说明
allow Skill 会立即加载
deny Skill 对 agent 隐藏，访问会被拒绝
ask 加载前会向用户请求授权

Patterns 支持通配符： 例如 internal-* 可以匹配 internal-docs、internal-tools 等。

按 agent 覆盖权限（Override per agent）

可以为特定 agent 配置不同于全局默认值的权限。

对于自定义 agents（在 agent frontmatter 中）：

  1. ---
  2. permission:
  3.   skill:
  4.     "documents-*": "allow"
  5. ---

对于内置 agents（在 opencode.json 中）：

  1. {
  2.   "agent": {
  3.     "plan": {
  4.       "permission": {
  5.         "skill": {
  6.           "internal-*": "allow"
  7.         }
  8.       }
  9.     }
  10.   }
  11. }

禁用 skill tool（Disable the skill tool）

可以为不需要使用 skills 的 agent 完全禁用 skill 功能。

对于自定义 agents：

  1. ---
  2. tools:
  3.   skill: false
  4. ---

对于内置 agents：

  1. {
  2.   "agent": {
  3.     "plan": {
  4.       "tools": {
  5.         "skill": false
  6.       }
  7.     }
  8.   }
  9. }

当被禁用时，<available_skills> 区块会被完全省略。

排查加载问题（Troubleshoot loading）

如果某个 skill 没有显示出来，请检查：

  1. 确认文件名是否严格为全大写 SKILL.md
  2. 检查 frontmatter 是否包含 name 和 description
  3. 确保所有位置中的 skill name 唯一
  4. 检查权限配置 —— 被设置为 deny 的 skills 会对 agent 隐藏