智能体技能 Agent Skills

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

---

放置文件 Place files

为每个技能创建一个文件夹，并在其中放入一个 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

---

了解发现机制 Understand discovery

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

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

---

编写 Frontmatter Write frontmatter

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

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

未知的 frontmatter 字段将被忽略。

---

验证名称 Validate names

name 必须：

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

等效正则表达式：

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

---

遵循长度规则 Follow length rules

description 必须为 1-1024 个字符。 保持足够具体，以便智能体正确选择。

---

使用示例 Use an example

像这样创建 .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.

---

识别工具描述 Recognize tool description

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

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

智能体通过调用工具加载技能：

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

---

配置权限 Configure permissions

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

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

权限 Permission	行为 Behavior
allow	技能立即加载
deny	技能对智能体隐藏，访问被拒绝
ask	加载前提示用户批准

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

---

覆盖每个智能体 Override per agent

给予特定智能体不同于全局默认值的权限。

对于自定义智能体 (在智能体 frontmatter 中):

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

对于内置智能体 (在 opencode.json 中):

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

---

禁用技能工具 Disable the skill tool

完全禁用不应使用技能的智能体的技能功能：

对于自定义智能体:

---
tools:
  skill: false
---

对于内置智能体:

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

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

---

故障排除加载 Troubleshoot loading

如果技能没有显示：

1. 验证 SKILL.md 是否全大写拼写
2. 检查 frontmatter 是否包含 name 和 description
3. 确保所有位置的技能名称唯一
4. 检查权限——带有 deny 的技能对智能体隐藏