---
title: "05 · Agents、Skills 與 Plugins"
description: "區分 OpenCode 中的 agent、skill、plugin：角色邊界、流程複用和執行時擴充套件不要混在一起。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **這一篇用 12 分鐘換什麼**：你會知道什麼時候只用內建 Agent，什麼時候寫自定義 Agent，什麼時候沉澱 `SKILL.md`，什麼時候才值得寫 Plugin，以及團隊裡怎麼把這些擴充套件放到可維護的位置。

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

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

```mermaid
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 | 誰來做、能做什麼、用什麼模型和許可權 | `.opencode/agents/*.md` / `opencode.json` |
| Skill | 遇到某類任務時按什麼流程做 | `.opencode/skills/<name>/SKILL.md` |
| Plugin | OpenCode 執行過程中額外發生什麼 | `.opencode/plugins/*.ts` / npm plugin |

> [!IMPORTANT]
> 配置層級越低，維護成本越高，影響面越大。Plugin 是程式碼擴充套件，不是高階提示詞；全域性 Plugin 更要謹慎。

## Agent 是角色和許可權邊界

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

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

| 型別 | Agent | 呼叫方式 | 適合場景 |
| --- | --- | --- | --- |
| **Primary（主代理）** | `Build`（預設） | TUI 預設進入；按 **Tab** 在 primary agents 之間切換 | 實現、修復、改檔案、跑命令——所有工具預設開啟 |
| **Primary（主代理）** | `Plan` | 按 **Tab** 切換進入 | 規劃、分析、保守判斷——`edit` / `bash` 預設 `ask`，不會亂改 |
| **Subagent（子代理）** | `Explore` | 主代理在需要時自動呼叫，或 `@explore` 手動觸發 | 只讀探索程式碼庫、查路徑 / 符號 / 呼叫關係 |
| **Subagent（子代理）** | `General` | 主代理呼叫，或 `@general` 觸發；可並行 | 獨立研究、多步驟旁路任務 |

> [!NOTE]
> 這就是 03 篇說的"按 Tab 切換 Plan / Build 雙模式"在底層 agent 系統裡的對應——OpenCode 預設 ship 了兩個 primary agent，Tab 在兩者之間切。OpenCode 還有 3 個隱藏 system agent（`compaction` / `title` / `summary`），分別管自動壓縮、生成會話標題、生成摘要，由系統自動呼叫，不出現在 UI 裡。

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

## 什麼時候建立自定義 Agent

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

適合建立的例子：

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

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

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

```md title=".opencode/agents/review.md"
---
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 名。使用时可以写：

```text
@review review the current diff
```

> [!TIP]
> **权限比提示词更可靠**：如果你真的不希望 review agent 改文件，就用 `permission.edit: deny`。只在提示词里写“不要改文件”，不等于形成安全边界。

## 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/`。

最小结构：

```md title=".opencode/skills/release-check/SKILL.md"
---
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` 里控制：

```jsonc title="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 不要直接放全局。

## 团队怎么组合

一个比较稳的团队配置通常是这样分层：

```text
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 後，是否知道哪些流程會受影響？

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

## 接下來去哪

<Cards>
  <Card title="配置 Agents" description="繼續看內建 Agent、自定義 Agent、許可權和主/子代理的官方配置。" href="/zh-Hant/docs/opencode/official/02-agents-skills/agents" />
  <Card title="使用 Agent Skills" description="把可複用流程沉澱成 `SKILL.md`，並用 permission 控制載入範圍。" href="/zh-Hant/docs/opencode/official/02-agents-skills/skills" />
  <Card title="安裝外掛" description="只有需要執行時事件和行為擴充套件時，再進入 Plugin。" href="/zh-Hant/docs/opencode/official/02-agents-skills/plugins" />
  <Card title="模型與供應商策略" description="當角色邊界清楚後，再決定哪些 Agent 用強模型、哪些任務用小模型。" href="/zh-Hant/docs/opencode/understanding/06-model-provider-strategy" />
</Cards>

## 官方資料

- Agents：[https://opencode.ai/docs/agents](https://opencode.ai/docs/agents)
- Agent Skills：[https://opencode.ai/docs/skills](https://opencode.ai/docs/skills)
- Plugins：[https://opencode.ai/docs/plugins](https://opencode.ai/docs/plugins)
- Permissions：[https://opencode.ai/docs/permissions](https://opencode.ai/docs/permissions)
