进阶 opencode.ai 2026-11-11 16:13:22 · 19 阅读

第9章 Skills 技能指南

创建 Skill 即为智能体提供针对特定任务的可复用指令。在 `.opencode/skills/` 目录下放置一个 `SKILL.md` 文件,并在 `description` 中描述其适用场景。

`.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 会从 `/git-release/` 下载每个文件。

`Rule` | `Requirement` ---|--- 路径 | 必须是安全的、相对的且同源 条目文件 | 包含 `SKILL.md` 或 `.md`(例如 `git-release.md`) 更新 | 文件变更时递增版本号,以便 OpenCode 刷新缓存

每个下载的 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` ---|--- `/git-release.md` | `git-release` `/git-release/SKILL.md` | `git-release` `/teams/release/SKILL.md` | `release`

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..permissions` 下,即可仅应用于单个智能体。

例如,该 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`、同源文件路径及已变更的版本号。

评论 (0)