写 skill/长文档：用三层渐进披露，别堆成一个巨文件

写 skill、操作手册、长文档时，把所有内容堆进一个主文件会让模型读不完也读不准。按「元数据→主体→参考资料」三层组织，按需加载。

适用场景

解决思路

1. 三层结构：①元数据（名字+描述，永远在上下文里，约 100 字）②主体（触发时加载，控制在 500 行内）③附带资源（按需读，脚本可直接执行无需读源码）
2. 主体接近 500 行就再加一层层级，并在主文件里写清「接下来该去读哪个文件」
3. 引用文件时写明「什么情况下读它」，不要只丢个路径
4. 超过 300 行的参考资料加目录
5. 同一主题有多个变体时按变体分文件（如 cloud-deploy/references/{aws,gcp,azure}.md），模型只读需要的那份
6. 指令用祈使句写

适用边界 · 注意事项

• 别把内容全塞进主文件 —— 会撑爆上下文，且关键部分被淹没
• 别只给路径不写使用时机（模型不知道什么时候该去读）
• 别给教学类内容加 offset/limit 分页 —— 模型会只读第一页就跳过剩下（这是被验证过的失败模式）