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 中的生命周期是:
- OpenCode 搜索受支持的 Skill 目录。
- 它读取足够的 metadata,从而知道有哪些 Skills、各自解决什么问题。
- 当任务需要某个 Skill 时,内置
skilltool 可以加载完整指令。 permission.skill决定匹配的 Skill 可以加载、禁止加载,还是需要先获得批准。- 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 移入共享工作空间。
创建一个最小且有效的 SKILL.md
文件夹与 Skill 名称应该表达一个明确任务。下面的示例使用项目级路径:
下面的示例使用官方 schema 要求的 name 与 description。2026 年 8 月 26 日的本机检查中,OpenCode 1.18.23 通过 opencode debug skill 正确发现了另一个位于 .opencode/skills/release-check/SKILL.md 的最小 Skill。这只证明一个本机环境中的 discovery,不代表所有第三方 Skill 或配置都已验证。
为什么这个示例足够窄
它只有一个触发条件、一套工作流、明确的边界和一种确定输出。它不声称能审查所有语言,不安装软件,不连接外部系统,也不执行打包脚本。因此发现与权限行为更容易验证。
Frontmatter 必须满足官方限制:名称只能使用小写字母、数字和单个连字符,长度为 1–64 个字符,必须与所在目录同名;name 与 description 都是必填字段。看起来像 Markdown 还不够,必须在一次性项目中运行 discovery。
OpenCode 如何发现并加载 Skill
Stable OpenCode 使用内置 skill tool 按需加载 Skills。发现和加载不是同一件事:
- 发现(Discovery):OpenCode 能从受支持目录看到某个有效 Skill 的 metadata。
- 加载(Loading):
skilltool 为当前任务读取该 Skill 的指令。 - 执行(Execution):Agent 使用自己现有的工具与权限来遵循这些指令。
一次有用的 smoke test 应观察全部三步,而不是创建文件后就停止。
最小发现测试
- 确认 binary 是 stable
opencode,不是 betaopencode2。 - 把示例放进一个当前官方支持的目录。
- 在目标项目中新开一个测试 session。
- 通过当前 stable 行为确认 Skill metadata 可以被发现。
- 给出一个明显匹配 description 的任务,观察内置
skilltool 是否加载了目标文件。 - 确认输出遵守 Skill 边界,没有声称执行实际未发生的动作。
本机 1.18.23 smoke test 已完成最小项目 Skill 的 discovery。它没有验证宽泛权限策略、第三方脚本或共享工作空间行为。若要截图或引用输出,仍需去掉用户名、私有路径、项目名和凭证。
避免名称冲突
项目级和用户级位置中存在同名 Skills,可能造成歧义。准确优先级和冲突行为必须来自当前 stable 文档与 smoke test,不要猜测哪个会覆盖另一个。尽量使用任务明确、彼此不同的名称,并在可能时只维护一份权威副本。
用权限控制 Skill 加载
Stable OpenCode 支持 permission.skill 规则,通过匹配 Skill 名称来设置 allow、deny 或 ask。
- allow:允许匹配的 Skill 加载,不再增加一次批准步骤。
- deny:禁止加载。
- ask:加载前请求批准。
从完成任务所需的最小权限开始。新 Skill 或第三方 Skill 在被广泛允许之前,通常都应该先接受人工审查。
下面是针对示例 Skill 的窄范围配置片段:
这段配置符合文档中的 permission.skill 结构。广泛使用前,仍需把它放入当前 stable 配置上下文,验证完整 JSON,并在一次性项目中观察审批行为;不要未经测试就使用宽泛 wildcard 策略。
允许加载 Skill,不代表允许执行 Skill 里描述的所有动作。Shell 命令、网络访问、文件写入、MCP 工具和 provider 凭证仍由各自的控制机制管理。
项目 Skills、个人 Skills 与共享工作空间 Skills
项目 Skills
当 Skill 编码仓库特有事实时,把它与项目放在一起。像审查代码一样审查 Skill 变更:指定维护者、检查 scripts 和 references,并解释为什么需要新增权限。
个人 Skills
适合跨项目复用的方法。不要因为目录位于个人账号下,就把雇主 secret、客户数据、私有 URL 或可复用凭证写入 Skill。
共享工作空间 Skills
OpenCode 上游支持 Skills,不代表每个 Skill 都能在 Macshop 中安装、同步,或被每个 harness 加载。请以当前 Macshop 工作空间页面和公开产品资料为准,判断托管工作空间提供了哪些共享 Skill 控制。如果你还在决定 OpenCode 应运行在本地、自托管还是托管环境,可以先看云端运行 OpenCode 的选择指南。
依赖共享 Skill 前,先确认产品提供了清楚的添加或移除方式、选中的 harness 能够加载它,而且协作者能看到预期版本和权限提示。如果界面或公开资料没有展示这些控制,就不要默认托管工作空间已支持上游 OpenCode 的这套工作流。
把本地 Skill 复制到共享工作空间前,确认其脚本、参考资料、数据访问和所有权对所有目标用户都合适。
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 当作接近代码的内容进行检查。
- 完整阅读
SKILL.md。 检查隐藏的范围扩张、破坏性动作、数据上传、凭证请求,或要求忽略项目规则的指令。 - 检查所有随附脚本和 executable。 不要因为 skill pack 很流行,就默认它安全或有人维护。
- 检查 references 与外部链接。 确认来源、更新策略,以及其中是否包含不可信指令。
- 检查所需工具和权限。 一个写作 Skill 不应该静默要求 shell、网络、宽泛文件写入或生产凭证。
- 检查数据边界。 分享前移除 secrets、客户数据、私有 endpoint 和内部标识。
- 固定所有权和更新流程。 明确谁审查上游变化,以及团队怎样回退问题更新。
- 先在一次性项目测试。 扩大使用范围前,观察发现、加载、批准、动作和输出。
Marketplace badge 或下载量都不能替代这些检查。
先从一个窄 Skill 开始
创建一个只做一件事的 Skill,把它放进一个官方支持的目录,初始权限保持为 ask,并验证 stable OpenCode 是否按文档完成发现与加载。只有触发、指令、动作和输出都可观察后,才扩大 Skill 范围。
“创建、放置、发现、加载、授权、验证”这条生命周期,是可靠使用 OpenCode Skills 的方法,也为后续判断 Skill 应留在一个项目、保留为个人使用,还是进入共享工作空间提供了清楚边界。
下一步
先创建一个范围窄的 Skill,把首次加载权限保留为 ask,并在共享前验证 discovery。如果任务真正需要的是实时外部工具,而不是可复用指令,再继续看 OpenCode MCP。
