第七章：自定义命令、规则与上下文
本章讲解三类「让 OpenCode 更懂你的项目、更少重复劳动」的定制：自定义命令（Commands）、规则文件（AGENTS.md / instructions）、以及 Agent Skills。它们都是纯文本、可提交进 Git、可团队共享，并且对省 Token 大有帮助——因为高质量的上下文能减少来回澄清与返工。
7.1 自定义命令（Commands）
自定义命令把「常用提示词」固化为 /命令名，在 TUI 里一键触发。它们与内置命令并列，同名时覆盖内置命令。
用 Markdown 定义（推荐）
放在 .opencode/commands/（项目）或 ~/.config/opencode/commands/（全局），文件名即命令名：
---
description: 运行测试并生成覆盖率报告
agent: build
model: anthropic/claude-haiku-4-5
---运行完整测试套件并生成覆盖率报告，列出所有失败项。
聚焦失败的测试并给出修复建议。
之后在 TUI 输入 /test 即可。frontmatter 是配置，正文是发给 LLM 的模板。
用 JSON 定义
{"$schema": "https://opencode.ai/config.json","command": {"test": {"template": "运行完整测试套件并生成覆盖率报告，列出所有失败项。\n聚焦失败的测试并给出修复建议。","description": "运行测试并生成覆盖率报告","agent": "build","model": "anthropic/claude-haiku-4-5"},"component": {"template": "创建一个名为 $ARGUMENTS 的 React 组件，支持 TypeScript，包含正确的类型与基础结构。","description": "创建新组件"}}
}
命令模板的特殊语法
1）参数占位符
$ARGUMENTS：替换为命令后的全部参数。$1$2$3…：按位置取参。
---
description: 创建带内容的新文件
---在目录 $2 下创建名为 $1 的文件，内容如下：$3
调用：/create-file config.json src "{ \"key\": \"value\" }"。
2）注入 Bash 输出
用 反引号包裹命令并在前面加 !（即 ! + 反引号命令反引号）把命令输出注入提示。命令在项目根目录执行：
---
description: 审查最近的改动
---最近的 git 提交：
!`git log --oneline -10`请审查这些改动并给出改进建议。
3）引用文件内容
用 @ 加文件名，把文件内容自动并入提示：
---
description: 审查组件
---审查 @src/components/Button.tsx 这个组件，检查性能问题并给出改进建议。
命令配置项
| 字段 | 必填 | 说明 |
|---|---|---|
template |
是 | 发给 LLM 的提示模板 |
description |
否 | TUI 中显示的描述 |
agent |
否 | 指定执行该命令的 Agent；若是子代理则默认以子任务方式触发 |
subtask |
否 | 设 true 强制以子代理（子任务）方式运行，不污染主上下文 |
model |
否 | 覆盖该命令使用的模型 |
subtask: true+ 便宜的model是命令级省 Token 的黄金组合：把「跑测试并分析」「审查改动」这类重读取、重输出的任务丢进子会话用小模型完成，主会话只拿结论。
7.2 规则文件 AGENTS.md
AGENTS.md 类似 Cursor 的 rules，是注入到 LLM 上下文、用于定制其在你项目中行为的指令文件。
初始化
在 TUI 运行 /init：它扫描仓库关键文件，必要时问几个问题，然后创建/更新 AGENTS.md，聚焦未来会话最常需要的信息：
- 构建、lint、测试命令；命令顺序与关键验证步骤；
- 仅看文件名看不出的架构与目录结构；
- 项目专属约定、环境怪癖、操作「坑」；
- 对既有规则源（Cursor / Copilot rules）的引用。
若已有 AGENTS.md，/init 会就地改进而非粗暴替换。建议把它提交进 Git 与团队共享。
示例
# SST v3 Monorepo 项目这是一个使用 TypeScript 的 SST v3 monorepo，用 bun workspaces 管理包。## 项目结构
- `packages/` - 所有 workspace 包（functions、core、web 等）
- `infra/` - 基础设施定义，按服务拆分（storage.ts、api.ts、web.ts）
- `sst.config.ts` - SST 主配置，使用动态导入## 代码规范
- TypeScript 开启 strict 模式
- 共享代码放 `packages/core/`，配置正确的导出
- 函数放 `packages/functions/`## Monorepo 约定
- 用 workspace 名导入共享模块：`@my-app/core/example`
多位置与优先级
AGENTS.md 可来自多个位置，用途不同：
- 项目级：项目根
AGENTS.md，只在该目录及子目录生效，随项目共享。 - 全局级：
~/.config/opencode/AGENTS.md，对所有会话生效，适合放个人规则（不入 Git）。
启动时按此顺序查找，每类「首个命中者生效」：
- 从当前目录向上回溯的本地文件（
AGENTS.md、CLAUDE.md）； - 全局
~/.config/opencode/AGENTS.md； - Claude Code 文件
~/.claude/CLAUDE.md（除非禁用）。
兼容 Claude Code
从 Claude Code 迁移者可直接复用其约定作为回退：项目 CLAUDE.md（无 AGENTS.md 时）、全局 ~/.claude/CLAUDE.md、以及 ~/.claude/skills/。可用环境变量关闭：
export OPENCODE_DISABLE_CLAUDE_CODE=1 # 关闭全部 .claude 支持
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1 # 仅关闭 ~/.claude/CLAUDE.md
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 # 仅关闭 .claude/skills
7.3 复用既有规则：instructions
不想把规则都搬进 AGENTS.md？用 instructions 引用既有文件（支持路径、glob、甚至远程 URL），它们会与 AGENTS.md 合并：
{"$schema": "https://opencode.ai/config.json","instructions": ["CONTRIBUTING.md","docs/guidelines.md",".cursor/rules/*.md","packages/*/AGENTS.md","https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]
}
远程指令以 5 秒超时拉取。对 monorepo 或有共享规范的项目，用 glob（如 packages/*/AGENTS.md）比手写引用更易维护。
按需加载外部文件（省 Token 技巧）
OpenCode 不会自动解析 AGENTS.md 里的文件引用，但你可以在 AGENTS.md 里教它「按需懒加载」，避免一次性把所有规则塞进上下文：
## 外部文件加载关键：当遇到形如 @rules/general.md 的文件引用时，用 Read 工具按需加载它们，
它们只与当前具体任务相关。- 不要预先加载所有引用——按实际需要懒加载
- 加载后将内容视为强制指令，覆盖默认行为
- 必要时递归跟随引用## 开发指南
TypeScript 风格与最佳实践：@docs/typescript-guidelines.md
React 组件架构与 hooks：@docs/react-patterns.md
这样既能模块化、复用规则，又能让 AGENTS.md 保持精简、只在需要时才消耗 Token。
7.4 Agent Skills（SKILL.md）
Skills 让 OpenCode 从仓库或主目录按需发现可复用的操作流程。它们通过原生 skill 工具被「看到」，只有在需要时才加载完整内容——天然省 Token。
存放位置
每个技能一个文件夹，内含 SKILL.md。搜索位置包括：
- 项目：
.opencode/skills/<name>/SKILL.md - 全局：
~/.config/opencode/skills/<name>/SKILL.md - Claude 兼容：
.claude/skills/<name>/SKILL.md、~/.claude/skills/<name>/SKILL.md - agents 兼容：
.agents/skills/<name>/SKILL.md、~/.agents/skills/<name>/SKILL.md
frontmatter 规范
---
name: git-release
description: 规范化的 Git 发版流程：打 tag、生成 changelog、推送 release
---执行发版时，按以下步骤……
仅识别这些字段：name（必填）、description（必填）、license、compatibility、metadata（字符串映射），其它字段被忽略。name 必须为 1–64 字符、小写字母数字、用单个连字符分隔、不以 - 开头或结尾、不含连续 --，且与所在目录名一致；description 为 1–1024 字符，要写得足够具体，方便 Agent 正确选用。
Skill 与「直接把所有流程写进 AGENTS.md」相比，最大优势是延迟加载：平时不占上下文，用到才加载，对长流程/多技能场景省 Token 效果明显。
7.5 小结
本章你学会了三种把项目知识注入 OpenCode 的方式：自定义命令（含参数、Bash 注入、文件引用、子任务分流）、规则文件（AGENTS.md + instructions + 懒加载技巧）、以及按需加载的 Skills。它们共同让模型「少问、少错、少返工」，本质上也是一种 Token 优化。下一章进入工具、权限与 MCP 扩展。