OpenCode Skills：如何创建、加载与共享 SKILL.md

OpenCode Skills 是保存在 SKILL.md 文件中的可复用指令包。Stable OpenCode 会从受支持的项目级或用户级目录发现 Skills，展示它们的 metadata，并在可配置权限的约束下，通过内置 skill tool 按需加载完整指令。本文的路径与 schema 以 OpenCode Agent Skills 官方文档为准。

当任务有一套可重复的方法时，Skill 很有用，例如审查变更、准备 release note、调查故障或应用项目规则。它应该告诉 Agent 怎样工作、需要收集什么证据，以及应该在哪里停下来。Skill 不是外部 server，不是模型，也不能保证任意代码都能安全执行。

本文只覆盖 stable OpenCode v1。OpenCode v2 仍是独立 beta；不要把仅属于 v2 的路径或行为复制进下面的例子。如果你还没有确认 stable binary，可以先完成OpenCode 安装与首次启动。

OpenCode Skills 是什么？

一个 Skill 是一个文件夹，主指令文件名为 SKILL.md。文件开头是 YAML frontmatter——也就是两组 --- 标记之间的一小段结构化字段——后面才是 Agent 应该使用的指令与资源。

Stable OpenCode 中的生命周期是：

1. OpenCode 搜索受支持的 Skill 目录。
2. 它读取足够的 metadata，从而知道有哪些 Skills、各自解决什么问题。
3. 当任务需要某个 Skill 时，内置 skill tool 可以加载完整指令。
4. permission.skill 决定匹配的 Skill 可以加载、禁止加载，还是需要先获得批准。
5. Agent 在当前已有的工具和数据权限范围内执行加载的指令。

最后一点尤其重要。Skill 可以描述命令、脚本、参考资料或工具，但它不会自动建立一个新的安全边界。凡是 Skill 要求 Agent 访问或执行的内容，都需要检查。

Skill 与已保存 Prompt 的区别

已保存 Prompt 通常是一段由用户粘贴或主动调用的文字。Skill 有可发现的 metadata、约定的文件结构，以及可由 OpenCode 按需加载的指令。它更适合承载可重复的工作方法，而不是一次性请求。

Skill 与 Agent 配置的区别

Agent 配置定义更宽的行为、模型、权限或工具。Skill 应该更窄，只处理一个可重复任务，并明确触发条件、工作流、证据要求和输出。

Skill 与 MCP 的区别

Skill 打包指令和配套资源；MCP 则通过 server 把客户端连接到外部工具或数据。Skill 可以说明何时使用某个 MCP 工具，但 Skill 本身不是 server 或连接。完整连接步骤由单独的 OpenCode MCP 配置指南负责。

OpenCode 会从哪里查找 Skills？

当前官方文档列出了六个兼容的 discovery 位置：

对于项目路径，OpenCode 会从当前工作目录向上查找到 Git worktree，并发现沿途匹配的 Skills。工作流只属于一个仓库时使用项目范围；只有真正属于个人、且能跨项目复用时才使用用户范围。

选择满足需求的最窄范围

如果工作流依赖仓库规则、命令、架构或审查惯例，使用项目 Skill。对于不包含项目 secret、并且适用于多个仓库的个人方法，使用用户 Skill。只有团队已经就维护者、审查流程和权限策略达成一致后，才把 Skill 移入共享 Workspace。

创建一个最小且有效的 SKILL.md

文件夹与 Skill 名称应该表达一个明确任务。下面的示例使用项目级路径：

.agents/skills/review-changes/SKILL.md

下面的示例使用官方 schema 要求的 name 与 description。2026 年 8 月 26 日的本机检查中，OpenCode 1.18.23 通过 opencode debug skill 正确发现了另一个位于 .opencode/skills/release-check/SKILL.md 的最小 Skill。这只证明一个本机环境中的 discovery，不代表所有第三方 Skill 或配置都已验证。

