---
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="/docs/opencode/official/02-agents-skills/agents" />
  <Card title="使用 Agent Skills" description="把可复用流程沉淀成 `SKILL.md`，并用 permission 控制加载范围。" href="/docs/opencode/official/02-agents-skills/skills" />
  <Card title="安装插件" description="只有需要运行时事件和行为扩展时，再进入 Plugin。" href="/docs/opencode/official/02-agents-skills/plugins" />
  <Card title="模型与供应商策略" description="当角色边界清楚后，再决定哪些 Agent 用强模型、哪些任务用小模型。" href="/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)
