Howie2099

Skills：渐进式披露的知识包

Skills 用三层渐进式披露按需投放领域知识，description 是触发命脉，SKILL.md 是路由器不是仓库

2026-07-21
AgentAIClaude

🎯 核心主张（一句话）

Skills 解决的是「知识的按需投放」：CLAUDE.md 是贴在墙上人人常看的制度，Skills 是文件柜里按岗位取用的 SOP——靠三层渐进式披露，用最小上下文成本换最大知识覆盖。

📖 正文

一、为什么 CLAUDE.md 不够用：两种知识，两种加载策略

组织里有两类知识资产。第一类是通用规则（技术栈、缩进、PR 格式），任何时刻都必须生效，所以必须常驻上下文、每次全量加载——这是 CLAUDE.md，代价是不管你在干什么它都占着 Token。第二类是岗位 SOP（API 文档规范、财务分析基准、审查清单），只在执行特定任务时才需要。把这类知识硬塞进 CLAUDE.md，你调试 bug 时那几千 Token 的文档规范照样赖在上下文里，稀释真正关键信息的权重。

Skills 就是给第二类知识建的文件柜：可跨项目复用、按需激活、用时才付 Token。 它不是一段 Prompt，而是一个工程化目录，能装文档、模板和可执行脚本；官方定义里用的动词是「教」而不是「命令」——目标是让 Claude 内化一个领域的做事方式，而非临时听指令。

二、三层渐进式披露：知识的投资回报率

装 20 个 Skill 会不会每次全部加载？不会。Skills 像图书馆检索：先看分类编目，再翻目录，最后只精读需要的章节。

  • 第一层 metadata：所有 Skill 的 description 常驻上下文，每个约百级 Token，只用于判断相关性。
  • 第二层 SKILL.md 正文：触发后才加载，约几百到两三千 Token。
  • 第三层捆绑资源：reference/、templates/、scripts/ 留在磁盘上，执行中按路由指引动态读取。

书中给的财务分析 Skill 实测：全套 5300 Token，问「毛利率怎么算」时只加载 SKILL.md + 利润率参考文件约 1800 Token，其余 3500 Token 零消耗。简单请求节省约 85%，扫描阶段节省 98%。这本质是软件工程的惰性加载（Lazy Loading）搬到了知识层。

三、description 预算池：写不好，Skill 就「不存在」

第一层不是免费的。所有 description 共享一个预算池——上限为上下文窗口的 2%，默认 16000 字符，由全部已安装 Skill 平分。装 20 个，每个平均只有 800 字符；某个 description 超额，它会被静默排除：Claude 根本看不见它，对用户来说这个 Skill 凭空消失，且没有任何报错。

三个实操手段：给纯手动触发的 Skill 设 disable-model-invocation: true（它的 description 不再进池子）；用 /context 诊断谁被静默排除；必要时调环境变量 SLASH_COMMAND_TOOL_CHAR_BUDGET 扩池。超过 20 个 Skill 通常是架构信号：该合并同类项、隐藏内部工具了，而不是继续堆。

description 的读者是 Claude 不是人，它是语义匹配的唯一信号。写法公式：功能定义（What）+ 触发场景（When，用 "Use when user..." 穷举用户的各种口语说法，包括不准确的说法如 Swagger/OpenAPI 混用）+ 排除范围（Not for...，防过触发）。两种失效模式对应两种修法：欠触发（Vercel 数据：无明确指引时 Agent 有 56% 概率完全不看可用 Skills）→ 往里加用户口语词；过触发 → 加负向约束。验收线：相关任务触发率 >90%，误触发率 <5%，用 10-20 条正反用例测。

四、两条执行路径：显式调用 vs 语义匹配

每个 Skill 都有双通道：用户输入 /skill-name（可带参数，走 $ARGUMENTS/$0 注入）是显式调用，确定无歧义；Claude 理解意图后自动加载是语义匹配，日常主力。选哪种交给「最坏情况测试」：如果 Claude 自动执行的最坏结果让你紧张（自动 commit、自动 deploy、误发通知），就设 disable-model-invocation: true 做成任务型 Skill；如果最坏不过是多读了一段文档，就保持默认，做参考型 Skill。 副作用越大，控制权越要收紧。

五、SKILL.md 是路由器，不是仓库

