第9章 Skills 技能指南
创建 Skill 即为智能体提供针对特定任务的可复用指令。在 `.opencode/skills/
`.opencode/skills/git-release/SKILL.md` ``` --- name: Git Release description: 准备发布说明、版本号升级及 GitHub 发布 ---
工作流程
1. 读取 `references/release-policy.md`。 2. 总结自上一个标签以来的已合并变更。 3. 修改文件前,先提议版本号升级方案。 4. 仅在用户批准版本号后,运行 `scripts/changelog.ts`。 ```
当该 Skill 相关时,OpenCode 会将其作为可用项列出。随后,智能体可以通过 skill 工具加载其指令,而无需将每个 Skill 都添加到每次提示词中。
将相关的脚本、引用文件和模板放在 `SKILL.md` 旁边:
`Files` .opencode/skills/ └── git-release/ ├── SKILL.md ├── scripts/ │ └── changelog.ts └── references/ └── release-policy.md
Skill 内部书写的路径相对于包含 `SKILL.md` 的目录。推荐这种目录形式,因为它为附属文件提供了一个独立的基准目录。
OpenCode 会自动搜索以下位置:
`Scope` | `Sources` ---|--- 全局 | `~/.config/opencode/skills` 全局兼容 | `~/.claude/skills`、`~/.agents/skills` 项目 | `.opencode/skills` 项目兼容 | `.claude/skills`、`.agents/skills`
对于项目源,OpenCode 会从当前目录向上搜索直至项目根目录,并包含每一层中匹配的目录。 每个源可以采用以下两种形式之一:
`Files` skills/ ├── review.md └── git-release/ └── SKILL.md
Markdown 文件必须位于源根目录,例如 `skills/review.md`。 文件名必须严格为 `SKILL.md` 才能嵌套在分组目录中,例如 `skills/git-release/SKILL.md` 或 `skills/teams/release/SKILL.md`。 包含 `SKILL.md` 的目录视为一个 Skill。OpenCode 不会在其中继续搜索更多 Skill。 隐藏文件/目录以及 `node_modules` 会被跳过。 搜索深度限制在源根目录向下六级目录。
在任意 `opencode.json` 或 `opencode.jsonc` 中通过 `skills` 数组添加更多本地目录或 HTTP 目录:
`opencode.jsonc` { "$schema": "https://opencode.ai/config.json", "skills": [ "./team-skills", "~/shared/opencode-skills", "/opt/company-skills", "https://example.com/opencode/skills/", ], }
`Value` | `Resolution` ---|--- 相对路径 | 相对于当前活动的 OpenCode 工作目录,而非配置文件 `~/` 路径 | 相对于当前用户的主目录 绝对路径 | 按原样使用 `http://` 或 `https://` URL | 作为 HTTP 目录加载
所有发现的配置文件条目均会合并。`skills` 数组是追加而非替换。 已连接的 OpenCode Console 工作区也可以共享 Skills。
HTTP 目录是指带有 `index.json` 文件的基础 URL:
`index.json`
{
"skills": [
{
"name": "git-release",
"version": "3",
"files": ["git-release.md", "references/release-policy.md"]
}
]
}
针对该条目,OpenCode 会从 `
`Rule` | `Requirement`
---|---
路径 | 必须是安全的、相对的且同源
条目文件 | 包含 `SKILL.md` 或 `
每个下载的 Skill 目录都会成为一个以其条目命名的源根,因此 `git-release.md` 和 `SKILL.md` 的 ID 均为 `git-release`。
使用 Frontmatter 来命名 Skill 并控制其显示位置:
`SKILL.md` ``` --- name: Git Release description: 准备仓库发布 metadata: opencode/autoinvoke: false ---
准备更新日志、版本升级、标签及发布说明。 ```
`Field` | `Behavior` ---|--- `name` | 显示名称;默认值为基于路径推导的 ID `description` | 摘要,用于向模型展示该 Skill `metadata.opencode/autoinvoke` | 设为 `false` 可将其从模型的可用列表中排除 `disable-model-invocation` | 设为 `true` 效果等同于 `opencode/autoinvoke: false`
运行时所有 Frontmatter 字段均为可选。若希望模型能发现该 Skill,需添加清晰的 `description`;缺少描述的 Skill 不会被列出。 `opencode/autoinvoke: false` 仅将该 Skill 从模型可用列表中隐藏。该 Skill 仍被注册,且可通过 ID 显式加载。若同时设置了 `disable-model-invocation` 和 `opencode/autoinvoke`,则 `opencode/autoinvoke` 优先。V2 接受 `license` 和 `compatibility` 等可移植性字段,但不对其解释。
文件路径决定了 Skill ID。Frontmatter 中的 `name` 仅是显示标签。
`File` | `ID`
---|---
`
ID 是精确且区分大小写的。对于可移植的 Skill,请使用 1-64 个字符的唯一小写 kebab-case ID,并保持其与目录名一致: `^[a-z0-9]+(-[a-z0-9]+)*$` V2 目前不强制执行此模式、1-64 字符建议、`name` 与目录匹配或最大描述长度。
Skill 按 ID 选择。若两个源都定义了 `git-release`,则后注册的源提供的 Skill 会被 OpenCode 加载: `~/.config/opencode/skills/git-release/SKILL.md` ← 较低优先级 `.opencode/skills/git-release/SKILL.md` ← 加载
源按从低到高优先级注册:
1. 内置 Skills 2. `.claude/skills`,先全局再从上向下的祖先目录至当前目录 3. `.agents/skills`,先全局再从上向下的祖先目录至当前目录 4. `~/.config/opencode/skills` 5. 项目 `.opencode/skills`,从项目根目录至当前目录 6. 显式 `skills` 配置条目,按配置优先级和数组顺序
除非有意覆盖之前的 Skill,否则请避免重复 ID。
在每次模型步骤中,OpenCode 会列出拥有 `description` 且未将 `opencode/autoinvoke` 设为 `false` 的允许 Skills。列表仅包含 ID、名称和描述,不包含完整的 Markdown 正文。 模型通过调用 skill 工具并使用精确 ID 来加载 Skill:
`skill tool input` { "id": "git-release" } 随后 OpenCode 会:
1. 选择该 ID 的当前定义。 2. 检查所选智能体的 Skill 权限。 3. 将不含 Frontmatter 的 Markdown 正文添加到对话中。 4. 提供 Skill 的基准目录及最多十个附属文件路径的示例。
若要自行加载 Skill,可在提示词中以 `@skill-id` 提及。 附属文件内容不会自动加载。智能体会在 Skill 指令下读取它们。文件示例仅适用于基于目录的 `SKILL.md` Skill;平面 Markdown Skill 不会获得邻近文件列表。
使用 skill 操作和 Skill ID 作为资源。规则按顺序执行,最后匹配的规则生效:
`opencode.jsonc` { "permissions": [ { "action": "skill", "resource": "*", "effect": "allow" }, { "action": "skill", "resource": "internal-*", "effect": "deny" }, { "action": "skill", "resource": "experimental-*", "effect": "ask" }, ], }
`Effect` | `Behavior` ---|--- `allow` | 无需审批即列出并加载匹配的 Skill `ask` | 列出匹配的 Skill,加载前询问 `deny` | 对模型隐藏匹配的 Skill 并拒绝加载
将相同规则置于 `agents.
例如,该 Skill 的 ID 是 `release`,而非其 Frontmatter 名称 `Git Release`: `.opencode/skills/release/SKILL.md` └─ ID: release
如果 Skill 缺失或加载了错误内容:
1. 确认文件是根级别的 `*.md` 还是名为 `SKILL.md` 的嵌套文件。 2. 检查基于路径推导的、区分大小写的 ID,而非 Frontmatter 名称。 3. 若希望模型发现该 Skill,请添加 `description`。 4. 检查 `opencode/autoinvoke` 及所选智能体的 Skill 权限。 5. 查找定义相同 ID 的后置源。 6. 对于 HTTP 目录,验证 `index.json`、同源文件路径及已变更的版本号。