Agent 技能

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

---

放置文件

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

• 项目配置：.opencode/skill/<name>/SKILL.md
• 全局配置：~/.config/opencode/skill/<name>/SKILL.md
• 项目 Claude 兼容路径：.claude/skills/<name>/SKILL.md
• 全局 Claude 兼容路径：~/.claude/skills/<name>/SKILL.md

---

理解发现机制

对于项目本地路径，OpenCode 会从你当前的工作目录向上遍历，直到到达 git 工作树。 在此过程中，它会加载任何匹配的 .opencode/skill/*/SKILL.md 和 .claude/skills/*/SKILL.md。

全局定义也会从 ~/.config/opencode/skill/*/SKILL.md 和 ~/.claude/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/skill/git-release/SKILL.md，内容如下：

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

我的功能

• 根据已合并的 PR 起草发布说明
• 提议版本号变更
• 提供可复制的 gh release create 命令

何时使用我

在准备进行带标签的发布时使用我。 如果目标版本控制方案不明确，我会询问澄清性问题。

---


## 识别工具描述

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

```xml
<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": {
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask",
      "*": "allow"
    }
  }
}

权限	行为
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> 部分会被完全省略。

---

故障排查加载问题

如果某个技能没有显示：

1. 确认 SKILL.md 文件名全部为大写
2. 检查 frontmatter 是否包含 name 和 description
3. 确保所有位置的技能名称都是唯一的
4. 检查权限——带有 deny 权限的技能对代理是隐藏的