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