HoRain云--OpenCode Skills

HoRain云--OpenCode Skills HoRain云小助手个人主页 个人专栏: 《Linux 系列教程》《c语言教程》⛺️生活的理想就是为了理想的生活!⛳️ 推荐前些天发现了一个超棒的服务器购买网站性价比超高大内存超划算忍不住分享一下给大家。点击跳转到网站。专栏介绍专栏名称专栏介绍《C语言》本专栏主要撰写C干货内容和编程技巧让大家从底层了解C把更多的知识由抽象到简单通俗易懂。《网络协议》本专栏主要是注重从底层来给大家一步步剖析网络协议的奥秘一起解密网络协议在运行中协议的基本运行机制《docker容器精解篇》全面深入解析 docker 容器从基础到进阶涵盖原理、操作、实践案例助您精通 docker。《linux系列》本专栏主要撰写Linux干货内容从基础到进阶知识由抽象到简单通俗易懂帮你从新手小白到扫地僧。《python 系列》本专栏着重撰写Python相关的干货内容与编程技巧助力大家从底层去认识Python将更多复杂的知识由抽象转化为简单易懂的内容。《试题库》本专栏主要是发布一些考试和练习题库涵盖软考、HCIE、HRCE、CCNA等目录⛳️ 推荐专栏介绍核心机制Skill 的核心结构技能如何工作文件放置位置发现机制编写 SKILL.md1、Frontmatter 字段2、命名规则3、编写描述4、完整示例实例代理如何发现和加载技能配置技能权限实例按代理覆盖权限1、在自定义代理的 Frontmatter 中配置2、在 opencode.json 中为内置代理配置禁用技能工具1、在自定义代理的 Frontmatter 中禁用实例2、在 opencode.json 中为内置代理禁用实例排查技能加载问题在 OpenCode 中代理技能Skills是一种用于封装可复用行为的机制通过SKILL.md文件定义使 LLM 能够按需加载、按需执行特定能力。相比普通提示词技能更接近模块化能力单元可以在多个项目或团队中复用。Skills 是 OpenCode 的能力插件系统它将 AI 行为从单次提示升级为可复用能力模块使开发流程更加标准化、可组合并适用于复杂工程体系。Skills 以 Markdown 文件形式存在不执行功能而是通过按需、渐进式加载实现高效且可复用的经验传递。Skills 和传统 Prompt 最大的区别是按需加载 渐进式披露只在需要时才把厚厚的 SOP 塞进上下文极大节省 token。对比项普通 PromptSkills 机制每次都要重新描述是否只描述一次上下文长度占用每次全量塞入渐进式加载只在触发时才读完整内容一致性依赖每次 prompt 质量高固定 SOP 模板复用性手动复制粘贴自动匹配 / slash 命令 / 项目共享维护方式改一次 prompt 就要重新发修改 SKILL.md 文件全局/项目生效核心机制Skills 通过内置的skill工具进行管理工作流程如下扫描本地和全局技能目录在上下文中暴露可用技能列表代理根据任务自动选择技能按需加载 SKILL.md 内容这种机制避免了将所有规则一次性加载提高了性能和上下文利用率。Skill 的核心结构Skills 的核心就是一个文件夹 一个 SKILL.md 文件。SKILL.md 文件包含元数据至少要有名称和描述告诉 AI 如何完成某一特定任务的指令一个 Skill 本质上就是一个 Markdown 文件文件名固定为 SKILL.mdmy-skill/ └── SKILL.md 唯一必需SKILL.md 基本模板:--- name: pdf-processing description: 从 PDF 中提取文本和表格填写表单并合并文档 --- # PDF 处理 ## 使用场景 当需要对 PDF 文件进行操作时使用例如 - 提取 PDF 文本或表格数据 - 填写 PDF 表单 - 合并多个 PDF 文件 ## 提取文本 - 使用 pdfplumber 提取文本型 PDF 内容 - 扫描版 PDF 需配合 OCR 工具 ## 填写表单 - 读取 PDF 表单字段 - 按输入数据填充并生成新文件最小必填示例:--- name: skill-name description: 说明该 Skill 的功能以及适用场景 ---含可选字段示例:--- name: pdf-processing description: 从 PDF 中提取文本和表格填写表单并合并文档 license: Apache-2.0 metadata: author: example-org version: 1.0 ---字段必需说明name是Skill 名称最长 64 字符只能使用小写字母、数字和-且不能以-开头或结尾description是功能与使用场景说明最长 1024 字符不能为空license否许可证名称或指向随 Skill 附带的许可证文件compatibility否环境与依赖说明产品、系统包、网络权限等最长 500 字符metadata否自定义键值对用于扩展元数据如作者、版本号allowed-tools否允许使用的工具列表空格分隔实验性功能如果你需要一些参考资料参考实例执行脚本可以使用更复制 Skill 的目录结构my-skill/ ├── SKILL.md # 必需指令 元数据 ├── scripts/ # 可选可执行代码 ├── references/ # 可选文档资料 └── assets/ # 可选模板、资源技能如何工作技能用渐进式加载来高效管理上下文发现启动时AI 只加载每个技能的名称和描述只保留最基本的识别信息。激活当任务匹配某个技能的描述时AI 才把完整的 SKILL.md 指令读入上下文。执行AI 按照指令执行按需加载参考文件或运行代码。这种设计让 AI 保持快速同时能按需获取更多信息。文件放置位置每个技能需要一个独立的文件夹文件夹内放置SKILL.md文件注意文件名必须全部大写。OpenCode 会自动搜索以下六个位置类型路径适用范围项目配置.opencode/skills/name/SKILL.md仅当前项目全局配置~/.config/opencode/skills/name/SKILL.md所有项目项目 Claude 兼容.claude/skills/name/SKILL.md仅当前项目全局 Claude 兼容~/.claude/skills/name/SKILL.md所有项目项目代理兼容.agents/skills/name/SKILL.md仅当前项目全局代理兼容~/.agents/skills/name/SKILL.md所有项目典型的项目目录结构如下your-repo/ ├── .opencode/ │ └── skills/ │ ├── git-release/ │ │ └── SKILL.md ← 发版流程技能 │ ├── code-review/ │ │ └── SKILL.md ← 代码审查技能 │ └── api-doc/ │ └── SKILL.md ← API 文档编写技能 ├── src/ └── package.json发现机制OpenCode 的技能发现分为两个层级项目本地技能OpenCode 从当前工作目录开始向上逐层遍历目录树直到到达 Git 工作树的根目录为止。在此过程中它会收集沿途每一层目录下.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.md中所有匹配的技能文件。全局技能同时从~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.md中加载所有已定义的全局技能。两个层级的技能会合并后一起提供给代理使用。如果项目本地技能与全局技能同名项目本地技能优先。编写 SKILL.md1、Frontmatter 字段每个SKILL.md文件必须以 YAML frontmatter 开头即---包裹的部分。OpenCode 只识别以下字段未知字段会被自动忽略字段是否必填类型说明name必填字符串技能的唯一标识名必须与所在文件夹名称一致且符合命名规则description必填字符串技能的描述代理依据此内容决定是否调用1–1024 个字符license可选字符串技能内容的许可证类型如MIT、Apache-2.0compatibility可选字符串标注与哪个工具兼容如opencode、claudemetadata可选对象字符串到字符串的映射自定义的附加元数据如目标受众、工作流类型等键值均为字符串2、命名规则name字段的值必须同时满足以下所有条件否则技能将无法被加载长度为1–64 个字符只能包含小写字母和数字单词之间可以用单个连字符-分隔不能以-开头或结尾不能包含连续的--必须与包含该SKILL.md的文件夹名称完全一致等效的正则表达式^[a-z0-9](-[a-z0-9])*$合法命名示例git-release、api-doc、code-review、deploy2prod非法命名示例Git-Release含大写、-release以-开头、git--release连续--3、编写描述description字段的内容直接影响代理是否能正确选择和调用该技能。建议描述要具体明确说明该技能做什么、在什么场景下使用避免过于笼统❌ 过于笼统帮助完成发版任务✅ 具体明确从合并的 PR 中起草发版说明、提出版本号建议并生成可直接使用的 gh release create 命令4、完整示例在项目中创建.opencode/skills/git-release/SKILL.md内容如下实例---name: git-releasedescription: Create consistent releases and changelogslicense: MITcompatibility: opencodemetadata:audience: maintainers # 自定义元数据目标受众workflow: github # 自定义元数据工作流类型---## What I do- Draft release notes from merged PRs- Propose a version bump- Provide a copy-pasteable gh release create command## When to use meUse this when you are preparing a tagged release.Ask clarifying questions if the target versioning scheme is unclear.Frontmatter 中的name值必须与文件夹名称一致。本例中文件夹名为git-release因此name也必须写git-release否则技能无法被识别。代理如何发现和加载技能OpenCode 启动后会将当前所有可用技能以 XML 格式注入到skill工具的描述中。代理可以通过查看工具描述来了解有哪些技能可用available_skills skill namegit-release/name descriptionCreate consistent releases and changelogs/description /skill skill namecode-review/name descriptionPerform structured code reviews with consistent criteria/description /skill /available_skills当代理判断某个技能与当前任务相关时会主动调用skill工具来加载该技能的完整SKILL.md内容skill({ name: git-release })加载完成后技能中定义的指令和上下文信息会进入代理的工作记忆从而影响后续的行为和输出。技能本身不会自动执行任何操作只是为代理提供额外的上下文和行为规范。配置技能权限在opencode.json中使用permission.skill字段控制代理可以访问哪些技能支持精确名称和 Glob 通配符两种匹配方式实例{$schema: https://opencode.ai/config.json,permission: {skill: {*: allow, // 兜底规则默认允许加载所有技能pr-review: allow, // 精确匹配允许加载 pr-review 技能internal-*: deny, // Glob 匹配拒绝加载所有 internal- 开头的技能对代理完全隐藏experimental-*: ask // Glob 匹配加载 experimental- 开头的技能前需用户确认}}}三种权限动作对技能的具体效果如下权限值效果allow技能立即加载代理无需任何确认deny技能对代理完全隐藏available_skills列表中不会出现该技能代理无法感知其存在ask代理尝试加载该技能时弹出确认提示由用户决定是否允许按代理覆盖权限不同代理可能需要访问不同的技能集可以为每个代理单独配置权限覆盖全局默认值。1、在自定义代理的 Frontmatter 中配置# 文件路径~/.config/opencode/agents/my-agent.md --- permission: skill: documents-*: allow # 该代理可以加载所有 documents- 开头的技能 # 其他技能遵循全局权限配置 --- You are a documentation assistant.2、在 opencode.json 中为内置代理配置{ $schema: https://opencode.ai/config.json, agent: { plan: { // 内置代理名称 permission: { skill: { internal-*: allow // plan 代理可以加载 internal- 开头的技能 // 即使全局配置中对其设置了 deny } } } } }禁用技能工具对于完全不需要使用技能的代理可以直接禁用skill工具。禁用后available_skills列表将从代理的上下文中完全移除既节省 Token 消耗又避免代理尝试加载任何技能。1、在自定义代理的 Frontmatter 中禁用实例---tools:skill: false # 对该代理完全禁用技能功能available_skills 列表不会出现在上下文中---You are a quick answer assistant. Just answer questions directly.2、在 opencode.json 中为内置代理禁用实例{$schema: https://opencode.ai/config.json,agent: {plan: {tools: {skill: false // plan 代理不使用任何技能}}}}排查技能加载问题如果某个技能没有出现在可用列表中请按以下顺序逐项检查确认文件名大小写SKILL.md的文件名必须全部大写写成skill.md或Skill.md都不会被识别。检查 Frontmatter 完整性确保SKILL.md开头有正确的 YAML frontmatter且包含name和description两个必填字段。缺少任意一个技能都不会被加载。确认技能名称唯一且格式正确如果不同路径下存在同名技能可能产生冲突。同时检查name字段是否符合命名规则仅小写字母和数字以连字符分隔且与文件夹名称完全一致。检查权限配置在opencode.json的permission.skill中权限为deny的技能会对代理完全隐藏不会出现在available_skills列表中。检查是否有通配符规则如*: deny意外匹配到了该技能。❤️❤️❤️本人水平有限如有纰漏欢迎各位大佬评论批评指正如果觉得这篇文对你有帮助的话也请给个点赞、收藏下吧非常感谢! Stay Hungry Stay Foolish 道阻且长,行则将至,让我们一起加油吧