A Practical Guide to Progressive Disclosure for Agent SKILL Packages
A Juejin technical guide explains how to implement SKILL packages as directories containing SKILL.md, scripts, and optional reference files. It describes a four-stage workflow of registration, matching, loading, and execution, in which only skill descriptions are initially registered and full instructions are loaded on demand. The author also reports failure modes observed with a 1.7B local model and recommends safeguards such as explicit tool ordering, duplicate-load tracking, path validation, execution timeouts, and output truncation.
The guide offers developers a concrete pattern for separating reusable workflow knowledge and deterministic scripts from an agent’s existing tools, while reducing unnecessary context usage.
手写 SKILL 加载：搞懂技能包的渐进式披露
把"技能"做成目录形态的说明书（SKILL.md + 脚本 + 扩展资料），Agent 启动时只注册一句话描述，命中后才装载全文，脚本由子进程执行——让模型用已有的工具循环按需获取知识，全程零框架。 写作目的：吃透 SKILL 与 Agent 的配合机制——SKILL 不是新的执行通道，而是一份"按需注入的任务说明书"。看懂渐进式披露，就理解了 Cursor、Qoder 这类产品里技能体系的底层逻辑。
一、为什么需要 SKILL：工具解决"能做什么"，不解决"怎么编排"
从 Agent 架构看，工具（OpenAI tools 协议 / MCP）解决的是原子能力的接入：查天气、读网页、查待办，每个工具一份 JSON Schema 声明，模型决定调用、Agent 本地执行、结果回写。但有两类问题是工具层天然承载不了的：
- 编排经验无处沉淀。"出差前先看天气和当地新闻，再根据温度给穿衣建议"——这类"多个工具怎么组合着用"的流程知识，写不进工具声明，只能塞进 system prompt。场景一多，system prompt 变成大杂烩，每轮请求还全量消耗 token。
- 确定性逻辑不该交给模型推理。"12°C 穿外套、29°C 穿短袖并带伞"这种规则判断，小模型"凭感觉"输出不稳定；"早报固定排版"这种格式约束，写进提示词模型也会偶尔走样。它们本质是代码，不是提示词。
#SKILL.md#Anthropic Agent Skills#Model Context Protocol#OpenAI tools protocol#Cursor#Qoder