代理技能

通过 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 工作树根目录。在此过程中，它会加载 .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 个字符。请保持描述足够具体，以便代理能够正确选择。

使用示例

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

---name: git-releasedescription: Create consistent releases and changelogslicense: MITcompatibility: opencodemetadata:  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>

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

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

配置权限

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

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

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

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

按代理覆盖权限

为特定代理授予与全局默认值不同的权限。

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

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

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

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

禁用技能工具

为不需要使用技能的代理完全禁用技能功能：

自定义代理：

---tools:  skill: false---

内置代理：

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

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

排查加载问题

如果某个技能没有显示：

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

最近更新： 2026年5月1日

On this page