OpenCodeAgent SkillsSKILL.mdNbility

把常用流程做成 OpenCode Skill,让它在该用时加载

OpenCode Skills 先展示 ID 和描述,再按需读取 SKILL.md;从一个审查示例说明发现路径、同名覆盖,以及隐藏与禁止加载的区别。

查看接入文档
把常用流程做成 OpenCode Skill,让它在该用时加载

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。项目搜索从当前目录向上到项目根目录,包含沿途匹配的目录。

全局来源、兼容目录与项目来源汇入目录,再按 ID 选择定义

一个常见误会是把 name 当作调用 ID。实际 ID 来自路径:

路径ID
.opencode/skills/review-public/SKILL.mdreview-public
.opencode/skills/teams/review-public/SKILL.mdreview-public
.opencode/skills/review-public.mdreview-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 会提供基础路径和部分文件列表,但参考文件内容不会自动一并加载。让模型随口复述描述,不足以证明整套流程执行过。

确认路径与 ID、检查描述和权限、核对实际加载、验证参考文件读取

若未出现,按顺序检查文件名是否精确为 SKILL.md、路径推导的 ID、是否有描述、自动推荐设置、当前 Agent 的权限以及同名覆盖。配置了 API 服务却没回复时,先做连接基础检查,不要把模型请求失败归到 Skill 发现机制。长任务中需要保留的结果,还应写成压缩后可继续的记录。

相关文章

用 Nbility 跑通你的 Agent 工作流

获取 API Key,统一接入 OpenAI 兼容模型和开发工具。

获取 API Key