《代理技巧》

“通過 SKILL.md 定義定義可重用行為”

代理技能讓 opencode 從您的存儲庫或主目錄中發現可重用的指令。技能通過本機 skill 工具按需加載 - 代理可以查看可用技能並可以在需要時加載完整內容。

放置文件

每個技能名稱創建一個文件夾，並在其中放入SKILL.md。 opencode 搜索這些位置：

項目配置：.opencode/skills/<name>/SKILL.md
全局配置：~/.config/opencode/skills/<name>/SKILL.md
克勞德項目兼容：.claude/skills/<name>/SKILL.md
全球克勞德兼容：~/.claude/skills/<name>/SKILL.md
項目代理兼容：.agents/skills/<name>/SKILL.md
全球代理兼容：~/.agents/skills/<name>/SKILL.md

了解發現

對於項目本地路徑，opencode 將從當前工作目錄開始，直到到達 git 工作樹。它加載 skills/*/SKILL.md 中任何匹配的 .opencode/ 以及一路上任何匹配的 .claude/skills/*/SKILL.md 或 .agents/skills/*/SKILL.md。

全局定義也從~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md 和~/.agents/skills/*/SKILL.md 加載。

寫前言

每個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/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 工具描述中列出了可用的技能。每個條目都包含技能名稱和描述：

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

許可	行為
`allow`	技能立即加載
`deny`	技能對特工隱藏，訪問被拒絕
`ask`	加載前提示用戶批准

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

覆蓋每個代理

為特定代理授予與全局默認權限不同的權限。

對於自定義代理（在代理前言中）：

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

對於內置代理（在 opencode.json 中）：

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

禁用技能工具

完全禁用不應該使用技能的特工：

對於定制代理：

---
tools:
  skill: false
---

對於內置代理：

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

禁用時，<available_skills> 部分將被完全省略。

解決加載問題

如果某項技能沒有顯示：

驗證 SKILL.md 是否全部大寫拼寫
檢查 frontmatter 是否包含 name 和 description
確保技能名稱在所有位置都是唯一的
檢查權限 - deny 的技能對代理隱藏