智能体技能

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

---

文件放置

为每个技能名称创建一个文件夹，并在其中放入一个 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 个字符。 保持描述足够具体，以便智能体能做出正确的选择。

---

使用示例

像这样创建 .opencode/skill/git-release/SKILL.md：

---
name: git-release
description: 创建一致的发布说明和变更日志
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## 我能做什么

- 从已合并的 PR 中起草发布说明
- 提议版本号更新
- 提供可复制粘贴的 `gh release create` 命令

## 何时使用我

在准备标记版本发布时使用。
如果目标版本方案不明确，请向我提问以确认。

---

识别工具描述

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

<available_skills>
  <skill>
    <name>git-release</name>
    <description>创建一致的发布说明和变更日志</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 的技能对智能体是隐藏的