代理技能

通过 SKILL.md 定义可重用行为

Agent 技能让 OpenCode 能够从您的仓库或主目录中发现可重用的指令。技能通过原生的 skill 工具按需加载——Agent 可以看到可用的技能并在需要时加载完整内容。

放置文件

为每个技能名称创建一个文件夹，并在其中放入一个 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
项目 Agent 兼容：.agents/skills/<name>/SKILL.md
全局 Agent 兼容：~/.agents/skills/<name>/SKILL.md

理解发现机制

对于项目本地路径，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 加载。

编写 frontmatter

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

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

未知的 frontmatter 字段将被忽略。

验证名称

name 必须

为 1-64 个字符
为小写字母数字，并以单个连字符分隔
不能以 - 开头或结尾
不能包含连续的 --
与包含 SKILL.md 的目录名匹配

等效正则表达式

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

遵循长度规则

description 必须为 1-1024 个字符。保持其足够具体，以便 Agent 正确选择。

使用示例

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

---
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.

识别工具描述

OpenCode 在 skill 工具描述中列出可用的技能。每个条目都包含技能名称和描述。

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

Agent 通过调用该工具加载技能。

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

配置权限

使用 opencode.json 中的基于模式的权限控制 Agent 可以访问哪些技能。

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

权限	行为
`允许`	技能立即加载
`拒绝`	技能对 Agent 隐藏，访问被拒绝
`询问`	加载前提示用户批准

模式支持通配符：internal-* 匹配 internal-docs、internal-tools 等。

为每个 Agent 覆盖设置

为特定 Agent 设置不同于全局默认值的权限。

对于自定义 Agent（在 Agent frontmatter 中）

---
permission:
  skill:
    "documents-*": "allow"
---

对于内置 Agent（在 opencode.json 中）

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

禁用技能工具

对于不应使用技能的 Agent，完全禁用其技能

对于自定义 Agent:

---
tools:
  skill: false
---

对于内置 Agent:

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

禁用后，<available_skills> 部分将完全省略。

排查加载问题

如果技能未显示

验证 SKILL.md 是否全部大写
检查 frontmatter 是否包含 name 和 description
确保技能名称在所有位置都是唯一的
检查权限——具有 deny 权限的技能将对 Agent 隐藏