05 · Agents、Skills 與 Plugins

你是 OpenCode 擴充套件機制顧問。

【角色】
OpenCode 擴充套件機制顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我想擴充套件什麼：___
- 內建能否覆蓋：___
- 候選擴充套件來源：___
- 個人還是團隊：___
- 風險偏好：___

【工作流程】
1. 分清三者職責
2. 判斷是否真需要擴充套件
3. 評估來源和許可權
4. 給安全接入建議
5. 給驗證

【輸出規範】
▌一、三者職責
▌二、是否需要
▌三、來源 / 許可權
▌四、安全接入 + 驗證

【硬約束】
- 內建夠用就不擴充套件
- 來源不明的不裝
- 擴充套件許可權最小必要
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

OpenCode 裡最容易被過度設定的三類能力是 Agents、Skills 和 Plugins。它們確實能增強 OpenCode，但不是同一層東西：Agent 管角色和許可權，Skill 管可複用流程，Plugin 管執行時擴充套件。

先給結論：能用低維護層解決，就不要升級

大多數新手前期不需要 Plugin。先把內建 Build / Plan / Explore / General 用熟，再考慮自定義 Agent；只有跨專案重複出現的流程才適合 Skill；只有需要改變 OpenCode 執行過程時才寫 Plugin。

flowchart TB
  Prompt["一次性提示詞"] --> Rules["Rules / AGENTS.md<br/>長期專案約束"]
  Rules --> Commands["Commands<br/>重複入口"]
  Commands --> Agent["Agents<br/>角色和許可權邊界"]
  Agent --> Skill["Skills<br/>按需載入的流程包"]
  Agent --> Tool["Custom tools / MCP<br/>可呼叫能力"]
  Tool --> Plugin["Plugins<br/>執行時事件和行為擴充套件"]

  style Agent fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
  style Skill fill:#dcfce7,stroke:#22c55e
  style Plugin fill:#fee2e2,stroke:#ef4444

一句提示詞能解決的事，不要寫 Agent；一個 Command 能穩定解決的事，不要做 Skill；一個 Custom Tool 能解決的事，不要寫 Plugin。

三者怎麼分

Agent 是角色和許可權邊界

Agent 適合定義“誰來做這件事”。它可以繫結提示詞、模型、許可權、模式和輸出習慣。它的核心價值不是角色名，而是限制行為範圍。

OpenCode 內建 4 個可見 Agent，按"呼叫方式"分兩類：

日常最穩的流程是：Plan 先讀程式碼和拆方案，Build 執行明確改動，Explore 查詢區域性結構，General 處理獨立支線。這比一上來建立 10 個自定義 Agent 更可靠。

什麼時候建立自定義 Agent

只有某類任務反覆出現，並且需要固定邊界時，才值得建立自定義 Agent。

適合建立的例子：

• review：只讀審查目前 diff，不改檔案。
• docs：維護文件，要求補內鏈、事實來源和示例。
• security：檢查金鑰、許可權、記錄洩露和危險命令。
• migration：只做遷移方案和風險評估，執行前停下來。
• release：生成釋出說明和釋出前檢查清單。

不適合建立的情況：一次性任務、只是想換一個角色名、還沒有穩定輸出標準、許可權邊界和預設 Build 沒有區別。

推薦用 Markdown 定義，便於 review 和版本化：

---
description: Review code without editing files
mode: subagent
permission:
  edit: deny
  bash: ask
---

Review the current change.
Focus on bugs, security risks, regressions, missing tests, and edge cases.
Do not edit files.

檔名就是 Agent 名。使用時可以寫：

@review review the current diff

Agent 設定先抓住 7 個欄位

新手不用背完整設定表，先抓住這些欄位：

• description：寫觸發場景（subagent 的描述決定主代理什麼時候自動呼叫它）。
• mode：決定 primary / subagent / all，不寫預設 all。
• permission：控制硬邊界（read / edit / bash / webfetch / skill 等都能單獨設 allow / ask / deny）。
• model：只在確有差異時指定（如 plan 用便宜模型、deep audit 用強模型）。
• prompt：可以寫在 frontmatter 之後的正文裡，也可以指向外部檔案 prompt: "{file:./prompts/review.txt}"，長 prompt 用外部檔案更易 review。
• temperature：控制隨機性（plan / 分析類 0.0-0.2，brainstorm 類 0.6-1.0）。
• steps：限制最多迭代輪數，防止一條任務無限燒 token。

如果某個 Agent 每次呼叫都還需要你補一句"只讀""先復現""不要提交"，說明這些內容應該進 Agent 檔案。

Skill 是可複用流程包

Skill 解決的問題不是“誰來做”，而是“遇到某類任務時按什麼流程做”。它適合沉澱跨專案複用的操作說明、檢查清單、指令碼用法和輸出標準。

適合做成 Skill：釋出前檢查、程式碼安全審計、文件寫作流程、框架遷移檢查清單、故障排查 SOP、團隊內部工具的穩定用法。

不適合做成 Skill：目前專案的一條臨時要求、只會用一次的 prompt、沒有明確觸發場景的大段知識、真實金鑰和客戶資料。

