Agent Skills - OpenCode Docs | OpenCode Tutorial

Agent skills 让 OpenCode 能够从你的 repo 或 home 目录中发现可重用的指令。 Skills 通过原生 skill 工具按需加载——agents 可以看到可用的 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

##理解发现机制

对于项目本地路径，OpenCode 从当前工作目录向上遍历，直到到达 Git 工作树。它加载 .opencode/ 中任何匹配的 skills/*/SKILL.md 以及沿途任何匹配的 .claude/skills/*/SKILL.md。

全局定义也从 ~/.config/opencode/skills/*/SKILL.md 和 ~/.claude/skills/*/SKILL.md 加载。

##编写 frontmatter

每个 SKILL.md 必须以 YAML frontmatter 开头。仅识别以下字段：

name (必需)
description (必需)
license (可选)
compatibility (可选)
metadata (可选，字符串到字符串的映射)

未知的 frontmatter 字段将被忽略。

##验证名称

name 必须：

为 1–64 个字符
为小写字母数字，带有单个连字符分隔符
不以 - 开头或结尾
不包含连续的 --
匹配包含 SKILL.md 的目录名称

等效正则表达式：

bash

^[a-z0-9]+(-[a-z0-9]+)*$

##遵循长度规则

description 必须为 1-1024 个字符。使其足够具体，以便 agent 正确选择。

##使用示例

创建 .opencode/skills/git-release/SKILL.md 如下所示：

bash

---
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 名称和描述：

bash

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

Agent 通过调用该工具来加载 skill：

bash

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

##配置权限

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

bash

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

| Permission | Behavior | | ---------- | ----------------------------------------- | | allow | Skill 立即加载 | | deny | Skill 对 agent 隐藏，访问被拒绝 | | ask | 在加载之前提示用户批准 |

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

##针对每个 agent 覆盖

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

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

bash

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

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

bash

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

##禁用 skill 工具

完全禁用不应使用 skills 的 agents 的 skills：

对于自定义 agents：

bash

---
tools:
  skill: false
---

对于内置 agents：

bash

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

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

##故障排除加载

如果 skill 没有显示出来：

验证 SKILL.md 是否全部以大写字母拼写
检查 frontmatter 是否包含 name 和 description
确保 skill 名称在所有位置都是唯一的
检查权限——具有 deny 的 skills 对 agents 隐藏