Agent Skills

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

放置文件

为每个 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
• 项目 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 工具描述中列出可用的 skills。每个条目包含 skill 名称和描述：

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

Agent 通过调用工具加载 skill：

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

配置权限

使用 opencode.json 中基于模式的权限控制 agent 可以访问哪些 skills：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "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 工具

为不应使用 skills 的 agent 完全禁用：

对于自定义 agent：

---
tools:
  skill: false
---

对于内置 agent：

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

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

排查加载问题

如果 skill 没有显示：

• 验证 SKILL.md 全部大写
• 检查 frontmatter 是否包含 name 和 description
• 确保 skill 名称在所有位置中唯一
• 检查权限——设置为 deny 的 skills 对 agent 隐藏