Agent 技能

Agent 技能让 OpenCode 能够从你的代码仓库或 home 目录中发现可复用的指令。技能通过原生的 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 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 中加载。

编写 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"
    }
  }
}

Permission	行为
`allow`	技能立即加载
`deny`	技能对 agent 隐藏，访问被拒绝
`ask`	加载前向用户请求确认

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

按 agent 覆盖

为指定的 agent 提供与全局默认值不同的权限。

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

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

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

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

禁用 skill 工具

对不应该使用技能的 agent 完全禁用技能：

对于自定义 agent：

---
tools:
  skill: false
---

对于内置 agent：

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

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

故障排查

如果某个技能没有出现：

确认 SKILL.md 全部为大写
检查 frontmatter 是否包含 name 和 description
确保所有位置中的技能名称唯一
检查权限——带有 deny 的技能对 agent 不可见