HoRain云--OpenCode Skills 实战：用 SKILL.md 与 opencode.json 搭建可复用技能骨架

1. 为什么你的 OpenCode Skills 总是加载不出来如果你正在用 OpenCode 做日常开发大概率遇到过这种场景明明按文档写了SKILL.md重启之后代理却像没看见一样问它「有哪些技能可用」也答不上来。问题通常不在模型而在两个地方——SKILL.md的 Frontmatter 字段写错了或者opencode.json的注册骨架没配对。OpenCode Skills 本质上是把「一段可复用的行为规范」封装成 Markdown 文件让代理按需加载。它和普通提示词最大的区别是渐进式披露启动时只读name和description任务匹配上了才把完整内容塞进上下文。这意味着 Frontmatter 里那两个必填字段一旦写错技能连「被发现」的机会都没有。这篇聚焦落地配置从SKILL.md的 Frontmatter 字段写法到opencode.json的注册与权限骨架给出可直接复制的文件模板和最小验证步骤。适合已经装好 OpenCode、想跑通第一个自定义 Skill 的开发者。全程不需要改源码只动两个文件。2. 前置准备目录结构与模型接入2.1 技能目录放哪里OpenCode 会自动扫描六个位置项目级和全局级各三个。最常用的是项目级.opencode/skills/因为它能跟着仓库走团队共享方便。your-repo/ ├── .opencode/ │ └── skills/ │ └── git-release/ │ └── SKILL.md ├── src/ └── package.json注意文件夹名git-release必须和SKILL.md里的name字段完全一致这是新手最容易踩的坑。文件名必须全大写SKILL.md写成skill.md直接不识别。2.2 模型侧的准备Skills 本身不执行任何操作它只是给代理提供上下文。真正干活的是背后的模型。如果你还在为模型调用额度或接入方式折腾可以先把这一层理顺。我平时用 TaoToken 做统一接入一个 Key 覆盖多种模型省得在多个平台之间来回切。注册和拿 Key 的入口在这里官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content控制台创建 API Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 管理页https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys拿到 Key 之后OpenCode 侧只需要在配置里指向兼容的 API 地址https://taotoken.net/api模型名按你开通的填。这一步做完Skills 才有「大脑」去调用。3. 可复制配置SKILL.md 与 opencode.json 骨架3.1 SKILL.md 的 Frontmatter 字段每个SKILL.md必须以 YAML frontmatter 开头也就是---包裹的那一段。OpenCode 只认下面这几个字段其他字段会被静默忽略。字段是否必填类型说明name必填字符串唯一标识1–64 字符只能小写字母、数字和单个连字符description必填字符串功能与场景说明1–1024 字符代理靠它决定是否调用license可选字符串许可证类型如 MIT、Apache-2.0compatibility可选字符串兼容标注如 opencode、claudemetadata可选对象自定义键值对键值均为字符串allowed-tools可选字符串允许使用的工具列表空格分隔实验性name的命名规则可以用一个正则概括^[a-z0-9](-[a-z0-9])*$。合法示例有git-release、api-doc、deploy2prod非法示例有Git-Release大写、-release以连字符开头、git--release连续连字符。3.2 一个能跑的最小 SKILL.md在.opencode/skills/git-release/SKILL.md写入以下内容--- name: git-release description: 从已合并的 PR 中起草发版说明、建议版本号并生成可直接执行的 gh release create 命令 license: MIT compatibility: opencode metadata: audience: maintainers workflow: github --- ## 我做什么 - 从已合并的 PR 列表起草发版说明 - 根据变更类型建议版本号major / minor / patch - 输出一条可直接复制执行的 gh release create 命令 ## 什么时候用我 当你准备打一个带 tag 的正式发版时使用。如果目标版本策略不明确先向用户提问确认。这里description写得具体代理才能判断「发版任务」该调用它。如果只写「帮助完成发版任务」匹配率会明显下降。3.3 opencode.json 的注册与权限骨架技能不需要在opencode.json里逐个「注册」OpenCode 靠目录扫描自动发现。但权限控制必须在这里配否则默认行为可能不符合预期。{ $schema: https://opencode.ai/config.json, permission: { skill: { *: allow, pr-review: allow, internal-*: deny, experimental-*: ask } } }三种权限动作的效果差异很大allow技能立即加载代理无需确认。deny技能对代理完全隐藏连available_skills列表都不出现。ask代理尝试加载时弹确认由用户决定。如果你想让某个代理单独覆盖全局权限可以在自定义代理的 frontmatter 里写--- permission: skill: documents-*: allow --- You are a documentation assistant.或者在opencode.json里针对内置代理配置{ $schema: https://opencode.ai/config.json, agent: { plan: { permission: { skill: { internal-*: allow } } } } }4. 验证请求确认技能真的加载生效4.1 用 skill 工具主动触发OpenCode 启动后会把可用技能以 XML 形式注入到skill工具的描述里。你可以直接问代理你现在有哪些可用的 skill请列出名称和描述。如果配置正确代理会返回类似这样的列表available_skills skill namegit-release/name description从已合并的 PR 中起草发版说明.../description /skill /available_skills4.2 用真实任务验证加载光看到列表还不够要确认完整内容能被读进上下文。直接给一个匹配description的任务帮我为 v1.2.0 起草一份发版说明并给出 gh release create 命令。代理判断任务匹配后会调用skill({ name: git-release })把完整SKILL.md读入工作记忆然后按里面的指令输出。如果它开始按「我做什么」那几节的结构回答说明加载链路通了。4.3 用 API 侧确认模型响应正常如果技能列表能出来但任务执行报错问题可能在模型调用。用一条最小请求确认 API 通curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型名, messages: [{role: user, content: ping}] }返回正常 JSON 就说明模型侧没问题可以回头查 Skills 配置。模型对话的调试入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat 适合快速验证。5. 本篇常见错排查5.1 技能不出现先查文件名和 Frontmatter按这个顺序逐项过第一文件名必须全大写SKILL.md。skill.md、Skill.md都不识别这是最高频的坑。第二Frontmatter 必须完整。name和description缺任意一个技能直接不加载。检查开头是不是---结尾是不是也有---。第三name必须和文件夹名完全一致。文件夹叫git-releasename写git_release或GitRelease都不行。5.2 技能被隐藏查权限通配符如果技能明明存在却不在列表里重点看opencode.json的permission.skill。一条*: deny会兜底拒绝所有技能即使后面写了git-release: allow顺序和匹配逻辑也可能让预期落空。建议把精确规则写在通配符之前或者干脆把兜底设为allow。5.3 加载了但不按指令走查 description 质量技能能被加载但代理输出不符合SKILL.md里的规范通常是description太笼统导致代理在多个技能之间选错。把「做什么」和「什么时候用」都写进description匹配精度会明显提升。5.4 上下文被撑爆检查是否该禁用 skill 工具对于纯问答型代理技能列表本身也占 Token。如果某个代理完全不需要技能直接在它的 frontmatter 里禁用--- tools: skill: false --- You are a quick answer assistant.禁用后available_skills列表从上下文移除既省 Token 又避免误调用。6. 长期编码场景的接入建议如果你打算把 Skills 用在长期的编码或 Agent 工作流里单次调用额度很容易成为瓶颈。这种场景更适合用 Coding Plan 这类面向持续编码的套餐配合 Skills 做模块化能力沉淀团队里每个人共享同一套SKILL.md行为一致性比每次手写提示词高得多。Coding Plan 入口https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入文档含 OpenCode 等工具的配置说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用的是 Claude Code 这类 Anthropic 兼容客户端配置方式在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode-anthropic 有单独说明。最后给一个实操建议先把git-release这个最小技能跑通确认列表能看到、任务能触发、输出符合SKILL.md规范再往scripts/、references/里加复杂内容。渐进式加载的价值就在于你不需要一次性把整套 SOP 写完先让骨架生效再逐步填充。