oc/skills/opencode-config/SKILL.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
opencode-config	配置 opencode 自身 (agents / skills / MCP servers / custom tools / 内置工具权限) 的工作流与速查。基于 opencode 官方中文文档 (agents、skills、mcp-servers、custom-tools、tools 五篇)。Use ONLY when 用户要创建/修改 opencode.json、子代理文件、SKILL.md、MCP server 配置、.opencode/tools/ 自定义工具、或调整工具权限策略;不用于改业务代码或运行应用。	MIT	opencode	audience scope source opencode maintainers opencode-self-config https://opencode.ai/docs/zh-cn/

opencode-config

opencode 自身配置的导航 + 摘要 skill。详细字段/示例/边界场景放 references/,按需加载,避免主文件膨胀。

何时加载我

• 用户说"加个子代理 / 改 opencode.json / 配置 MCP / 写个自定义工具 / 调权限"
• 用户要求排查"skill 没显示 / MCP 连不上 / 自定义工具不生效"
• 用户给 opencode 官方文档链接,要求落地

反向场景 (不要加载): 改 RuoYi 业务、跑 mvn install、查 MySQL、调小程序 — 这些走 ruoyi-cs-platform / dba 子代理。

文件位置约定 (本仓库)

类别	路径	备注
主配置	opencode.json 或 opencode.jsonc	必须含 "$schema": "https://opencode.ai/config.json"
子代理 (文件)	.opencode/agent/<name>.md 或 .opencode/agents/<name>.md	文件名即 agent 名
技能	.opencode/skill/<name>/SKILL.md	frontmatter name 与目录名一致
技能 (外部)	.agents/skills/<name>/SKILL.md	兼容 Claude 风格
MCP	写在 opencode.json 的 mcp.<server>	不用单独文件
自定义工具	.opencode/tools/<name>.ts	文件名即工具名,@opencode-ai/plugin 的 tool()
插件	.opencode/plugin/*.ts 或 opencode.json 的 plugin 数组	TS 文件自动发现

配置只读一次,改完任何 opencode 配置文件都需告诉用户退出并重启 opencode 才生效。

5 篇官方文档 → 5 个子文件 (按需 read 加载)

子文件	对应官方页	涵盖内容
references/01-agents.md	agents	主/子代理、内置代理 (build/plan/general/explore/scout)、JSON vs Markdown 配置、description/temperature/steps/prompt/model/tools/permission/mode/hidden/task/color/top_p、文档/安全审计样例
references/02-skills.md	skills	SKILL.md frontmatter (name/description 必填)、name 正则 ^[a-z0-9]+(-[a-z0-9]+)*$、description 1-1024 字符、发现路径、glob 通配符权限、agent 级 skill 权限覆盖、禁用 skill 工具、加载问题排查
references/03-mcp-servers.md	mcp-servers	mcp 段结构、local (type:"local", command 数组, environment) / remote (type:"remote", url, headers) / OAuth (auto/preregister/manual)、enabled: false 临时禁用、按 agent 控制 MCP 工具 (mymcp_* glob)、Context7/Sentry/gh_grep 示例
references/04-custom-tools.md	custom-tools	.opencode/tools/*.ts、tool() 辅助函数 + Zod (tool.schema)、多导出命名 <file>_<export>、context (agent/sessionID/messageID/directory/worktree)、与内置工具同名时覆盖、Python 等非 TS 实现
references/05-tools.md	tools	12 个内置工具清单:bash/edit/write/read/grep/glob/lsp/patch/skill/todowrite/webfetch/websearch/question,以及 permission 字段 (allow/ask/deny)、glob 通配符、.ignore 文件覆盖 .gitignore

加载方式: 用 read 工具读 references/0X-xxx.md 的完整内容。主文件只保留"我要做 X,先读哪个引用"的导航。

速查决策树

用户想…
├─ 加子代理 ──────────→ references/01-agents.md §"Markdown 形式"
│                         落地: .opencode/agent/<name>.md (frontmatter + prompt)
├─ 改 opencode.json ──→ 对应类别的 references/ + 校验 $schema
├─ 加 skill ──────────→ references/02-skills.md §"编写 frontmatter"
│                         落地: .opencode/skill/<name>/SKILL.md (主文件) + 视情况 references/ scripts/ templates/
├─ 加 MCP server ─────→ references/03-mcp-servers.md §"本地/远程/OAuth"
│                         落地: opencode.json 的 mcp.<name>
├─ 写自定义工具 ─────→ references/04-custom-tools.md §"结构/参数/上下文"
│                         落地: .opencode/tools/<name>.ts (import { tool } from "@opencode-ai/plugin")
├─ 调工具权限 ───────→ references/05-tools.md §"配置" + references/01 §"权限"
│                         落地: opencode.json 的 permission 段
└─ 排查加载问题 ─────→ references/02 §"排查加载问题" / references/03 §"OAuth 调试" / references/05 §"忽略模式"

硬约束 (违反 opencode 拒启 / 静默失败)

1. JSON Schema: opencode.json 顶部必须 "$schema": "https://opencode.ai/config.json",未知顶层键 ConfigInvalidError。
2. SKILL.md frontmatter: name 必填 + 1-64 字符 + 小写连字符正则;description 必填 + 1-1024 字符。无 description 的 skill 从模型视野过滤掉,不报错也不出现。
3. MCP command 是字符串数组,不是单个字符串;type: local|remote 必填。
4. mcp[name].disabled 静默: 想要临时关 → enabled: false;彻底删 → 从 mcp 段移除。
5. Skill 权限拒绝后: 代理在 <available_skills> 里看不到该 skill,会安静地以为不存在。
6. MCP 工具 glob: 禁用某 server 全部工具用 "<server>_*": false,因为工具注册时带 server 前缀。
7. todowrite 默认对子代理禁用: 要用就 agent.<name>.tools.todowrite: true。
8. LSP 工具: 需 OPENCODE_EXPERIMENTAL_LSP_TOOL=true (或 OPENCODE_EXPERIMENTAL=true)。
9. websearch 工具: 需 OpenCode 提供商,或 OPENCODE_ENABLE_EXA=1|true。
10. 配置热重载: 不支持 — 改完必须告诉用户退出重启 opencode。

写配置的标准动作

1. 读对应 references/ 子文件 拿到字段/示例/边界。
2. 校验字段 — 不确定就 webfetch https://opencode.ai/config.json 看 schema。
3. 保留用户原有字段 — 只动用户明确指出的部分,别顺手改 model/username/keys。
4. 加 $schema — 帮编辑器即时校验。
5. 写完后 — 输出"修改清单 + 提醒用户退出重启 opencode"。

相关 skill (本仓库已存在)

• ruoyi-cs-platform — 业务入口 skill,改 RuoYi 代码前必读
• customize-opencode (内置) — opencode 自身配置速查,与本 skill 互补但本 skill 更细、含子文件分页
• .qwen/skills/* — 历史 Qwen 风格 skill,与 .opencode/skill/* 并存,迁移时按需搬运