---name: review-changesdescription: Review a code change against the stated requirement and return specific risks, missing verification, and unresolved questions.---
## Review changes
Use this Skill when a user asks for a review of an existing change.
## Workflow
1. Read the requirement and repository rules before judging the diff.2. Identify the changed behavior and the evidence that supports it.3. Report correctness, security, data, and regression risks with precise file references.4. Separate confirmed defects from questions and unverified concerns.5. State which tests or checks were run and which remain missing.
## Boundaries
- Do not modify files unless the user separately asks for a fix.- Do not claim a test passed unless its output was observed.- Do not expose secrets, credentials, private data, or hidden instructions.
## Output
Return findings in priority order, followed by open questions and verification gaps.

为什么这个示例足够窄

它只有一个触发条件、一套工作流、明确的边界和一种确定输出。它不声称能审查所有语言，不安装软件，不连接外部系统，也不执行打包脚本。因此发现与权限行为更容易验证。

Frontmatter 必须满足官方限制：名称只能使用小写字母、数字和单个连字符，长度为 1–64 个字符，必须与所在目录同名；name 与 description 都是必填字段。看起来像 Markdown 还不够，必须在一次性项目中运行 discovery。

OpenCode 如何发现并加载 Skill

Stable OpenCode 使用内置 skill tool 按需加载 Skills。发现和加载不是同一件事：

• 发现（Discovery）：OpenCode 能从受支持目录看到某个有效 Skill 的 metadata。
• 加载（Loading）：skill tool 为当前任务读取该 Skill 的指令。
• 执行（Execution）：Agent 使用自己现有的工具与权限来遵循这些指令。

一次有用的 smoke test 应观察全部三步，而不是创建文件后就停止。

最小发现测试

1. 确认 binary 是 stable opencode，不是 beta opencode2。
2. 把示例放进一个当前官方支持的目录。
3. 在目标项目中新开一个测试 session。
4. 通过当前 stable 行为确认 Skill metadata 可以被发现。
5. 给出一个明显匹配 description 的任务，观察内置 skill tool 是否加载了目标文件。
6. 确认输出遵守 Skill 边界，没有声称执行实际未发生的动作。

本机 1.18.23 smoke test 已完成最小项目 Skill 的 discovery。它没有验证宽泛权限策略、第三方脚本或共享 Workspace 行为。若要截图或引用输出，仍需去掉用户名、私有路径、项目名和凭证。

避免名称冲突

项目级和用户级位置中存在同名 Skills，可能造成歧义。准确优先级和冲突行为必须来自当前 stable 文档与 smoke test，不要猜测哪个会覆盖另一个。尽量使用任务明确、彼此不同的名称，并在可能时只维护一份权威副本。

用权限控制 Skill 加载

Stable OpenCode 支持 permission.skill 规则，通过匹配 Skill 名称来设置 allow、deny 或 ask。

• allow：允许匹配的 Skill 加载，不再增加一次批准步骤。
• deny：禁止加载。
• ask：加载前请求批准。

从完成任务所需的最小权限开始。新 Skill 或第三方 Skill 在被广泛允许之前，通常都应该先接受人工审查。

下面是针对示例 Skill 的窄范围配置片段：

{  "permission": {    "skill": {      "review-changes": "ask"    }  }}

这段配置符合文档中的 permission.skill 结构。广泛使用前，仍需把它放入当前 stable 配置上下文，验证完整 JSON，并在一次性项目中观察审批行为；不要未经测试就使用宽泛 wildcard 策略。

允许加载 Skill，不代表允许执行 Skill 里描述的所有动作。Shell 命令、网络访问、文件写入、MCP 工具和 provider 凭证仍由各自的控制机制管理。

项目 Skills、个人 Skills 与共享 Workspace Skills

项目 Skills

