第 5 章 · Agents / Commands / Skills

前 4 章让你能在「通用助手」模式下高效工作。本章让 OpenCode 进化：定制专属 Agent、把常用 Prompt 固化成命令、用 Skill 装载专门知识——把它从一个通用工具，改造成为你量身定制的工作台。

本章包含 6 个知识点：

1. Agent 是什么：内置 Agent 与切换方式
2. 自定义 Agent：.opencode/agents/*.md
3. Commands：把常用 Prompt 固化成斜杠命令
4. Skills：按需加载的专门知识
5. 四者辨析：AGENTS.md / Agent / Command / Skill
6. 组合实战：用三者搭建个人工作流

---

知识点 1：Agent 是什么：内置 Agent 与切换方式

① 定位

在定制之前，先搞清楚「Agent」在 OpenCode 里的准确含义，以及开箱即有哪些 Agent。很多人用了很久都没切换过 Agent，错过了「不同任务用不同人设与工具策略」带来的提升。

② 是什么（What）

Agent（智能体配置） 是一份预设：它定义了 AI 以什么身份与工作方式处理任务——系统提示、可用工具范围、所用模型、是主交互角色还是子代理等。

OpenCode 内置了若干 Agent（名称与模式以官方文档为准）：

内置 Agent	模式	典型定位
build	primary（主交互）	主力编码 Agent：默认开放工具；读取敏感环境文件、访问工作区外时才要授权
plan	primary（主交互）	规划者：探索与出方案，不编辑普通项目文件（被要求时可写 OpenCode 的 plan 文件）
general	subagent（子代理）	处理研究与多步工作，工具范围广，但不能再启动更多子代理
explore	subagent（子代理）	快速探索代码库、回答「在哪里 / 怎么实现」，适合作为子任务被派出

同一个任务交给不同 Agent，行为差异明显：主交互的 build 擅长动手、plan 擅长先想后做；作为子代理的 explore 适合快速定位、general 适合承担需要广工具的研究子任务。选对 Agent，等于在任务开始前就选好了工作姿态。

③ 怎么做（How）

切换 Agent 的方式（默认键位，第 2 章已接触）：

1. Ctrl+X → A：打开 Agent 列表选择；
2. Shift+Tab：在各 Agent 间循环切换；
3. 输入 /agents 查看与选择；
4. 切换后留意状态栏，确认当前 Agent 名称，再开始任务。

一个简单选用习惯：陌生代码派 explore 子代理，动手前用 plan 过方案，确认后用 build 实现，需要研究型多步子任务时用 general。

④ 为什么这么做（Why）

• 没有「万能姿态」。 快速搜索需要轻装、广撒网；动手实现需要完整工具与写权限；方案设计需要克制、先诊断。让一个 Agent 兼顾全部，结果往往是「搜索时太重、动手时太莽、规划时太急」。
• 预设把「经验」前置成「配置」。 资深者面对不同任务会本能切换工作模式；Agent 把这套模式差异固化下来，你只需选择，不必每次临时叮嘱「先别改代码」。
• 工具范围也是风险控制。 规划 / 探索类 Agent 通常不默认拥有强写权限，用它们做前期工作，天然降低误改代码的概率——身份选择与安全策略是联动的。
• 可切换成本极低、收益持续。 只是一次按键或一条命令，却让每个任务都以更合适的方式启动。

⑤ 这样做的好处

• 任务开局即正确：姿态与任务性质匹配。
• 风险前置降低：前期工作用受限 Agent，减少误操作。
• 心智负担减轻：不用每次在 Prompt 里重复限定工作方式。
• 协作节奏清晰：探索 → 规划 → 构建形成稳定流水线。
• 为自定义打基础：理解内置 Agent 后，才知道缺什么、该补什么。

⑥ 不这么做的问题 / 坏处

• 一个 build 走天下 → 陌生代码里它可能还没摸清结构就动手改。
• 该规划时直接构建 → 方向没确认就产生大量改动，返工成本高。
• 从不切换 → 错过工具预设带来的效率与安全收益。
• 切了不确认 → 以为在用某个 Agent，实际是另一个，产出与预期不符。

⑦ 举一反三：三个例子

例 1（基础）：接手陌生项目先探索

📌 场景：你克隆了一个陌生仓库，要先搞清楚登录逻辑在哪。

✅ 做法：不切换主 Agent，直接对 build 说「用 explore 子代理查清：登录认证相关代码分布在哪些文件？调用链从入口到 token 校验是怎样的？」；主 Agent 会派出 explore 子代理，把汇总结果带回。

🔍 讲解：explore 是 subagent，不能用 Shift+Tab 切成主角色，而应在任务中点名让主 Agent 派出它。探索子代理不会动手改任何东西，定位正好匹配「快速找代码」，且它的搜索过程不污染主会话。

例 2（进阶）：动手前先规划

📌 场景：你确认要做一个涉及多文件的功能，但不希望它上来就改。

✅ 做法：切到 plan，让它给出方案、影响面、步骤顺序与风险，等你确认后，再切 build 实现。

🔍 讲解：这就是「plan 先想、build 后做」的经典两段式。方案在无改动阶段产出，你审查的是思路而非一堆 diff，纠偏成本最低。

例 3（挑战）：为高风险任务刻意选受限 Agent

📌 场景：让 AI 在生产配置相关目录做只读分析，你非常担心误改。

✅ 做法：主 Agent 切到 plan（它不编辑普通项目文件），或派 explore 子代理做只读定位；并在任务中再次声明「只分析、不修改、不执行写操作」。

🔍 讲解：双保险——Agent 预设限制 + Prompt 显式约束。任务风险越高，越值得在「身份层」和「指令层」同时收紧，而不是只靠临场盯着。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：默写出至少 3 个内置 Agent 的名称及其典型定位，并说出切换 Agent 的两种方式。

💡 思路提示：build / plan / explore / general；切换走 Leader 组合或循环键。

✅ 参考答案：

- build：主力编码（primary），默认开放工具，敏感读取 / 越界访问才授权；
- plan：规划（primary），探索出方案、不编辑普通项目文件；
- general：研究型子代理（subagent），工具广但不能再派子代理；
- explore：探索子代理（subagent），快速搜索定位。
切换：Ctrl+X → A 打开列表；Shift+Tab 循环（也可用 /agents）。

🔍 讲解：能把「名称 → 定位 → 切换方式」对应起来，说明你已掌握 Agent 系统的基本用法。

练习 2（迁移型）

📝 题目：迁移到职场分工：「调研员 / 方案架构师 / 开发工程师」的分工，和 explore/plan/build 有什么共性？为什么团队要这样分角色？

💡 思路提示：不同阶段需要不同技能与权限，角色分离降低风险。

✅ 参考答案（示例）：

- 调研员（explore）：快速摸清现状、提供事实，不做决策与改动；
- 架构师（plan）：基于事实设计方案、评估风险，先想清楚再动手；
- 开发工程师（build）：按确认方案执行实现。
共性：把工作按「了解 → 设计 → 执行」分阶段配角色，
每个角色用合适的技能与权限，既专业又能防止「没想清楚就乱改」。
OpenCode 的内置 Agent 复刻的正是这种成熟的工程角色分工。

知识点 2：自定义 Agent：.opencode/agents/*.md

① 定位

内置 Agent 覆盖通用姿态，但你总会有特定的、重复出现的工作方式需求——比如「专门做代码审查且只读」「专门写提交信息」。本知识点讲如何把这些姿态定义成自己的 Agent。

② 是什么（What）

自定义 Agent 是放在项目 .opencode/agents/ 目录下的 Markdown 文件（每个文件一个 Agent，文件名即 Agent 标识的一部分）。它由两部分组成：

1. Frontmatter（元数据）：声明 Agent 的名称、描述、使用的模型、工具范围、是否作为子代理（subagent）等；
2. 正文（系统提示）：这个 Agent 的身份、工作原则、行为要求。

一个自定义「只读代码审查 Agent」的结构示意（字段名为官方 Agents 文档确认的写法）：

---
description: 只读代码审查，输出按严重程度排序的问题清单
mode: subagent          # primary=主交互；subagent=子代理；all=两者皆可
subagent:
  description: 只读审查当前改动          # 这段描述会给模型看，决定何时调用它
model: 供应商/强模型ID     # 省略则继承父会话的模型
permissions:
  write: deny
  edit: deny
  patch: deny
---

你是一位严格的代码审查员。你的职责：
- 只阅读与分析，绝不修改文件、绝不执行写操作；
- 问题按「必须改 / 建议改」分组，标注文件行号；
- 不确定的地方明确标注「需人工确认」，不要编造结论。

要点：工具权限通过 frontmatter 的 permissions 规则声明（支持通配），而不是嵌套的 tools: 表；mode / subagent 控制它是主 Agent、子代理还是两者都可。

定义后，它会和内置 Agent 一样出现在 Agent 列表中，可切换或被主任务作为子代理调用。

③ 怎么做（How）

1. 在项目（或全局配置对应位置）创建 .opencode/agents/reviewer.md；
2. 写 frontmatter：用 permissions 声明工具范围（只读就 deny 写/edit/patch）、用 model 指定强模型、用 mode 决定角色；
3. 写正文：身份 + 必须遵守的工作原则 + 输出格式；
4. 保存后用 /agents 或 Ctrl+X → A 确认它已出现；

④ 为什么这么做（Why）

• 重复的工作姿态值得固化。 当你第 N 次在 Prompt 里写「请只做审查、不要修改、按严重程度排序」，这些字本可以一劳永逸地进入 Agent 正文——自定义 Agent 消除的是「姿态级重复」。
• 工具范围在 frontmatter 的 permissions 中被硬性约束。 仅靠 Prompt 说「别改文件」，模型理论上仍可能越界；在配置层用权限规则 deny 写工具，是比口头要求更可靠的机械限制。
• 身份提示决定专业深度。 「你是严格的代码审查员」加上明确输出规则，会让模型持续进入特定角色，产出比临时通用提问更聚焦、更一致。
• 自定义 Agent 是可共享资产。 文件随项目入库后，团队每个人都拥有同一个审查员，标准统一。
• 子代理机制让专业角色可被编排。 主任务可以在需要时调用专门 Agent，而不必让人手动来回切换（知识点 6 展开）。

⑤ 这样做的好处

• 专业姿态一键调用，产出稳定一致。
• 权限在配置层锁死，高风险角色更安全。
• 团队标准统一：同一 Agent，同样口径。
• 减少大量重复 Prompt。
• 可迭代沉淀：每次改进 Agent 文件，所有人立刻受益。

⑥ 不这么做的问题 / 坏处

• 每次临时写长 Prompt → 重复劳动，且措辞不一、结果漂移。
• 只靠口头限制写操作 → 存在被越界的风险，尤其在复杂任务中。
• 标准只在个人脑中 → 团队审查口径各异，无法统一质量。
• 自定义后不验证字段 → frontmatter 写错可能导致 Agent 不加载或权限不符预期。

⑦ 举一反三：三个例子

例 1（基础）：写一个提交信息专员

📌 场景：你经常需要让 AI 根据改动生成规范的提交信息。

✅ Agent 要点：正文规定「只读取 diff、按 Conventional Commits 输出一条建议、不执行 commit」；工具以读为主。

🔍 讲解：把「生成提交信息但不替你提交」固化成角色，既复用了能力，又把最终提交权留在你手里——专业 + 安全。

例 2（进阶）：只读、强模型的审查员

📌 场景：如正文所示的 reviewer，你希望它在重要 PR 上做深度审查。

✅ 做法：frontmatter 关闭写工具、指定强模型；正文要求分组、带行号、标注不确定项。

🔍 讲解：三层约束协同——配置层无写权限（机械限制）+ 强模型（能力保障）+ 正文规则（输出标准），这是一个高可靠专业 Agent 的典型构造。

例 3（挑战）：定义可被子任务调用的子代理

📌 场景：你希望主开发任务在遇到大量文件检索时，自动派一个「代码搜索员」子代理并行查找，而不是主线自己慢搜。

✅ 做法：在 Agent 配置中设置 mode: subagent（或 all），并在 subagent.description 中写清它的用途（这段描述会给主模型看、用于选择是否调用），正文聚焦「只负责快速搜索并汇总文件与行号，结果交回主任务」。

🔍 讲解：子代理的价值是并行 + 上下文隔离：它的搜索过程不污染主会话，结果摘要回传。这要求 Agent 正文明确「职责边界 + 结果形态」，否则回传内容主线难以使用。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：一个自定义 Agent 文件由哪两部分组成？若要确保它「绝不修改文件」，最可靠的做法是什么？

💡 思路提示：frontmatter 与正文；机械限制优先于口头要求。

✅ 参考答案：

两部分：frontmatter（元数据：模型、工具范围等）与正文（身份与行为提示）。
绝不修改文件：在 frontmatter 中关闭写工具（配置层硬限制），
比只在正文里要求“不要改”更可靠。

🔍 讲解：理解「声明式配置 + 提示式引导」的分工，是写好自定义 Agent 的关键。

练习 2（迁移型）

📝 题目：迁移到岗位说明书：一份好的岗位定义为什么既要写「职责与行为要求」，又要规定「权限边界（能动用什么资源）」？

💡 思路提示：只讲职责不给边界，可能越权；只给边界不讲职责，不知道该干什么。

✅ 参考答案（示例）：

- 职责与行为要求（对应正文）让人知道目标、标准与做法；
- 权限边界（对应 frontmatter 工具范围）限定可动用的资源，
  防止越权与误操作；
二者结合，角色既能干活又不失控。只写其一：
有职责无边界 → 风险敞口；有边界无职责 → 无所作为。
共性：Agent 文件本质上就是一份「人机可读的岗位说明书」。

知识点 3：Commands：把常用 Prompt 固化成斜杠命令

① 定位

自定义 Agent 固化的是「谁来做」，Command 固化的是「说哪段话」。当某段 Prompt 反复使用、且需要带上当下参数时，把它做成斜杠命令是最直接的提效方式。

② 是什么（What）

Command（斜杠命令） 是放在 .opencode/commands/ 目录下的 Markdown 文件，文件名即命令名。文件内容主要是一段预置 Prompt 模板，支持参数占位与动态内容：

语法	含义
$ARGUMENTS	调用命令时输入的全部参数
$1、$2 …	按位置引用单个参数
反引号内执行 shell	用反引号包裹命令，运行并把输出内联进 Prompt（如 `git branch --show-current`；多命令可写 `git diff --stat && git diff`）

示例 .opencode/commands/test.md：

请为 $ARGUMENTS 补充单元测试，要求覆盖正常、边界、非法输入三类；
不要修改被测源码，完成后运行相关测试并贴出结果。

之后在 TUI 中输入 /test src/utils/date.ts，即等价于发出这段填好参数的 Prompt。

Command vs 自定义 Agent：Command 是「一段可复用的话」，执行它的仍是当前 Agent；Agent 是「一种工作方式」。两者正交，也可组合（用某 Agent 执行某命令）。

③ 怎么做（How）

1. 创建 .opencode/commands/review.md；
2. 在正文写 Prompt 模板，用 $ARGUMENTS 接收当下输入；
3. 需要上下文事实时，用 shell 内联（如把当前分支、改动文件列表自动带入）；
4. 保存后输入 / 即可看到新命令，继续打字过滤；

④ 为什么这么做（Why）

• 复用的是「结构良好的 Prompt」。 你精心打磨过的测试 / 审查 / 重构 Prompt，如果每次重写，质量会随当天状态波动；存成命令，最佳版本被永久固定，一次打磨、反复复用。
• 参数占位让模板通用于「当下对象」。 $ARGUMENTS / $1 让同一段流程能套用到不同文件、函数、需求，模板写一次，对象每次现填。
• shell 内联自动补「易漏事实」。 人工调用时常忘记说明当前分支、改动清单；让命令在发送前自动执行 git 并把结果写入，信息准确且不依赖记忆。
• 斜杠调用路径最短。 / + 几个字符即可触发，比翻历史消息复制旧 Prompt 快得多。
• 命令可共享、可版本化，团队复用同一批最佳 Prompt。

⑤ 这样做的好处

• 高质量 Prompt 零成本复用。
• 执行速度快：斜杠 + 参数，一两秒发出。
• 一致性强：每次流程与标准相同。
• 自动带上下文：减少遗漏与手误。
• 团队能力沉淀：好 Prompt 变成组织资产。

⑥ 不这么做的问题 / 坏处

• 反复重写 Prompt → 质量不稳定、浪费时间。
• 靠翻聊天记录复制 → 经常复制错版本或漏改对象名。
• 忘记关键上下文 → 没带分支 / 文件范围，产出跑偏。
• shell 内联用不当 → 调用危险命令或把不稳定输出写进 Prompt。

⑦ 举一反三：三个例子

例 1（基础）：补测试命令

📌 场景：如 /test 模板所示，你经常给不同文件补测试。

✅ 调用：/test src/utils/format.ts——模板自动把文件代入，按既定三类覆盖要求执行。

🔍 讲解：流程标准（三类用例、不改源码、跑测试）被固定，变化的只是目标文件。这是 Command 最典型的「固定流程 + 可变对象」用法。

例 2（进阶）：审查当前分支改动

📌 场景：你想审查「当前分支相对主分支」的改动，每次手敲分支名很麻烦。

✅ 命令要点：用 shell 内联自动获取当前分支与改动文件列表，正文要求按严重程度输出问题清单、只读不改。

🔍 讲解：让命令自己取「当前分支」，消除了人工填错分支名的风险，也保证每次审查范围准确。自动化的事实采集是命令进阶价值所在。

例 3（挑战）：带多参数的多步命令

📌 场景：你希望一条命令完成「为 $1 模块、用 $2 指定的方式重构，并输出到 $3 位置」。

✅ 做法：在模板中用 $1、$2、$3 分别占位，并在开头写明参数缺失时的处理（如让 AI 先反问补齐，而不是带着空参数执行）。

🔍 讲解：多参数命令更强大，但也更易因参数错位出错。显式定义「缺失参数如何处理」能防止模型用空值硬跑——这与 Prompt 中「可验证、防臆测」的原则一致。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：Command 文件放在哪个目录？$ARGUMENTS 与 $1 有什么区别？请写一个简单的 /explain 命令模板。

💡 思路提示：整体参数 vs 第一个位置参数。

✅ 参考答案：

目录：.opencode/commands/
区别：$ARGUMENTS 是调用时输入的全部参数；$1 只是第一个参数。
模板示例（.opencode/commands/explain.md）：
请向中级开发者解释 $ARGUMENTS 的职责、核心函数与调用流程，
引用代码带行号，先不要修改任何文件。

🔍 讲解：掌握目录与占位语法，你就具备把任何高频 Prompt 命令化的能力。

练习 2（迁移型）

📝 题目：迁移到办公自动化：邮件模板、合同模板里的「占位符 + 每次填写」方式，和 Command 的 $ARGUMENTS 有什么共性？

💡 思路提示：固定结构、变量填充、减少重复起草与不一致。

✅ 参考答案（示例）：

- 邮件 / 合同模板固定了结构与标准措辞，只留姓名、金额、日期等占位，
  每次填写即可，避免重复起草和措辞不一；
- Command 同样固定 Prompt 结构，用 $ARGUMENTS 填入当下对象；
共性：把「不变的部分」沉淀为模板，把「变化的部分」参数化，
既提效又保证一致性——这是模板化复用的通用思想。

知识点 4：Skills：按需加载的专门知识

① 定位

Agent 给姿态、Command 给话术，但有些任务需要一大块专门知识 / 操作流程（领域规范、平台流程）。把这些长期塞进系统提示会浪费窗口；Skill 的做法是「平时不加载，用到才唤醒」。

② 是什么（What）

Skill（技能） 是一个自包含的知识包，存放在 .opencode/skills/<技能ID>/ 目录下，核心文件是 SKILL.md：

• Frontmatter：包含技能名称与描述（描述决定「什么情况下该用这个技能」）；
• 正文：完成该类任务的知识、规则与操作步骤；
• 还可包含脚本、模板、参考文件等配套资源。

关键机制是按需加载（渐进式披露）：Skill 默认不占上下文；当任务与其描述匹配、或你显式调用时，它的内容才被读取进来。这使你可以安装很多技能，而不必担心平时全部加载撑爆窗口。

与 Command 的区别：Command 是「你主动触发的一段话」；Skill 是「模型在合适场景自行取用的一块知识 / 流程」，更像一本「需要时翻开的操作手册」。

③ 怎么做（How）

1. 创建 .opencode/skills/deploy-check/SKILL.md；
2. frontmatter 写清名称与「适用场景」描述——描述质量直接决定它会不会在正确时机被唤醒；
3. 正文组织成可执行的检查 / 操作步骤，必要时引用同目录脚本或模板；
4. 正常使用时，当任务命中该场景，模型会参考该技能；你也可以显式要求「使用 deploy-check 技能」；

④ 为什么这么做（Why）

• 专门知识体积大、使用频次低。 部署检查、平台接入流程可能有很多步骤，但只在特定任务才用得上。常驻系统提示会持续浪费每个会话的窗口。
• 按需加载是「信噪比」的最优解。 平时只保留技能的名称与描述（极小开销），真正需要时才加载完整内容——为具体任务临时注入高相关知识。
• 描述承担「路由」职责。 模型根据描述判断何时启用，因此描述必须准确点出触发场景；写得含糊，该用时不唤醒、不该用时乱唤醒。
• 自包含目录便于打包与共享。 SKILL.md + 脚本 + 模板构成一个可整体分发的能力包，安装即用。
• 它让「知识」与「推理」解耦。 你可以不断扩充技能库，而无需改动核心提示——能力增长以插件方式进行。

⑤ 这样做的好处

• 平时零负担、用时能力强。
• 可安装大量技能而不撑爆窗口。
• 专业流程标准化、可复用、可共享。
• 能力扩展模块化，维护与分发简单。
• 与任务高度相关：注入的都是当下需要的知识。

⑥ 不这么做的问题 / 坏处

• 把大段流程塞进系统提示 / AGENTS.md → 每个会话都背着无关内容，窗口吃紧。
• 技能描述写不清 → 唤醒时机错乱，效果不稳定。
• 把 Skill 当 Command 用 → 期待一喊即执行固定话术，其实二者机制不同。
• 技能依赖外部资源却不自包含 → 换环境即失效。

⑦ 举一反三：三个例子

例 1（基础）：发布前检查技能

📌 场景：团队规定发布前要过一串检查项（测试、构建、迁移、回滚说明）。

✅ 做法：把检查清单与顺序写进 deploy-check/SKILL.md，描述为「发布 / 部署前的检查流程」；当你说「准备发布」，该技能被参考，AI 按清单逐项确认。

🔍 讲解：清单只在发布时需要，平时不加载；命中场景才唤醒——典型的按需知识。

例 2（进阶）：带脚本的自包含技能

📌 场景：某平台接入需要固定步骤 + 一个生成配置的脚本。

✅ 做法：技能目录中放入 SKILL.md（流程说明）和 gen-config.*（脚本），正文说明何时运行脚本、如何使用其输出。

🔍 讲解：知识 + 工具同处一个目录，技能可整体复制到别的机器并立即工作。自包含是技能可移植性的关键。

例 3（挑战）：为「正确唤醒」打磨描述

📌 场景：你装了两个相近技能，发现模型经常在错误场景启用其中一个。

✅ 做法：重写两者 frontmatter 描述，显式区分触发条件，并在正文中加一句「不适用于 X 场景」，减少误唤醒。

🔍 讲解：技能的可靠性很大程度取决于描述的区分度。把描述当作「给路由器看的规则」来写，明确包含与排除条件，命中率才会稳定。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：Skill 存放在什么目录结构中？核心文件是什么？为什么 Skill 可以装很多个而不影响平时的上下文？

💡 思路提示：<id>/SKILL.md；按需加载。

✅ 参考答案：

结构：.opencode/skills/<技能ID>/SKILL.md（可含配套脚本/模板）。
核心文件：SKILL.md（frontmatter 名称与描述 + 正文知识流程）。
原因：默认只保留轻量描述、正文按需加载，平时不占上下文，
因此可安装很多技能。

🔍 讲解：理解「渐进式披露」是掌握 Skill 与其它三种机制差异的钥匙。

练习 2（迁移型）

📝 题目：迁移到工具书使用：一本厚厚的《操作手册》平时放在书架、需要某章节时才翻开阅读——这和 Skill 的机制有什么共性？为什么比「把整本书背下来」更合理？

💡 思路提示：记忆 / 携带成本 vs 按需检索。

✅ 参考答案（示例）：

- 手册平时不占用人的记忆，只在遇到对应任务时翻开相关章节，
  获取精确流程；
- “把整本书背下来”成本极高，且大部分内容长期用不到，
  遗忘也快；
共性：大量低频、专门的知识应「集中存放 + 按需检索 + 只读相关章节」，
而非常驻记忆。Skill 让 AI 用同样方式管理专业知识，
兼顾能力广度与当下效率。

知识点 5：四者辨析：AGENTS.md / Agent / Command / Skill

① 定位

学完四种机制，最容易发生的是「概念全混在一起」。本知识点用一张总表和一组判定问题，让你面对任何需求时都能立刻判断：这事该用哪个机制。

② 是什么（What）

四种机制各自回答一个不同的问题：

机制	回答的问题	本质	何时加载
AGENTS.md	在这个项目里，始终要遵守什么？	长期规则	每次会话自动加载
Agent	由什么角色 / 工作方式来处理？	身份 + 工具策略	被切换 / 调用时
Command	我要重复发出的哪段话？	Prompt 模板	输入 /命令 时
Skill	这类任务需要的专门知识 / 流程是什么？	自包含知识包	命中场景按需加载

一句话记忆：

• 规则（AGENTS.md）管「边界与底线」；
• Agent 管「谁来做」；
• Command 管「说什么」；
• Skill 管「懂什么 / 怎么做这套专门流程」。

③ 怎么做（How）

用三个判定问题快速选型：

1. 这是长期每次都生效的规则吗？——是 → AGENTS.md。
2. 我是在改变工作角色 / 工具权限吗？——是 → Agent。
3. 我是在复用一段带参数的 Prompt，还是在提供一块专门知识？
   • 前者主动触发 → Command；
   • 后者按场景唤醒 → Skill。

④ 为什么这么做（Why）

• 四种机制对应四类不同的信息寿命与用途。 把它们混用（如把一次性 Prompt 塞进 AGENTS.md、把大段知识当 Command），要么浪费窗口，要么该生效时不生效。清晰分类让每种信息进入最合适的容器。
• 选型问题把「直觉」显式化。 熟练者凭感觉就能选对；初学者通过三个判定问题，同样能稳定选对，学习路径因此可靠。
• 正交设计支持自由组合。 四个维度互不冲突（规则、角色、话术、知识），因此能叠加出复杂工作流，而不会互相破坏。
• 概念清晰是维护的前提。 你只有知道某个文件「为什么存在」，才能在项目演进时正确地增删改它。

⑤ 这样做的好处

• 面对任何需求都能快速选型，不犹豫。
• 信息各归其位，窗口与维护成本最优。
• 能有意识地组合机制搭建高级流程。
• 团队沟通成本低：术语统一，讨论「该加规则还是该做命令」时无歧义。
• 能力体系完整：既懂单项又懂全局。

⑥ 不这么做的问题 / 坏处

• 概念混淆 → 反复在错误地方加内容，效果与预期不符。
• 把一切都堆进 AGENTS.md → 文件臃肿、信噪比下降。
• 不会组合 → 只用单一机制，错过协同带来的上限提升。
• 凭感觉乱选 → 结果时好时坏，无法稳定复现高效流程。

⑦ 举一反三：三个例子

例 1（基础）：给需求选机制

📌 场景：判断「金额一律以分为单位」该用哪个机制。

✅ 结论：长期每次生效的业务规则 → 写进 AGENTS.md。

🔍 讲解：它既不改变角色、也不是一段话术或一块按需知识，而是恒定底线——规则文件是唯一正确位置。

例 2（进阶）：「我希望每次审查都只读且按固定格式输出」

📌 场景：这句话里藏着多个机制。

✅ 拆解：

• 「只读」可在自定义审查 Agent 的工具范围中锁死（Agent）；
• 「按固定格式输出」可写进 Agent 正文，也可做成 /review 命令模板（Command）；
• 审查中涉及的发布规范则走 Skill 按需加载。

🔍 讲解：复杂需求往往不是四选一，而是先拆成维度、再分别承载。能做这种拆解，就真正理解了四者的正交关系。

例 3（挑战）：审查一个混乱的现有配置

📌 场景：你发现项目把大段操作流程写进了 AGENTS.md，又在 commands 目录放了只含静态口号、从不带参数的文件。

✅ 重构建议：

• 大段低频流程 → 迁移为 Skill；
• 静态口号若属长期规则 → 精炼后留在 AGENTS.md；若本应是可复用 Prompt → 改造成带参数的 Command；
• 逐项核对「信息寿命与用途」后归位。

🔍 讲解：用四者模型反过来审计现有配置，能把历史遗留的错位内容逐步纠正，让整套定制恢复清晰高效。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：为下列需求各选一个最合适的机制：（a）禁止擅自修改迁移文件；（b）需要一个只做安全审计的角色；（c）反复使用、每次对象不同的重构 Prompt；（d）仅在接入某云平台时才需要的详细流程。

💡 思路提示：规则 / 角色 / 话术 / 知识。

✅ 参考答案：

(a) AGENTS.md（长期禁区规则）；
(b) 自定义 Agent（身份 + 收紧工具范围）；
(c) Command（带 $ARGUMENTS 的模板）；
(d) Skill（按需加载的专门流程）。

🔍 讲解：四题恰好对应四种机制，能全对说明选型直觉已建立。

练习 2（迁移型）

📝 题目：迁移到一家公司的管理体系：「公司章程 / 岗位设置 / 标准化流程模板 / 专项操作手册」分别对应哪种机制？为什么成熟组织需要这四类东西同时存在？

💡 思路提示：底线、角色、可复用流程、专门知识缺一不可。

✅ 参考答案（示例）：

- 公司章程 ≈ AGENTS.md：始终适用的底线规则；
- 岗位设置 ≈ Agent：定义由什么角色、拥有什么权限来做事；
- 标准化流程模板 ≈ Command：可反复套用、每次填入具体对象的流程；
- 专项操作手册 ≈ Skill：特定场景才翻阅的专门知识。
共性：四类东西分别承载「规则 / 角色 / 话术 / 知识」，
正交互补、缺一就会在某些场景失控或低效——
OpenCode 的定制体系正是这种成熟组织结构的数字化复刻。

知识点 6：组合实战：用三者搭建个人工作流

① 定位

本章收口：把四种机制从「孤立的功能」编织成一条端到端的个人工作流。学会这一知识点，你将能为任意一类重复性工作，定制出一条半自动、可控、可复用的流水线。

② 是什么（What）

一个成熟的定制工作流，通常沿「任务生命周期」分层挂载四种机制：

开工 → 规则自动在场（AGENTS.md）
探索 → 用 explore / 专门子代理搜集事实
规划 → 用 plan 出方案、人来拍板
执行 → 用 build + /命令（带参数）落实
专业环节 → 命中场景时自动加载 Skill
收口 → 用 Command 生成提交信息 / 检查清单，提交仍需人授权

关键不是「用了多少功能」，而是：每个环节的高价值动作被固化，而风险动作（写、改、提交）始终保留人工闸门。 定制的目标是放大执行力，而不是取消人的决策。

③ 怎么做（How）

以「开发一个新功能」为例，搭建步骤：

1. 先补规则：确认测试、提交、禁区已在 AGENTS.md；缺失则补上；
2. 固化命令：把「补测试 /test」「审查 /review」「提交信息 /commitmsg」做成 Command；
3. 准备 Agent：保留 / 自定义 explore、plan、build，必要时加只读审查员；
4. 准备 Skill：把该功能可能涉及的平台接入 / 发布检查做成技能；

④ 为什么这么做（Why）

• 真正的效率来自「系统」而非「单次发挥」。 单次把 Prompt 写好是技巧；让好 Prompt、好角色、好规则在每个环节自动就位，才是可重复、可依赖的效率系统。
• 分层挂载降低认知负荷。 每种机制只管自己擅长的环节，组合后你在每一步只需做最少决策（主要是审查与授权）。
• 保留人工闸门是定制的底线伦理。 越容易自动化，越要刻意守住删除、提交、发布这类不可逆动作的最终授权——自动化的是执行，不是责任。
• 工作流需要在实战中迭代。 初版不可能完美；每跑一次真实任务，就根据卡点改进对应文件，系统持续进化。
• 组合放大复利。 规则、Agent、命令、技能各自的改进会叠加：一条好规则 + 一个好命令 + 一个好技能，协作质量不是相加而是相乘。

⑤ 这样做的好处

• 重复性工作半自动化，又快又稳。
• 决策点集中在人：风险可控。
• 系统持续进化：越用越贴合个人习惯。
• 切换 / 上手成本低：流程固定，照做即可。
• 可复制到新项目：把 .opencode/ 与 AGENTS.md 迁移过去，工作流随身带走。

⑥ 不这么做的问题 / 坏处

• 机制零散使用 → 每个环节仍要临时组织，效率不成体系。
• 过度追求全自动 → 把提交 / 发布也自动化，一旦判断失误无人拦截，事故放大。
• 搭完不实战迭代 → 工作流停留在理想设计，与真实摩擦脱节。
• 不迁移复用 → 每个新项目重新摸索，浪费已积累的定制。

⑦ 举一反三：三个例子

例 1（基础）：为「修 bug」串一条最小流水线

📌 场景：修一个普通 bug。

✅ 流程：explore 定位 → plan 给修复方案、你确认 → build + /test 补跑测试 → /commitmsg 生成提交信息，你审核后亲自提交。

🔍 讲解：即使是小任务，沿固定节奏走也能保证「先想清楚、改动有验证、提交受控制」。流程轻量但闭环完整。

例 2（进阶）：为「功能开发」做完整定制

📌 场景：一个跨多文件、可能涉及外部平台的新功能。

✅ 流程：规则在场 → explore + 子代理并行搜代码 → plan 出设计 → 确认后 build 实现，中途用 /test、加载相关 Skill → 只读审查 Agent 过一遍 → /commitmsg 收口，提交由你授权。

🔍 讲解：每种机制在最适合的环节出现：子代理做并行搜索、Skill 注入平台知识、只读 Agent 做独立审查。环节与能力一一对应，整条线既快又有多重保险。

例 3（挑战）：把整套工作流迁移到新项目

📌 场景：你开启一个全新项目，希望立刻拥有熟悉的工作节奏。

✅ 做法：复用通用 AGENTS.md 与全局 Agent；把通用 /test、/review、/commitmsg 命令与公共技能复制 / 抽取到可共享位置；只针对新项目补写项目级规则与专属技能。

🔍 讲解：把「通用层」与「项目层」分开沉淀，迁移时只带走通用部分、按项目补差异——这与第 4 章的分层规则思想一致。好的工作流应当是可移植的资产，而非一次性的临时搭建。

---

⑧ 练习题 ×2

练习 1（巩固型）

📝 题目：默写出「新功能开发」工作流中，四个机制分别在哪个环节出现，并指出哪些动作必须保留人工授权。

💡 思路提示：规则常驻；探索 / 规划 / 执行 / 专业环节 / 收口；不可逆动作守闸门。

✅ 参考答案：

- AGENTS.md：全程自动在场；
- Agent：explore 探索、plan 规划、build 执行、只读审查员收口前审查；
- Command：/test 补测试、/review 审查、/commitmsg 生成提交信息；
- Skill：平台接入 / 发布检查等专业环节按需加载。
必须人工授权：修改高风险文件、提交（commit/push）、发布 / 部署。

🔍 讲解：能完整复述这条映射，说明你已具备独立搭建定制工作流的能力。

练习 2（迁移型）

📝 题目：迁移到团队 / 项目管理：设计一条「从需求到上线」的团队流程，要求标准化环节提效、关键节点人工审批。说明这样设计如何兼顾速度与安全。

💡 思路提示：调研、方案评审、开发、测试、上线评审、发布；评审即人工闸门。

✅ 参考答案（示例）：

流程：需求调研（标准化模板）→ 方案评审（人工闸门 1）
→ 开发（标准脚手架 / 命令提效）→ 测试（标准用例与检查清单）
→ 上线评审（人工闸门 2）→ 发布（负责人授权 + 回滚预案）。
兼顾方式：把高频、确定性的环节标准化 / 自动化以提速；
在「方向是否正确」「能否上线」两个高代价节点保留人工审批，
并用回滚预案兜底——速度来自标准化，安全来自闸门。
共性：这正是 OpenCode 定制工作流（执行可自动、风险需授权）
在团队层面的同一套思想。

🔍 讲解：能把个人 AI 工作流迁移到团队流程设计，说明你掌握的是**「标准化提效 + 闸门控险」**这一可广泛迁移的方法论，而不只是工具操作。

---

本章小结

知识点	一句话核心
1. 内置 Agent	build/plan/explore/general 分姿态，开局选对角色
2. 自定义 Agent	frontmatter 限权限 + 正文定身份，机械限制优先
3. Commands	把最佳 Prompt 模板化，$ARGUMENTS 带当下对象
4. Skills	自包含知识包，描述做路由、按需才加载
5. 四者辨析	规则 / 角色 / 话术 / 知识各归其位、正交可组合
6. 组合实战	沿生命周期挂载机制，执行可自动、风险需授权

下一章进入模型层：《模型与供应商》——如何理解模型差异、配置与切换供应商、按任务选择合适模型，在成本、速度与质量之间找到最佳平衡。