OpenCode Skills 使用指南：技能目錄、命名規則、權限配置與不加載排查

本文根據 OpenCode 官方文檔《Agent Skills》整理，資料核對於 2026-10-11。OpenCode 是一款開源的終端編程智能體，安裝與模型配置以其官方文檔為準，本文只講技能。

適用於誰

• 搜「opencode skills 使用」「opencode skills 目錄」「opencode skills 安裝」的人；
• 想讓 OpenCode 直接用上已有的 Claude Code 技能的人；
• 團隊裏想限制某些技能只能被特定智能體使用的人。

結論先說

1. OpenCode 自己的目錄是 .opencode/skills/（項目）和 ~/.config/opencode/skills/（全局），同時也讀 .claude/skills/ 和 .agents/skills/ 以及它們在主目錄下的對應位置。
2. name 規則嚴格：1–64 個字符，小寫字母和數字，單個連字符分隔，且必須和所在目錄同名。
3. 技能通過一個叫 skill 的工具加載：智能體在工具描述裏看到可用技能的名稱和描述，需要時按名稱加載。
4. 權限在 opencode.json 裏配：對技能名（支持通配符）設 allow、deny 或 ask。
5. OpenCode 專有的行為寫在 metadata 裏，而不是加自定義的頂層字段，這樣同一份 SKILL.md 在別的工具裏也不會出錯。

一、技能放在哪

每個技能一個文件夾，裏面放 SKILL.md：

發現規則：對項目路徑，OpenCode 從當前工作目錄向上走，直到 git worktree 的根，沿途每一層的 .opencode/skills//SKILL.md、.claude/skills//SKILL.md、.agents/skills/*/SKILL.md 都會加載；全局技能從上面三個主目錄路徑加載。

這意味着已經在用 Claude Code 的項目，不需要做任何遷移，OpenCode 打開就能看到 .claude/skills/ 裏的技能。

二、frontmatter 與命名規則

• 必填：name、description；
• 可選：license、compatibility、metadata（字符串到字符串的鍵值表）。

name 的規則

• 1–64 個字符；
• 小寫字母和數字，用單個連字符分隔；
• 不能以 - 開頭或結尾，不能有連續的 --；
• 必須和包含 SKILL.md 的目錄名一致；
• 對應的正則：^[a-z0-9]+(-[a-z0-9]+)*$

description 的規則：1–1024 個字符，要具體到足以讓智能體做出正確選擇。

OpenCode 專有的兩個開關放在 metadata 下：

官方說明這兩個鍵也接受 YAML 布爾值。按官方示例的思路寫出來是這樣：

markdown
---
name: git-release
description: Create consistent releases and changelogs. Use when preparing a tagged release.
metadata:
  opencode/slash: "true"
  opencode/autoinvoke: "false"
---

## 步驟
（發佈流程的具體說明）

上面這個組合的含義是：只能通過 /git-release 手動調用，模型不會自己用它。適合發佈這類有副作用的流程。

三、技能是怎麼被加載的

OpenCode 提供一個名為 skill 的工具：

• 工具的描述裏有一段 <available_skills>，列出每個可用技能的名稱和描述；
• 智能體判斷需要某個技能時，調用 skill({ name: "git-release" }) 加載它的全文；
• opencode/autoinvoke 設為 "false" 的技能不會出現在 <available_skills> 裏，但仍然可以按確切名稱加載。

所以和其他工具一樣，智能體平時只看得到名稱和描述，description 決定它會不會被用上。

四、配置權限

在 opencode.json 裏按技能名設定，支持通配符：

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

通配符的例子：internal-* 會匹配 internal-docs。

對來源還不夠放心的技能，先設為 ask，每次加載都能看到一次提示。

五、按智能體覆蓋

自定義智能體：在智能體定義文件的 frontmatter 裏寫

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

內置智能體：在 opencode.json 的 agent 下寫

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

完全關掉技能工具：自定義智能體在 frontmatter 的 tools: 下寫 skill: false；內置智能體在 opencode.json 裏把 agent.plan.tools.skill 設為 false。關掉之後，<available_skills> 整段都不會出現。

六、技能不出現時的五項檢查

官方的排查清單：

1. 確認文件名是全大寫的 SKILL.md；
2. 確認 frontmatter 裏有 name 和 description；
3. 確認技能名稱在所有位置中是唯一的；
4. 檢查權限，設為 deny 的技能對智能體是隱藏的；
5. 檢查 opencode/autoinvoke，設為 "false" 的技能不會出現在給模型看的列表裏。

第 3 條值得多看一眼：OpenCode 同時掃描三套目錄，同一個技能如果在 .opencode/skills/ 和 .claude/skills/ 裏各放了一份，就違反了唯一性。保留一份即可。

常見問題

Q：怎麼安裝別人的技能？

把技能文件夾放進上面任一目錄即可。也可以用通用的命令行工具一次裝到多個工具，見《npx skills add 怎麼用》。裝之前先看內容，見《Skill 安全嗎：安裝前檢查什麼》。

Q：技能在列表裏但不被使用？

改 description，把使用場景寫具體，見《Skill 不觸發怎麼辦》。

Q：Claude Code 專有的 frontmatter 字段在這裏有用嗎？

官方文檔列出的可識別字段只有 name、description、license、compatibility、metadata。其他工具的專有字段在 OpenCode 裏不要指望生效。

Q：SKILL.md 怎麼寫？

見《SKILL.md 怎麼寫》。

參考資料

• Agent Skills（OpenCode 官方文檔）：https://opencode.ai/docs/skills/
• Specification（Agent Skills 官方規範）：https://agentskills.io/specification