05 · Agents、Skills 與 Plugins

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