01 技能(Skill):渐进式披露指令

文档摘要

01 技能(Skill):渐进式披露指令本节摘要:OpenWork 的核心承诺是「一次创建,随处分享」,「能力(capability)」就是这个承诺的载体。四类能力里,本节讲技能(Skill)——它是一种渐进式披露的指令文件,用标准的 SKILL 格式描述,模型先看摘要、按需读正文。本节讲清技能的形态、OpenWork 如何管理它(CRUD)、它如何被分享。一、技能是什么:一个指令文件技能本质上是一个指令文件——告诉 Agent「遇到某类任务时该怎么做」。

01 技能(Skill):渐进式披露指令

本节摘要:OpenWork 的核心承诺是「一次创建,随处分享」,「能力(capability)」就是这个承诺的载体。四类能力里,本节讲技能(Skill)——它是一种渐进式披露的指令文件,用标准的 SKILL 格式描述,模型先看摘要、按需读正文。本节讲清技能的形态、OpenWork 如何管理它(CRUD)、它如何被分享。

一、技能是什么:一个指令文件

技能本质上是一个指令文件——告诉 Agent「遇到某类任务时该怎么做」。它用一种标准的 SKILL 格式描述,大致含:

部分	作用
名字(name)	唯一标识,如 `pdf-handler`
描述(description)	一句话说明干什么、何时用
正文(content)	详细指令(何时用才读)

技能的底层机制(渐进式披露)和 OpenCode 教程第 11 章讲的一样——模型先只看名字+描述(占很少 token),需要时通过技能工具读正文。OpenWork 在这之上加了「管理 + 分享」。

二、OpenWork 如何管理技能(CRUD)

OpenWork 服务端对技能提供完整的增删改查(CRUD):

操作	说明
list(列)	扫描工作区与全局的技能目录,列出所有技能
upsert(增/改)	写一个技能文件(含 frontmatter + 正文)
delete(删)	删除技能文件/目录
读正文	模型按需时读技能正文


技能管理(CRUD):
   ├─ list: 扫描 .opencode/skills、.claude/skills 等
   ├─ upsert: 写 <root>/.opencode/skills/<name>/SKILL.md
   ├─ delete: 删该目录
   └─ read: 模型按需读正文

技能可以来自两个 scope:项目级(项目目录)和全局级(用户主目录)。同名时项目级优先。

三、技能的发现:多目录扫描

OpenWork 扫描多个目录发现技能:

工作区根的 .opencode/skills
工作区根的 .claude/skills(兼容)
全局目录(用户主目录)

支持两种布局:扁平(skills/<name>/SKILL.md)和分层(skills/<domain>/<name>/SKILL.md)。同名技能去重(取优先级高的)。

💡 兼容多目录的价值:OpenWork 扫 .opencode 和 .claude 两个目录,让它能复用已有生态的技能——你为 Claude 写的技能,OpenWork 直接能用。这是「跨工具复用」的一个体现。

四、技能的 upsert:格式要求

写一个技能(upsert)时,格式有要求:

必须是标准 SKILL 格式(frontmatter + 正文)
frontmatter 的 name 必须匹配文件目录名(防不一致)
正文是详细指令


<root>/.opencode/skills/my-skill/SKILL.md:
---
name: my-skill
description: 处理某类任务的最佳实践
---
(正文:详细指令...)

如果 name 和目录名不匹配,OpenWork 会拒绝(防「文件叫 A 但声明叫 B」的混乱)。

五、技能如何被分享

这是 OpenWork 技能管理的核心价值——技能可分享。一个技能写好后,可以:

在工作区内分享:队友连到同一个工作区,就能用这个技能。
经 meta-MCP 分享(第 7 章):技能作为一种「能力」,可被任意接入的 Agent 经 meta-MCP 检索和使用。
经市场分享(第 12 章):企业版可把技能发布到市场,跨组织分享。


你写了个技能 pdf-handler
   │
   ▼ 队友连工作区 ──► 直接用
   │
   ▼ Agent 经 meta-MCP ──► 检索到并用
   │
   ▼ 发布到市场 ──► 跨组织用

这就是「一次创建、随处分享」在技能上的体现。

六、技能与第 5 章(引擎托管)的关系

技能写好后,怎么让引擎用上?通过第 5 章的运行时配置注入——OpenWork 把可用技能的信息注入到引擎的配置里,引擎重建实例后感知到新技能。


你 upsert 了一个新技能
   │
   ▼ OpenWork 运行时配置更新(第 5 章)
   │
   ▼ 配置新鲜度同步
   │
   ▼ Reload 事件(第 8 章)驱动引擎重建
   │
   ▼ 引擎感知到新技能,模型可用

所以技能管理(CRUD)和引擎托管(第 5 章)、Reload(第 8 章)是一条链——你加了技能,经这套链路让引擎实时用上。

七、技能 vs 命令 vs MCP vs 插件

本节讲技能,后面三节讲命令、MCP、插件。先给个对比定位:

能力	触发者	本质
技能	模型按需	给模型的指令
命令	用户主动	用户提示模板
MCP	Agent 调用	外部工具连接
插件	系统/Agent	包级全能扩展

技能是「模型按需加载的指令」,这是它的定位。

八、本节要点回顾

技能是指令文件:标准 SKILL 格式(name + description + 正文)。
渐进式披露:模型先看名字+描述,按需读正文(底层同 OpenCode 第 11 章)。
OpenWork CRUD:list / upsert / delete / read,项目级+全局级两个 scope。
多目录扫描:.opencode + .claude,扁平+分层布局,兼容已有生态。
upsert 要求 name 匹配目录名:防不一致。
可分享:工作区内 + meta-MCP + 市场——「一次创建随处分享」。
经配置注入生效:CRUD → 配置注入(第 5 章)→ Reload(第 8 章)→ 引擎用上。

技能讲清了,下一节讲命令——用户侧的提示模板。