代理技能

通过 SKILL.md 定义可复用的行为

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

# 放置文件#

为每个技能名称创建一个文件夹，并在其中放置一个 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

# 理解发现机制#

对于项目本地路径，OpenCode 从当前工作目录向上遍历直到 git worktree 根目录。它会加载沿途 .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 加载。

路径核验：2026-10-08。 以上位置和发现机制依据 OpenCode 官方技能文档↗，未在本次修订中运行技能加载测试。

# 编写 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 个字符。保持足够具体，以便代理能够正确选择。

# 使用示例#

创建 .opencode/skills/git-release/SKILL.md：

markdown
1---
2name: git-release
3description: 创建一致的发布和更新日志
4license: MIT
5compatibility: opencode
6metadata:
7  audience: maintainers
8  workflow: github
9---
10
11## 我做什么
12
13- 从已合并的 PR 起草发布说明
14- 建议版本号升级
15- 提供可复制粘贴的 `gh release create` 命令
16
17## 何时使用我
18
19准备打标签发布时使用此技能。
20如果目标版本控制方案不清楚，请提出澄清问题。

# 识别工具描述#

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

xml
1<available_skills>
2  <skill>
3    <name>git-release</name>
4    <description>创建一致的发布和更新日志</description>
5  </skill>
6</available_skills>

代理通过调用工具来加载技能：

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

# 配置权限#

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

json
1{
2  "permission": {
3    "skill": {
4      "*": "allow",
5      "pr-review": "allow",
6      "internal-*": "deny",
7      "experimental-*": "ask"
8    }
9  }
10}

权限	行为
`allow`	技能立即加载
`deny`	技能对代理隐藏，访问被拒绝
`ask`	加载前提示用户批准

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

规则顺序会影响结果。 同一技能名称匹配多条规则时，最后一条匹配规则生效。因此先写默认的 "*": "allow"，再写具体规则。上例中，internal-docs 被拒绝，experimental-demo 需要确认，其他未被具体规则覆盖的技能允许加载；若把 "*": "allow" 移到最后，它会覆盖前面的 deny 和 ask。

权限规则核验：2026-10-08。 依据官方细粒度权限规则↗及技能权限示例↗。以上是文档规则说明，不代表已执行 OpenCode 权限测试。

# 按代理覆盖#

为特定代理提供与全局默认不同的权限。

对于自定义代理（在代理 frontmatter 中）：

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

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

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

# 禁用技能工具#

完全禁用不应使用技能的代理的技能功能：

对于自定义代理：

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

对于内置代理：

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

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

# 故障排除加载问题#

如果技能没有显示：

验证 SKILL.md 全部大写
检查 frontmatter 包含 name 和 description
确保技能名称在所有位置中唯一
检查权限 — 设置为 deny 的技能对代理隐藏

代理技能

相关文档