cc-skills-golang 渐进式披露设计：metadata、body、references三层加载——技能不撑爆上下文的秘密

cc-skills-golang 渐进式披露设计metadata、body、references三层加载——技能不撑爆上下文的秘密【免费下载链接】cc-skills-golang‍ A collection of Golang agentic skills that works项目地址: https://gitcode.com/gh_mirrors/cc/cc-skills-golangcc-skills-golang 是一套面向 Go 语言的 AI 编程技能Agent Skills集合覆盖代码风格、并发、测试、安全、性能等 40 多个主题。它的核心设计叫渐进式披露每个技能按 metadata、body、references 三层按需加载——启动时只常驻几百个 token几十套技能同装也不会撑爆 AI 助手的上下文窗口。下面用三个真实文件的数字讲清楚这套机制是怎么省 token 的。1. 问题AI 技能为什么会撑爆上下文AI 助手的上下文窗口是有限的工作台。如果把每个技能的完整手册都一次性塞进去代价是双重的数量大40 个技能每个正文几千人全量加载就是数万 token是经常性成本技能一旦被加载内容会留在上下文中贯穿后续每一轮对话不会被回收。作者的解法不是把技能写得更短而是改变何时加载——这正是 CLAUDE.md 中 Progressive disclosure 一节的设计核心正文里的一切都是反复付费的内容而 references 目录里的内容只在真正被需要时付费一次。用仓库里的话说Markdown 只是冰山一角。2. 三层加载架构用到的才加载一个技能目录的加载时机长这样skills/golang-safety/ ├─ SKILL.md │ ├─ frontmattermetadataname description── 启动时常驻 │ └─ body正文指令、常见错误表────────────── 技能被触发时才加载 └─ references/深度资料──────────────────────── 正文明确指向时才读取层级内容何时加载典型大小第 1 层 metadataSKILL.md 的 name description安装后启动时常驻约 100 token/技能第 2 层 bodySKILL.md 正文角色、最佳实践、常见错误表技能被触发时1,000–2,500 token第 3 层 referencesreferences/、assets/等子文件正文明确指向时按需读取只加载相关部分第 1 层 metadata常驻内存的名片description 是模型在决定是否加载技能之前读到的唯一内容——选错了后面写得再好也没用。所以 CLAUDE.md 对 description 有专门的质量要求先说这个技能做什么再说什么时候用并点名用户真正会输入的具体名词文件类型、工具名、导入路径。这套名片有多轻看 skills/golang-safety/SKILL.md 的 frontmatterdescription 描述了 nil 崩溃、append 别名共享、浮点比较等具体触发场景全部只占约 78 个 token。整个项目的推荐技能集合启动时合计也只加载约1,100 个 token 的描述。第 2 层 body触发时加载的手册技能被触发后SKILL.md 正文才进入上下文。比如 golang-safety 的正文有 282 行约 2,600 token包含角色设定、11 条最佳实践摘要、nil 行为速查表和一张常见错误→修复对照表——全部是高频使用的核心知识没有一处是万一用到的边角料。因为正文是每一轮都付费的内容CLAUDE.md 给它定了硬预算单个 SKILL.md 建议不超过 2,500 token、500 行超过就拆出去而不是压缩它。第 3 层 references需要时才打开的百科深度资料放在references/下按领域一个文件pprof、benchstat、trace 各管一摊只加载相关的那一个。两个关键细节让它真正省 token显式指向正文必须写明读哪个文件、什么时候读例如 golang-safety/SKILL.md 中的See [Nil Safety Deep Dive](https://link.gitcode.com/i/1caddf0b7d7b0ed1578ac18d256aec88) for nil receivers, nil in generics...。裸链接会被模型直接跳过只下探一层references 不嵌套链式引用避免深层内容被截断而模型毫无感知超过 100 行的参考文件必须加目录保证部分读取也能看到全貌。以 skills/golang-benchmark/SKILL.md 为例正文 3,153 token而它的 8 个参考文件含 895 行的 pprof.md合计把整个技能目录撑到 33,396 token——不触发时这 3 万多 token 一个字都不进上下文。3. Token 预算三级数字背后的压缩比CLAUDE.md 的 Token budgets 表格是整个项目的省钱账本预算数值约束对象单个 description约 100 token启动成本每个已装技能都要付单个 SKILL.md 2,500 token正文预算同时加载总量约 10,000 token2–4 个技能的正文合计自动压缩线约 25,000 token压缩时只保留每个技能开头约 5,000 token拿 README.md 技能表里的真实数据看三级漏斗技能descriptionSKILL.md 正文整个技能目录压缩效果golang-safety782,6145,384目录→正文 ≈ 2×golang-security853,18721,623目录→正文 ≈ 7×golang-benchmark1023,15333,396目录→正文 ≈ 11×两层下来装进来和真正用掉之间形成了几十倍的差值——这就是渐进式披露不撑爆上下文的数学原理。4. 让设计生效的三个细节按付费方式拆内容反复用到的规则留在正文一次性查考的资料挪进 references——拆分依据不是文件大小而是加载成本。关键规则前置自动压缩只保留技能开头约 5,000 token所以承重的规则必须排在例子和边缘情况之前。交叉引用而非复制技能之间用→ See指向唯一拥有者原子技能原则同一个概念只存在一份既不重复占位也不产生互相矛盾的二手信息。5. 效果数据97% vs 57%省 token 不是目的有用才是。EVALUATIONS.md 记录了带技能与不带技能的两组对照评测带技能不带技能差距总得分3348/343997%1957/343957%40 个百分点单个技能的错误率降幅最高达 81%golang-samber-do推荐技能普遍在 20%–60% 之间——说明三层结构装下的内容确实改变了模型的默认行为。6. 如何安装 cc-skills-golang只需把仓库克隆到你所用助手的技能发现目录OpenCode、Codex 等通用路径为~/.agents/skills/git clone https://gitcode.com/gh_mirrors/cc/cc-skills-golang ~/.agents/skills/cc-skills-golang建议整套安装技能之间是原子化、互相引用的只装子集会得到不完整甚至不一致的视角。装好后无需任何配置——metadata 层会在下次会话启动时自动生效。7. 写在最后cc-skills-golang 的渐进式披露本质是把写多长的问题变成了何时读的问题metadata 层约 100 token 的名片负责被选中body 层约 2,500 token 的手册负责干活references 层不设上限的百科负责兜底。如果你自己也在使用或编写 AI 技能这套100 → 2,500 → 按需的预算分层几乎可以直接照搬。【免费下载链接】cc-skills-golang‍ A collection of Golang agentic skills that works项目地址: https://gitcode.com/gh_mirrors/cc/cc-skills-golang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考