OpenCode Agents、Skills 与 Commands：打造你的工作流

一个比喻先分清

• Agent：谁来干。它决定系统提示、模型、权限、可见性。
• Skill：怎么干。可复用的知识或流程，需要时被加载。
• Command：一键开干。把一段提示模板变成 /xxx。

三者可以组合：一个 command 指定用哪个 agent、哪个 model；一个 agent 可以加载 skill；skill 里可以引用脚本和参考资料。

Agent：定义"谁来干"

最省事的方式是写一个 markdown，放进 .opencode/agents/（全局则是 ~/.config/opencode/agents/）：

---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-4-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Review the current changes. List findings in severity order with file and line references.

正文就是它的 system prompt。嵌套目录会成为 ID 的一部分：.opencode/agents/team/reviewer.md → team/reviewer。

模式决定它能在哪跑：

子代理有全新上下文，在前后台子会话里跑。父代理的 subagent 权限决定它能启动哪些子代理，子代理则用自己配置的权限——不是父权限的子集。

这里有个值得用的技巧：用权限反向塑造"专家"。上面的 reviewer 明确 deny 了 edit 和 shell，它就只能看、不能改。让"审查者"物理上无法改代码，比在提示里写"请不要改"可靠得多。

其他常用字段：

• model：provider/model#variant；
• system：非空会替换 provider 的基础提示（markdown 里就写正文）；
• steps：最大模型步数，到最后一步会移走工具并要求它用文字总结；
• hidden：从列表和子代理目录里隐藏（控制可见性，不是安全边界）；
• disabled：在该配置层移除某个内置或自定义 agent；
• color：UI 颜色。

覆盖内置 agent 用同名 ID，例如给 build 加一条只针对它的权限：

{
  "agents": {
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git push *", "effect": "ask" }
      ]
    }
  }
}

合并规则：后出现的标量覆盖前面的，请求映射按键合并，权限规则追加。全局权限先于 agent 权限，所以 agent 规则能细化它们。

Skill：可复用的"怎么干"

一个 skill 是 .opencode/skills/<skill-id>/SKILL.md：

---
name: Git Release
description: Prepare release notes, version bumps, and GitHub releases
---

## Workflow

1. Read `references/release-policy.md`.
2. Summarize merged changes since the previous tag.
3. Propose the version bump before changing files.
4. Run `scripts/changelog.ts` only after the user approves the version.

把脚本、参考文档、模板放在 SKILL.md 旁边，路径以 SKILL.md 所在目录为基准。用目录形式，这样配套文件有独立的根目录。

它不会把每个 skill 都塞进每次提示，而是先广告 ID、名称、描述，模型需要时用 skill 工具按 ID 加载正文，并拿到最多十个配套文件路径（内容仍要它自己去读）。这个"按需加载"是 skill 的核心价值。

发现位置（含兼容）：

兼容目录意味着你为 Claude Code 写的 skill，OpenCode 也能直接发现。这对同时用两个工具的团队很实用。

两个必须记住的细节：

1. ID 由路径决定，不是 frontmatter 的 name。 SKILL.md 的 ID 是它所在目录名；git-release.md 的 ID 是 git-release。ID 区分大小写。
2. metadata.opencode/autoinvoke: false 只把 skill 从模型的可用列表里隐藏，它仍然可以被显式按 ID 加载。

对有副作用的 skill，建议关掉自动调用，只让你手动触发。方法是在 frontmatter 里设 slash: false（从交互命令目录隐藏）或用 autoinvoke 控制，并用 skill 权限把不想给的技能直接 deny 掉：

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "allow" },
    { "action": "skill", "resource": "internal-*", "effect": "deny" }
  ]
}

Command：把重复的提示变成 /命令

标准写法是 .opencode/commands/review.md：

Review $ARGUMENTS for bugs and missing tests.

然后在 TUI 里：

/review src/auth.ts

它会提交 Review src/auth.ts for bugs and missing tests.。嵌套路径变成带 / 的命令名：.opencode/commands/team/review.md → /team/review。

参数有两种占位：

• $ARGUMENTS：完整参数串原样填入；
• $1、$2……：位置参数，单/双引号可以分组（引号会被去掉）。

最高编号的占位符会吃掉它之后的所有内容；缺失的位置变成空串。如果模板里没有任何占位符，OpenCode 会把非空参数追加在空行之后。

命令还能指定 agent 和 model：

---
description: Review code for correctness
agent: plan
model: anthropic/claude-sonnet-4-5#high
---

Review $ARGUMENTS. Report bugs first.

模型选择顺序：命令的 model > 所选 agent 的模型 > 当前会话模型。运行 /plan migration 这类命令会先把当前会话切到 plan 再提交提示。

有个强但危险的功能——在命令里嵌 shell：

---
description: Review the staged diff
---

Review this diff:

!`git diff --stat && git diff`

它在提交提示前运行 shell，并插入输出。注意：shell 块在 agent 的工具权限流程之外运行。 官方明确警告过，只在你完全信任模板来源时使用，而且不要把不可信参数放进 shell 块。

想让命令在后台子会话跑，设 subagent: true：

---
description: Audit changes
agent: general
subagent: true
---

Audit $ARGUMENTS for bugs and missing tests.

父会话保持可用、保留自己的 agent 和模型；子会话完成或失败后结果回传。

怎么选：一张对照

一个务实建议：优先写成仓库里的 markdown，而不是 JSON。 它们能被 git 跟踪、能 review、能跨工具复用；JSON 配置适合少量全局设置，不适合承载会演化的流程。

小结

• agent 管"谁来干"，skill 管"怎么干"，command 管"一键开干"。
• 用权限塑造专家：deny edit/shell，比提示词里写"不要改"可靠。
• skill 的 ID 来自路径，不是 name；有副作用的技能关掉自动调用。
• 命令的 shell 块在权限流程之外执行，来源可信才用。
• .claude/skills、.agents/skills 会被自动发现，是跨工具复用技能的关键。

下一篇讲扩展与集成：插件、MCP、权限规则与快照回滚——覆盖你把它接进真实工程时最需要的那几块。