02 技能作为上下文源的渐进式披露
文档摘要
02 技能作为上下文源的渐进式披露 本节摘要:四类扩展点里,技能(Skill)是最精巧的一个。它不是「把指令全塞进系统提示」,而是用一种渐进式披露(progressive disclosure)的方式暴露给模型——模型先只看到技能的名字和描述(占很少 token),需要时通过「技能工具」读取正文。本节讲清这种机制,以及为什么它比「全塞进系统提示」更省 token、更聚焦。 一、问题:指令全塞进系统提示的代价 先看传统做法的问题。如果你想让 Agent 遵循一堆专门的指令(比如「处理 PDF 的规范」「写测试的规范」),朴素做法是把它们全写进系统提示。但这有代价: token 浪费:很多指令在当前会话里根本用不上(比如不处理 PDF 时,PDF 规范就是浪费)。
02 技能作为上下文源的渐进式披露
本节摘要:四类扩展点里,**技能(Skill)是最精巧的一个。它不是「把指令全塞进系统提示」,而是用一种渐进式披露(progressive disclosure)**的方式暴露给模型——模型先只看到技能的名字和描述(占很少 token),需要时通过「技能工具」读取正文。本节讲清这种机制,以及为什么它比「全塞进系统提示」更省 token、更聚焦。
一、问题:指令全塞进系统提示的代价
先看传统做法的问题。如果你想让 Agent 遵循一堆专门的指令(比如「处理 PDF 的规范」「写测试的规范」),朴素做法是把它们全写进系统提示。但这有代价:
- token 浪费:很多指令在当前会话里根本用不上(比如不处理 PDF 时,PDF 规范就是浪费)。
- 注意力分散:系统提示塞太多,模型注意力被稀释,反而忽略了重点。
- 难扩展:指令越多,系统提示越臃肿,直到撑爆。
技能就是为了解决这个——它不把指令全塞进系统提示,而是「按需加载」。
二、技能是什么:一个指令文件
一个技能本质上是一个指令文件——用一种标准的 SKILL 格式描述,大致含:
| 部分 | 作用 |
|---|---|
| 名字(name) | 唯一标识,如 pdf-handler |
| 描述(description) | 一句话说明这个技能干什么、何时用 |
| 正文(content) | 详细的指令(何时用才读) |
关键在于:名字和描述会暴露给模型,但正文不会自动暴露——正文只在模型决定用这个技能时,通过「技能工具」读取。
三、渐进式披露:先看摘要,按需读正文
这是技能机制的核心。模型看到的是:
模型初始看到的(占很少 token): ├─ 技能: pdf-handler —— 处理 PDF 文件的规范 ├─ 技能: test-writer —— 写测试的最佳实践 └─ 技能: deploy-guide —— 部署流程指引 (只名字+描述,没有正文) ▼ 模型遇到任务:处理一个 PDF │ ▼ 模型判断:这需要 pdf-handler 技能 │ ▼ 调用「技能工具」读 pdf-handler 的正文 │ ▼ 拿到详细指令(此时才消耗 token) │ ▼ 按指令处理 PDF
这就是「渐进式披露」——先给模型一个「技能菜单」(名字+描述),模型按需「点菜」(读正文)。用不到的技能,正文从不进入上下文,token 一点不浪费。
💡 省 token 的本质:假设有 20 个技能,每个正文 2000 token。全塞进系统提示要 40000 token;渐进式披露下,模型只读它用的那 1-2 个(2000-4000 token),省了 90% 以上。技能越多,这种节省越明显。
四、技能作为「上下文源」
在第 8 章我们讲过「上下文源(Context Source)」——技能正是作为一种上下文源实现的。具体说:
- 技能的「名字+描述」作为一种上下文源,出现在 System Context 里(作为「技能指引」源)
- 技能的「正文」不进 System Context,而是通过「技能工具」按需读
这意味着技能享受第 8 章纪元机制的好处——技能列表的变化(增删技能)会触发 reconcile,必要时开新纪元或插中途消息。但正文的读取是一次性工具调用,不涉纪元变化。
五、技能从哪发现
OpenCode 会从多个地方发现技能:
| 来源 | 位置 |
|---|---|
| 全局 | 用户主目录下的技能目录(如 ~/.claude/skills、~/.agents) |
| 项目 | 项目里的技能目录(向上查找 .claude/.agents/配置目录) |
| 配置指定 | 配置里指定的技能路径 |
| 远程 | 配置里的技能 URL(从远程拉取) |
发现时,OpenCode 扫描这些地方的技能文件(以特定模式命名,如 SKILL.md),解析其名字和描述,注册成「可用技能」。
⚠️ 远程技能的安全:从远程拉技能要小心——技能含指令,恶意技能可能诱导模型做坏事。OpenCode 会做路径安全校验(防穿越攻击),但指令内容本身要你判断可不可信。
六、技能的权限过滤
技能也会过权限过滤——第 4 章权限规则决定当前 Agent 能看到哪些技能:
发现技能 [A, B, C] │ ▼ 权限过滤(技能级) │ 当前 Agent 可见: [A, C](B 被隐藏) │ ▼ 只有可见的进入「技能菜单」
这让技能的可见性也可控——不是「装了就全见」,而是按 Agent 权限筛。
七、技能 vs 斜杠命令:别混
新手容易混「技能」和「斜杠命令」(下一节)。这里先点破:
| 技能 | 斜杠命令 | |
|---|---|---|
| 触发者 | 模型按需读取 | 用户主动输入 |
| 本质 | 给模型的指令(模型看) | 给会话的提示模板(展开成消息) |
| 解决 | 模型需要时才知道怎么做 | 用户快速发起某类任务 |
技能是「模型按需加载的能力」,命令是「用户快捷发起的模板」。二者完全不同,别混。下一节详讲命令。
八、本节要点回顾
- 技能解决:指令全塞系统提示的 token 浪费/注意力分散/难扩展。
- 技能是指令文件:名字+描述+正文,用标准 SKILL 格式。
- 渐进式披露:模型先看名字+描述(菜单),按需读正文(点菜),用不到的不进上下文。
- 省 token 显著:20 个技能全塞 vs 只读 1-2 个,省 90% 以上。
- 作为上下文源实现:名字描述进 System Context,正文经技能工具读。
- 多源发现:全局/项目/配置路径/远程;远程要注意可信。
- 权限过滤:技能可见性受 Agent 权限约束。
- 技能 ≠ 命令:技能模型按需,命令用户主动——下一节详讲。
技能讲清了,下一节讲斜杠命令——用户侧的快捷方式。