强大的智能体系统，不是把提示词写长，而是处理好分工、边界、权限、上下文和校验。

opencode 给了几块积木：主代理、子代理、skill、项目规则和权限系统，难点是组织它们。主代理太强，会变成失控杂工，带来幻觉和过多 Token 消耗；传给子代理的上下文与 prompt 不当，会造成语义污染和 Token 浪费；skill 不设限制，会在错误场景里乱入；权限不给边界，所有设计都会败给一次误操作。

配套核心文件放这里，正文只讲组织方法：

• 完整示例配置：opencode-paper-suite.json
• 主代理示例：paper.agent.md.txt
• 子代理示例：reader-deep.agent.md.txt
• 仲裁代理示例：arbiter.agent.md.txt
• 诊断代理示例：diagnose.agent.md.txt
• Skill 示例：paper-reading.skill.md.txt
• 项目路由规则：AGENTS.routing.md.txt

原则

把 Agent 当人用，把 Skill 当工具书用，把权限当门锁用。

Agent 有角色、目标、权限和责任。它能判断、调度、取舍。

Skill 是流程卡。它告诉模型怎么做某类任务，给检查表、术语表、模板和质量标准。

权限是硬边界。它决定代理能不能读、写、跑命令、访问网络、调用别的代理。

三者不要混。

推荐结构

1
2
3
4
5
6
7
8
9
10
11

your-project/
├── opencode.json
├── AGENTS.md
└── .opencode/
    ├── agents/
    │   ├── main.md
    │   ├── reviewer.md
    │   └── researcher.md
    └── skills/
        └── some-skill/
            └── SKILL.md

适合所有项目的能力放全局，只适合当前项目的规则放项目里。项目配置会覆盖全局配置。

主代理：负责收口

主代理用 mode: primary。它不必亲自干所有事，但必须对最终结果负责。

它要做六件事：

1. 判断用户真正要什么。
2. 拆成可执行步骤。
3. 决定哪些自己做，哪些交给子代理。
4. 汇总子代理结果。
5. 验证关键结论。
6. 交付最终答案。

主代理最忌两种病：什么都自己做，或者把责任甩给子代理。好的主代理像导师，不像复读机。

子代理：只做窄任务

子代理用 mode: subagent。它的价值来自边界。

适合交给子代理的任务：

• 大仓库里定位功能。
• 广泛的多仓库阅读、web调研功能。
• 独立审阅一个方案。
• 检查某个实现风险。
• 盲读同一份材料，防止主代理自我强化。
• 仲裁两份分析的分歧。

不适合交给子代理的任务：

• 需要和用户多轮确认。
• 一两行小改动。
• 连续教学和讲解。
• 没有清晰输入和输出标准的模糊任务。

对子代理，权限应更窄。审阅、阅读、仲裁、诊断类子代理通常只需要读，不需要写。

Skill：沉淀方法

Skill 放在：

1

.opencode/skills/my-skill/SKILL.md

无需赘述。opencode 兼容 Anthropic 的 skill 文件格式，按 SKILL.md 的约定写即可。常见的文档处理、简单图表制作类 skill，也可以直接下载使用。

description 要写清触发场景，因为模型会根据描述决定是否加载这个 skill。一个好 skill 的描述应该包含具体触发词，比如“论文、PDF、arXiv、图表、实验、消融”。不要写“帮助你更好工作”这类空话。

限制 Skill

skill 要白名单化。尤其是你有上百个 skill 时，opencode 会一次展示给 Agent，容易造成混乱。（尤其是 Gemini 这种蠢家伙）

通用思路是：先拒绝全部，再放开需要的几个。具体配置看：opencode-paper-suite.json。

权限设计

建议默认倾向是：

• 读文件、搜索文件：全允许。
• 访问网络：一般允许。
• 写文件：询问。
• shell 命令：询问，只放行安全查看命令。
• 子代理：按角色收窄权限。

阅读、审阅、仲裁类子代理不该拥有写权限。实现类子代理可以写，但必须有清晰任务范围。

AGENTS.md：写项目规则

AGENTS.md 适合写整个项目的路由规则，而不是某个代理的介绍。

它应该回答：

• 什么时候主代理自己做。
• 什么时候派子代理。
• 哪些任务必须独立核查。
• 哪些事情不能做。
• 最终交付前要验证什么。

下载示例：AGENTS.routing.md.txt。

一个可复用的四层结构

1
2
3
4
5
6
7
8
9

主代理：理解意图，拆任务，收口
├── 探索子代理：找资料、找代码、摸结构
├── 实现子代理：按明确计划改文件
├── 审阅子代理：独立检查风险
└── 仲裁子代理：分歧时按证据裁决

Skills：提供任务方法
Permissions：限制工具边界
AGENTS.md：规定调度纪律

这套结构可以用于写代码、读论文、写文档、做数据报告。不同场景换不同 skill 和子代理，但骨架不变。

以论文 Agent 为例

配套文章里，论文 Agent 系统拆成：

1
2
3
4
5

paper 主代理
├── reader-deep：独立阅读子代理
├── arbiter：仲裁
├── diagnose：诊断
└── paper-reading skill：论文阅读流程

完整教程见：Paper-Agent 在 opencode 中的实现。

这个例子体现的是一般方法：主代理管方向，子代理管局部，skill 管方法，权限管风险。

写在最后

智能体系统不需要复杂到吓人，边界清楚，就已经很强大了。