最常见的误区是把 SKILL.md 写成知识堆。正确定位是路由器：正文只放核心流程 + 路由表，详细知识散在被引用的文件里。两个关键技巧：

  1. Quick Reference 表：三列（分析类型 | 触发关键词 | 参考文件路径），三行只花约 50 Token，信息密度可达散文式描述的 10 倍。
  2. 契约式引用：别写 "See reference/revenue.md"，要写「当用户问收入增长/ARPU 时 → 加载 reference/revenue.md 获取公式和行业基准」——触发时机、位置、预期产出三要素齐全，Claude 才知道何时去取、取到什么。

配套的是 500 行法则：SKILL.md 超过 500 行（约 2000-3000 Token）说明你把参考资料和路由指令混在一起了。重构对策：大段公式→reference/，长示例→examples/，输出格式→templates/，确定性逻辑→scripts/，平行功能模块→拆成多个 Skill。

六、目录结构与 frontmatter 骨架

api-doc-generator/          ← kebab-case，仅 [a-z0-9-]，≤64 字符
├── SKILL.md                ← 必需，全大写精确匹配（skill.md 无效）
├── scripts/                ← 可执行脚本（确定性计算交给它）
├── reference/              ← 按需加载的领域文档
└── templates/              ← 输出模板

两条容易踩的坑：目录里禁放 README.md（Claude 激活时会贪婪读取目录下 Markdown，人类文档会污染指令空间，放父目录）；name 不得含品牌词。

frontmatter 字段分三组：身份（name / description / argument-hint，决定怎么被发现）、权限（disable-model-invocation / user-invocable / allowed-tools / model，决定谁能调、能干什么）、执行（context: fork 进隔离子智能体、agent 指定子智能体类型、hooks 挂生命周期钩子）。注意 disable-model-invocation 和 user-invocable 是正交的两个方向：前者禁模型自动调（留给 /commit 这类副作用操作），后者从 / 菜单隐藏但模型仍可内部调用（适合纯知识型辅助 Skill）。

allowed-tools 的原则是知识约束行动：审查类只给 Read/Grep/Glob；生成类给 Write 不给 Edit；Bash 用前缀白名单精控（Bash(git commit:*) 而非 Bash(*)——后者等于放弃防线，配合 !command`` 动态注入时尤其危险，因为用户输入会拼进 Shell 命令）。

七、四种设计模式与取舍

  • 模板驱动：模板锁死输出格式（周报、审查报告），产出可对比、可后处理。
  • 脚本增强：确定性计算封装成脚本。经验法则：发现自己在 SKILL.md 里写公式让 Claude 算，立刻停手，改成脚本。
  • 知识分层：80% 请求只需要 20% 内容——高频知识内联正文，低频进 reference/。
  • 工具隔离：allowed-tools 定「不能做什么」，这比定义「能做什么」更保安全。

何时不该用 Skill：只是个提示词模板 → slash command 就够；规则必须每次都生效 → 放 CLAUDE.md；行为必须 100% 强制 → 用 Hook（Skill 的触发终究是概率性的）；任务需要隔离上下文长时间跑 → 子智能体。Skill 的甜区是「有领域逻辑 + 有辅助文件 + 按需激活」的专业工作流。写完不是终点：触发测试、功能测试、有/无 Skill 各跑 5 次对比——每次你手动纠正 Claude 的同一个错，就是该更新 SKILL.md 的信号。

🧭 业界视角（书外补充）

  • Simon Willison：「Claude Skills are awesome, maybe a bigger deal than MCP.」他给的理由正对应本篇两个机制：发现（Claude 自己判断何时加载，不需要人记得）和确定性（用捆绑脚本产出一致结果）。很多人架 MCP server 做的事，一个带脚本的 Skill 更便宜、更稳——Skill 是 Markdown + 文件，MCP 是要维护的进程。
  • Skill 先行策略（社区共识）：三种扩展机制里 Skill 创建成本最低、见效最快。先写 Skill；需要 100% 强制时再加 Hook；需要上下文隔离时再上子智能体。 反过来先建重型机制，多数时候是过度设计。
  • Vercel 的减法教训：删掉 80% 的 Agent 工具后流程更快、Token 更省。映射到 Skills 就是 description 预算池的哲学——每个字符都在挤占别人的生存空间，少而精的 Skill 集比大而全的更容易被准确触发。
  • Anthropic 官方上下文工程原则：上下文是稀缺资源，性能随填充度衰减，三大手段之一就是 just-in-time retrieval。渐进式披露是这条原则在 Claude Code 里最完整的产品化实现。

🔗 知识网络