使用 Agent Skills

Agent Skill 是一份可以被 OpenCode 按需載入的操作說明。它平時只暴露名稱和描述，Agent 認為需要時，才透過原生 skill 工具載入完整 SKILL.md。

先給結論：Skill 是流程包，不是大號規則檔案

不要把 Skill 當成另一個 AGENTS.md。兩者職責不同：

Skill 最適合承載釋出流程、PR 審查流程、文件生成流程、遷移檢查清單、排障 SOP 這類可複用任務。臨時要求不要做成 Skill，否則庫會越來越臃腫。

Skill 是怎麼被發現和載入的

OpenCode 會先發現可用 Skill，把名稱和描述放進 skill 工具說明裡。Agent 先看摘要，判斷需要時再載入完整內容。

flowchart LR
  Start[當前工作目錄] --> Walk[向上查詢到 git worktree]
  Walk --> Project[專案級 skills]
  Home[使用者主目錄] --> Global[全域性 skills]
  Project --> List[可用技能列表<br/>name + description]
  Global --> List
  List --> Decide{Agent 判斷是否需要}
  Decide -->|需要| Load[呼叫 skill 工具載入 SKILL.md]
  Decide -->|不需要| Skip[不佔用上下文]

這個機制的關鍵是：description 寫得越具體，Agent 越容易在正確時間載入它。

放在哪裡

為每個 Skill 建立一個資料夾，並在裡面放 SKILL.md。OpenCode 會搜尋這些位置：

選擇順序很簡單：

1. 只服務當前儲存庫，放專案目錄。
2. 多個儲存庫都要用，放全域性目錄。
3. 已經有 Claude Code Skill 庫，優先複用相容入口，不要複製一份大型目錄。

SKILL.md frontmatter 怎麼寫

每個 SKILL.md 必須以 YAML frontmatter 開頭。官方識別這些欄位：

未知欄位會被忽略，不要把關鍵約束寫在 OpenCode 不識別的 frontmatter 欄位裡。

名稱和描述怎麼判斷

name 要滿足：

• 長度 1-64 個字元。
• 只用小寫字母、數字和單個連字元。
• 不以 - 開頭或結尾。
• 不包含連續 --。
• 與包含 SKILL.md 的目錄名一致。

等效規則可以記成：

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

description 長度為 1-1024 個字元。它不是廣告語，而是給 Agent 的觸發條件。不要寫 help with git，要寫清楚“什麼時候用、產出什麼、有哪些邊界”。

一個可用的最小 Skill

檔案：.opencode/skills/release-check/SKILL.md

---
name: release-check
description: Use when preparing a release; checks diff, changelog, tests, version bump, and publish command
license: MIT
compatibility: opencode
metadata:
  workflow: github-release
---

## When to use

Use this when preparing a tagged release or release candidate.

## Steps

1. Read the current diff and changelog.
2. Confirm tests and version bump.
3. Draft release notes.
4. Produce a publish command for human review.

## Boundaries

Do not publish automatically.
Do not include secrets or private customer names.

這個 Skill 的重點不是寫得長，而是觸發條件、步驟和邊界都清楚。

許可權如何控制

在 opencode.json 裡可以用模式控制 Agent 能訪問哪些 Skill：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "skill": {
      "*": "ask",
      "release-check": "allow",
      "internal-*": "deny"
    }
  }
}

模式支援萬用字元。比如 internal-* 可以覆蓋 internal-docs、internal-tools 等內部技能。

按 Agent 覆蓋許可權

你也可以讓不同 Agent 使用不同 Skill 許可權。比如審查 Agent 可以使用 documents-*，但普通聊天 Agent 看不到內部發布 Skill。

自定義 Agent frontmatter 示例：

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

內建 Agent 可以在 opencode.json 裡覆蓋：

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

什麼時候停用 Skill 工具

有些 Agent 不應該載入 Skill：

• 只做規劃、不執行流程的 Agent。
• 不應該接觸內部資料的 Agent。
• 臨時測試 Agent，避免誤載入團隊 Skill。

可以直接關閉 skill 工具。關閉後，可用技能列表會完全省略。

---
tools:
  skill: false
---

排查載入問題

如果某個 Skill 沒顯示，按這個順序查：

1. 檔名是否是全大寫 SKILL.md。
2. frontmatter 是否包含 name 和 description。
3. name 是否和目錄名完全一致。
4. 當前啟動目錄是否位於目標 git 工作樹內。
5. 不同位置是否有同名 Skill 衝突。
6. 許可權是否被設為 deny。

新手常見坑

• 描述太泛，Agent 不知道什麼時候載入。
• Skill 太大，把整個團隊手冊塞進一個檔案。
• 目錄名和 name 不一致。
• 專案專用 Skill 放到全域性，導致其他儲存庫誤觸發。
• 把真實金鑰、賬號、客戶資料寫進 Skill。
• 只會用一次的 prompt 也做成 Skill。

接下來去哪

官方資料

• OpenCode Agent Skills
• OpenCode configuration