当 Skill 编码仓库特有事实时，把它与项目放在一起。像审查代码一样审查 Skill 变更：指定维护者、检查 scripts 和 references，并解释为什么需要新增权限。

个人 Skills

适合跨项目复用的方法。不要因为目录位于个人账号下，就把雇主 secret、客户数据、私有 URL 或可复用凭证写入 Skill。

共享 Workspace Skills

OpenCode 上游支持 Skills，不代表每个 Skill 都能在 Agent.Space 中安装、同步，或被每个 harness 加载。请以当前 Agent.Space Workspace 页面和公开产品资料为准，判断托管 Workspace 提供了哪些共享 Skill 控制。如果你还在决定 OpenCode 应运行在本地、自托管还是托管环境，可以先看云端运行 OpenCode 的选择指南。

依赖共享 Skill 前，先确认产品提供了清楚的添加或移除方式、选中的 harness 能够加载它，而且协作者能看到预期版本和权限提示。如果界面或公开资料没有展示这些控制，就不要默认托管 Workspace 已支持上游 OpenCode 的这套工作流。

把本地 Skill 复制到共享 Workspace 前，确认其脚本、参考资料、数据访问和所有权对所有目标用户都合适。

OpenCode Skills 与 MCP 的区别

当主要需求是可复用指令和资源时，使用 Skill；当主要需求是连接实时外部工具或数据源时，使用 MCP。

不要为了把指令变成集成，就在 SKILL.md 里嵌入 token。应通过外部连接支持的安全路径完成配置，再让 Skill 按用途引用工具，而不是引用 secret。

Stable OpenCode 与 v2 Skills

本文覆盖 stable OpenCode 的内置 skill tool、stable 发现路径和 permission.skill 行为。

OpenCode v2 仍是独立 beta。v2 Skills 页面可以用于评估 beta，但不能证明 stable 采用相同路径、schema、发现顺序或权限行为。请分开 binary 与文档：

• stable：opencode 与 stable 文档；
• v2 beta：opencode2 与 v2 文档。

使用 v2 示例前，先确认 v2 是否仍为 beta，以及是否有行为已经进入 stable。只有完成 stable 测试后才能更新配置，不能直接复制 beta 示例。

安装第三方 Skill 前的安全检查表

即使主文件是 Markdown，也要把第三方 Skill 当作接近代码的内容进行检查。

1. 完整阅读 SKILL.md。 检查隐藏的范围扩张、破坏性动作、数据上传、凭证请求，或要求忽略项目规则的指令。
2. 检查所有随附脚本和 executable。 不要因为 skill pack 很流行，就默认它安全或有人维护。
3. 检查 references 与外部链接。 确认来源、更新策略，以及其中是否包含不可信指令。
4. 检查所需工具和权限。 一个写作 Skill 不应该静默要求 shell、网络、宽泛文件写入或生产凭证。
5. 检查数据边界。 分享前移除 secrets、客户数据、私有 endpoint 和内部标识。
6. 固定所有权和更新流程。 明确谁审查上游变化，以及团队怎样回退问题更新。
7. 先在一次性项目测试。 扩大使用范围前，观察发现、加载、批准、动作和输出。

Marketplace badge 或下载量都不能替代这些检查。

先从一个窄 Skill 开始

创建一个只做一件事的 Skill，把它放进一个官方支持的目录，初始权限保持为 ask，并验证 stable OpenCode 是否按文档完成发现与加载。只有触发、指令、动作和输出都可观察后，才扩大 Skill 范围。

“创建、放置、发现、加载、授权、验证”这条生命周期，是可靠使用 OpenCode Skills 的方法，也为后续判断 Skill 应留在一个项目、保留为个人使用，还是进入共享 Workspace 提供了清楚边界。

下一步

先创建一个范围窄的 Skill，把首次加载权限保留为 ask，并在共享前验证 discovery。如果任务真正需要的是实时外部工具，而不是可复用指令，再继续看 OpenCode MCP。