OpenCode 會按需載入 Skill。Agent 先看到 Skill 的名稱和描述，判斷需要時再透過 skill 工具載入完整 SKILL.md。所以 description 要寫清楚“什麼時候用”，不要只寫 help with release。

Skill 放在哪裡

官方支援多個位置：

• .opencode/skills/<name>/SKILL.md：目前專案專用。
• ~/.config/opencode/skills/<name>/SKILL.md：OpenCode 全域複用。
• .claude/skills/<name>/SKILL.md：相容專案裡的 Claude Code Skill。
• ~/.claude/skills/<name>/SKILL.md：相容全域 Claude Code Skill。
• .agents/skills/<name>/SKILL.md、~/.agents/skills/<name>/SKILL.md：相容 agent 生態目錄。

如果你已經有 Claude Code 的 Skill 庫，不要為了 OpenCode 再複製一份大型目錄。先確認相容入口能不能複用，再決定是否遷移到 .opencode/skills/。

最小結構：

---
name: release-check
description: Use when preparing a release; checks changelog, tests, versioning, and publish commands
license: MIT
compatibility: opencode
---

## When to use

Use this when preparing a tagged release.

## Steps

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

Skill 名稱要和目錄一致，只用小寫字母、數字和單個連字元。例如 release-check，不要寫成 Release_Check。

Skill 許可權要單獨治理

Skill 會把額外指令載入進上下文，因此也需要許可權治理。可以在 opencode.json 裡控制：

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

團隊環境裡，內部 Skill 不要預設全開。涉及釋出、憑據、客戶專案、生產環境的 Skill，建議先設為 ask，穩定後再精確放開。

如果只想給某個 agent 單獨開放更寬的 Skill 許可權（比如 plan agent 預設禁內部 Skill，但允許它讀 documents-*），寫在 agent 自己的 frontmatter 或 agent.<name>.permission.skill 裡，覆蓋全域。需要徹底關掉 agent 的 Skill 能力時，把 tools.skill 設成 false，OpenCode 就不會向它暴露 <available_skills> 列表。

Plugin 是執行時擴充套件

Plugin 不是給模型看的說明書，而是擴充套件 OpenCode 自身執行行為的程式碼。它可以監聽事件、修改工具呼叫、注入環境變數、傳送通知、記錄記錄，也可以配合 custom tools 提供更深的整合。

適合 Plugin 的情況：

• 會話完成後傳送系統通知。
• 工具執行前檢查命令是否危險。
• 在 shell.env 階段注入專案環境變數。
• 記錄 session.*、permission.*、tool.execute.* 事件。
• 在上下文壓縮前自動補充專案狀態。

不適合 Plugin 的情況：只是想加一段角色設定、固定一次審查流程、讓模型多一個命令入口，或者流程價值還沒有被驗證過。

本地 Plugin 放在 .opencode/plugins/ 或 ~/.config/opencode/plugins/。npm Plugin 可以在 opencode.json 的 plugin 陣列裡宣告；啟動時 OpenCode 會透過 Bun 自動安裝並快取。不瞭解原始碼的 npm Plugin 不要直接放全域。

團隊怎麼組合

一個比較穩的團隊設定通常是這樣分層：

AGENTS.md
  專案長期約定：包管理器、測試命令、目錄邊界、釋出紅線

.opencode/commands/
  重複入口：/review-diff、/fix-failing-test、/write-release-note

.opencode/agents/
  角色邊界：review、docs、security、migration

.opencode/skills/
  跨專案流程：release-check、security-audit、docs-polish

.opencode/plugins/
  執行時擴充套件：通知、記錄、內部環境注入、工具呼叫攔截

順序也應該按這個來：先把規則和命令跑穩定，再拆 Agent；先證明流程跨專案複用，再做 Skill；只有需要執行時事件和程式碼擴充套件，才寫 Plugin。

新手常見坑

• 一開始建立太多 Agent，選擇成本變高，邊界仍然模糊。
• description 寫得太空，OpenCode 不知道何時呼叫。
• 只靠提示詞限制許可權，仍可能誤改檔案或執行命令。
• 把專案百科寫進 Skill，載入後上下文噪聲變大。
• 把 Plugin 當提示詞增強器，導致排障困難。
• 全域 Plugin 太多，所有專案都受影響。

怎麼驗收

用這些問題檢查是否過關：

• 能否說清每個自定義 Agent 的觸發場景？
• 審查、規劃類 Agent 是否真的禁止或詢問寫入？
• Skill 是否有跨專案複用價值，而不是一次性 prompt？
• Skill 名稱、目錄、frontmatter 是否一致？
• Plugin 是否解決執行時問題，而不是規則問題？
• 停用某個 Agent / Skill / Plugin 後，是否知道哪些流程會受影響？

過關標準很簡單：你能把一句經驗放到正確層級，並能解釋它為什麼不是更低維護成本的一層。

接下來去哪

官方資料

• Agents：https://opencode.ai/docs/agents
• Agent Skills：https://opencode.ai/docs/skills
• Plugins：https://opencode.ai/docs/plugins
• Permissions：https://opencode.ai/docs/permissions