把常用流程做成 OpenCode Skill,让它在该用时加载
OpenCode Skills 先展示 ID 和描述,再按需读取 SKILL.md;从一个审查示例说明发现路径、同名覆盖,以及隐藏与禁止加载的区别。

OpenCode Skill 适合保存“遇到这类任务时才需要”的流程。V2 会先把允许使用的 Skill 的 ID、名称和描述展示给模型,真正调用时再加载正文;因此,SKILL.md 已经放进目录,不代表每次对话都读过它。
本文于 2026 年 11 月 21 日核对当前 Skills 文档与 v2.3.2 标签正文,用一个无副作用的审查流程说明配置。示例文件可在本地检查,但本文未运行完整 OpenCode 模型任务。
哪些内容适合放进 Skill
每次都要知道的项目约定,仍放在 AGENTS.md 等常驻指令里;发版前核对、专项审查、某类迁移的步骤,适合放进 Skill。两者的分工可先看规则文件与 Skills。
别把“不得提交凭据”只藏进一个可能没被调用的 Skill;执行权限也要交给权限规则。Skill 的作用是提供流程,不会自动扩大工具或文件访问权。
例如,在演示项目创建:
.opencode/skills/review-public/
├── SKILL.md
└── references/
└── checklist.md
SKILL.md 可以写成:
---
name: review-public
description: Review a public demo change and report correctness risks without editing files
---
Read `references/checklist.md` relative to this skill directory.
Inspect the user-specified diff without changing files or running commands.
Report each supported finding with a file reference and a concrete failure case.
If evidence is insufficient, state what remains unverified.
references/checklist.md 只需列出这类审查真正要问的事,例如“输入为空时会怎样”“错误是否被传回调用方”。不要填进真实客户记录。描述要说明什么时候用、会交付什么,正文再写步骤。
OpenCode 到哪里找 Skills
V2 自动搜索全局的 ~/.config/opencode/skills,也兼容全局与项目的 .claude/skills、.agents/skills,以及项目 .opencode/skills。项目搜索从当前目录向上到项目根目录,包含沿途匹配的目录。
一个常见误会是把 name 当作调用 ID。实际 ID 来自路径:
| 路径 | ID |
|---|---|
.opencode/skills/review-public/SKILL.md | review-public |
.opencode/skills/teams/review-public/SKILL.md | review-public |
.opencode/skills/review-public.md | review-public |
嵌套分组不自动成为 Skill 的命名空间。两个团队各放一个 release/SKILL.md,仍可能撞同一个 release ID。ID 区分大小写;为了跨工具迁移,使用唯一的小写短横线名称更省事。
自动发现还会跳过隐藏项和 node_modules;一个已有 SKILL.md 的目录不会再向里找其他 Skill,搜索深度也有边界。文件藏得太深时,先简化到上面的目录形状,再排查加载。
为什么总加载了旧的那一份
同 ID 的定义按注册顺序选择,后注册的来源生效。官方顺序依次包括内置、.claude/skills、.agents/skills、全局 OpenCode 目录、项目 .opencode/skills,最后是显式 skills 配置项;各来源内部还有祖先目录与数组顺序。
显式目录可以这样加:
{
"$schema": "https://opencode.ai/config.json",
"skills": ["./team-skills"]
}
这里的相对路径按 OpenCode 当前工作目录解析,不是按配置文件所在目录;而多份配置中的 skills 数组会合并。全局配置里写 ./team-skills,换个启动目录就可能找不到原来那一份。
排查时列出所有同 ID 的来源,暂时只保留一个公开演示定义,再恢复需要的来源。不要只改显示名称后假定冲突消失。
隐藏自动推荐,等于禁止使用吗
不等于。metadata.opencode/autoinvoke: false 只是不向模型展示为可选项;Skill 仍已注册,可以按 ID 显式加载。disable-model-invocation: true 有类似效果,两者同时出现时以 opencode/autoinvoke 为准。
真正要限制某些 Skill,需要 skill 权限:
{
"permissions": [
{ "action": "skill", "resource": "*", "effect": "deny" },
{ "action": "skill", "resource": "review-public", "effect": "allow" }
]
}
这会先拒绝所有 Skill,再为 review-public 留出例外。最后匹配的规则生效;也能放进 agents.<id>.permissions,只限制某个 Agent。
#63455 的用户希望像 MCP 一样在界面开关 Skills。截至查阅仍开放,2 条回复;机器人给出的配置办法可由官方文档交叉核对,但不能把这个功能请求写成已上线的统一管理界面。
怎样确认正文和参考文件真的被读了
在公开演示项目输入:
请使用 @review-public 审查我指定的公开 diff。
先说明加载的 Skill ID 和目录,再按其中的检查单给出结论;不要修改文件或运行命令。
查看实际 skill 工具是否以 review-public 加载,再检查是否读取了 references/checklist.md。目录型 Skill 会提供基础路径和部分文件列表,但参考文件内容不会自动一并加载。让模型随口复述描述,不足以证明整套流程执行过。
若未出现,按顺序检查文件名是否精确为 SKILL.md、路径推导的 ID、是否有描述、自动推荐设置、当前 Agent 的权限以及同名覆盖。配置了 API 服务却没回复时,先做连接基础检查,不要把模型请求失败归到 Skill 发现机制。长任务中需要保留的结果,还应写成压缩后可继续的记录。


