渐进式披露设计指南
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/samber-cc-skills-skill-progressive-disclosure-design。
技能介绍
要解决什么问题
大模型技能往往在 SKILL.md 越写越长 时触发两种误判:把「不触发」当成「该拆文件」,或为了行数指标机械拆分,结果路由 prose 增多、该读的 references/* 没读、该在上下文里的关键段却进了可选引用。本技能把 Triggering(是否调用技能) 与 Progressive disclosure(激活后加载什么) 拆开讲清:前者只受 YAML 描述影响,后者才是 SKILL.md 全文 + 按指针加载 references/*、不经上下文执行 scripts/* 的取舍。
技能如何工作
默认立场是 单文件 SKILL.md 优先,只有行数约超 400 且存在自然分支、评测显示模型在读无关段、或某块内容又大又窄时才考虑拆分。文档给出三条可落地的切分轴:
- Variant branch:用户意图互斥选一路(云厂商、框架、输出格式等),主文件留决策与共用流程,各 variant 细节进独立 reference。
- Workflow vs. reference data:主文件写动词与顺序,查表类内容(schema、错误码、配置矩阵)按 key 指针查找。
- Depth tier:主文件覆盖 80% 常见路径,边缘情形用可观测条件跳转到
references/edge-cases.md。
同时列举 典型失败拆分(按主题拆 testing、为行数而拆、把罕见但关键内容放进 references、Examples/Notes 装饰性文件),并规定 指针卫生:一句一指针、文件名编码触发信号、长 reference 加目录。确定性工作优先 scripts/ 而非 reference 散文。文末提供 五项决策清单 与 架构评测(记录每次运行读了哪些 reference、token 与路径覆盖率),区别于只看输出质量的 eval。
适用边界
内容强调 权衡而非规则:模型应结合用户场景推理,而非照搬「400 行必拆」。若 variant 共享超过约 60% 内容、lookup 总量很小、或没有可从用户输入中观测到的尖锐加载条件,拆分往往不划算。触发不稳时应先改描述(可参考 skill-creator 的 run_loop.py),而不是拆文件。
使用场景
- SKILL.md 超过四百行,想判断应按云厂商还是按工作流拆 references,避免每次调用全量吃 token
- 技能能触发但模型总读错 reference 或漏读边缘分支,需要重写指针与文件名触发条件
- 准备把 schema、错误码表从主流程里拆出,要确认算 workflow 还是 reference data 切分
- 改版技能目录后要用架构 eval 统计每次运行实际加载了哪些 references 与 token 成本
适合人员
- 维护多 variant 部署技能的平台工程师,希望按用户选的框架只加载对应 reference
- 写 Claude/Cursor 技能的内构作者,正在为超长 SKILL.md 做拆分评审与指针卫生检查
- 负责技能质量的人,需要把输出 eval 扩展为记录 tool call 与 references 加载的架构评测
- 怀疑「不触发」与「上下文过大」混为一谈的新手技能作者,需要先看触发与披露的分工再动刀拆文件