05 · Agents、Skills 与 Plugins

OpenCode 里有三类容易混淆的扩展点：agents、skills、plugins。它们都能增强 OpenCode，但职责不同。

最简单的区分方式：

Agent    让模型换一种角色和工具边界
Skill    给模型一套可复用的领域操作说明
Plugin   扩展 OpenCode 运行时能力

Agent 是角色和边界

Agent 适合定义“谁来做这件事”。它通常包含系统提示词、可用工具、模型和行为边界。

例如：

• review：只做代码审查，优先找 bug、回归、安全风险。
• docs：只写文档，强调结构、事实来源和链接。
• test：专注失败测试，先复现再修。
• planner：只拆任务，不直接改代码。

Agent 的价值在于缩小行为范围。一个默认 agent 什么都能做，结果往往边界发散；专用 agent 的输出更稳定。

Skill 是领域能力包

Skill 适合定义“遇到某类任务该怎么做”。它不像 agent 那样强调角色，而是强调流程、检查清单、工具用法和输出标准。

适合做成 skill 的内容：

• 发布前检查。
• 数据清洗流程。
• 迁移某个框架。
• 写某类教程。
• 调试某种部署故障。
• 对某个 API 做封装。

如果一段经验会跨项目重复出现，就更适合 skill；如果只属于当前项目，就先放 rules 或 commands。

Plugin 是运行时扩展

Plugin 更接近代码层扩展。它不是告诉模型“怎么想”，而是给 OpenCode 增加能力。

适合 plugin 的场景：

• 添加新的集成。
• 扩展界面或事件。
• 接入团队内部服务。
• 封装复杂工具调用。
• 改变 OpenCode 的运行时行为。

Plugin 的维护成本更高。不要把一句提示词能解决的问题做成 plugin。

三者怎么配合

一个真实团队可能这样组织：

rules
  写项目长期约定：包管理器、测试命令、目录边界、代码风格

commands
  写重复任务入口：/review、/fix-test、/release-note

agents
  写角色分工：review agent、docs agent、test agent

skills
  写跨项目能力：安全审计、迁移指南、发布流程

plugins
  写运行时能力：内部系统集成、自定义面板、专用工具

这套分层的关键是避免所有东西都塞进一个超长系统提示词。

常见误区

第一个误区：把所有规则写进 agent。结果 agent 文件越来越长，模型反而抓不住重点。

第二个误区：把一次性提示词做成 skill。skill 需要复用价值，否则只是换了个文件保存临时提示词。

第三个误区：过早写 plugin。plugin 一旦进入运行时扩展，就要考虑版本、权限、测试和安全边界。

从低维护成本到高维护成本，顺序应该是：

普通提示词 → command → rule → agent → skill → plugin

只有当前一层解决不了问题时，再进入下一层。