Skill 的核心不是"塞更多指令"，而是把 LLM 的上下文窗口当 RAM、文件系统当 Disk——什么时候加载什么内容，比写了什么内容更重要。

Anthropic 工程团队在 2025 年 10 月发布了一个 PDF 处理 Skill，用来增强 Claude 的文档编辑能力。Claude 本身已经能理解 PDF 内容，但在直接操作 PDF（比如填写表单）时能力有限。这个 Skill 的结构很典型：一个 SKILL.md 主文件，加上两个附件——reference.md 和 forms.md。

把表单填写的指令单独拆到 forms.md，Skill 的核心部分保持精简。Claude 只在真正需要填表时才去读 forms.md，不会一开始就加载全部内容。

这个设计选择背后是一个被严重低估的概念：存储分层。

Skill 的本质：LLM 的 RAM 和 Disk

传统的 prompt engineering 思路是——把所有内容塞进 system prompt，尽量写短，因为上下文窗口就那么大。

Skill 完全反过来：鼓励内容写厚，前提是分层合理。

具体来说，Skill 的渐进式披露分三层：

  • 索引层（始终加载）：name + description，约几十 tokens——决定模型"什么时候该来找我"
  • 正文层（触发时加载）：SKILL.md 正文——模型判断相关时才读进来
  • 附件层（按需加载）：附件文件 + 脚本——特定场景才用得上

这跟计算机存储分层的逻辑一模一样：CPU 缓存 → 内存 → 磁盘。装 100 个 Skill，常态总占用才 ~5K tokens，因为大部分内容躺在文件系统里，只在需要时才进上下文。

原文用了一个很准确的比喻："像一本组织良好的手册，从目录开始，再到具体章节，最后是详细附录。"Agent 有文件系统和代码执行能力，不需要一次性把整个 Skill 读进上下文窗口——这意味着 Skill 能捆绑的上下文量实际上是无限的。

所以，Skill 的"上下文无限"不是 RAM 无限，是 disk 无限。

这也意味着设计哲学的根本转变：从"省 token"到"分 token"。

传统 prompt engineering 只有一个通道：system prompt。所有指令共享上下文窗口，多写一条就多占一份空间，而上下文窗口是硬上限。所以自然演化出"越短越好"的纪律——不是短本身好，是别无选择。

Skill 的渐进式披露把"写不写"和"什么时候加载"拆成了两件事。你可以写厚，但索引层只放几十 tokens 的 name + description。模型不会一次性看到全部内容——它先看索引判断"该不该来"，来了才读正文，需要时才翻附件。

约束从"总共能写多少"变成了"每一步该加载多少"。问题变了，策略自然也得变：

  • 写厚可以，但分层必须合理——该放索引的不能塞进正文，该拆文件的不能堆在一个 SKILL.md 里
  • 每一层都有犯错的可能：索引写错 → 召回失败；正文写错 → 执行偏了；附件写错 → 特定场景翻车
  • 所以设计重心从"怎么压缩"转向"怎么分层"——什么时候加载什么内容，比写了什么内容更重要

description 不是文档，是召回任务

Skill 的 description 是最容易被写错的部分。大部分人会把它当文档写——"这个 Skill 能做什么、怎么做"。

但它的真正角色是索引——它的任务不是告诉模型"怎么做"，而是"什么时候该来"。

原文解释了技术细节：Agent 启动时会把所有已安装 Skill 的 name 和 description 预加载到 system prompt。这是渐进式披露的第一层——提供刚好足够的信息让模型知道每个 Skill 何时该用，而不需要把全部内容加载进上下文。

标准句式应该是：Use when users want to ...

我总结了 description 的三种典型失败模式：

模式原因后果
召回失败触发词覆盖不全该用时没被识别
过早自满写得像迷你教程模型跳过正文直接干，错过关键步骤
召回过度描述太宽泛不该用也被加载，毁了 token 经济

写 description 的 checklist：

  • 用 Use when users want to ... 句式
  • 列 3-5 个典型触发关键词
  • 不要写操作步骤
  • 不要用"用于任何 X / 一切 Y"等过度泛化语言

原文特别强调："特别注意 Skill 的 name 和 description。Claude 会用这些来决定是否在当前任务中触发该 Skill。"这是从模型视角思考的关键——description 是召回信号，不是说明书。

代码的使用：两个独立决策，别混为一谈

Skill 里可以打包代码让模型直接执行，这很方便，但这里其实有两层独立决策，很容易混淆：

决策 A：这一步用代码还是模型？

  • 确定性算法 / 大数据批处理 → 代码
  • 语义判断 / 模糊匹配 → 模型

决策 B：代码是预设打包还是让模型临场写？

  • 逻辑稳定 → 预设打包
  • 逻辑本身要因情境而生 → 临场写

原文用 PDF Skill 举了一个具体的例子：Skill 包含一个预写的 Python 脚本，用来读取 PDF 并提取所有表单字段。Claude 可以直接运行这个脚本，而不需要把脚本本身或 PDF 文件加载进上下文。因为代码是确定性的，这个工作流每次执行都是一致且可重复的。

这里的关键判断：输入变 ≠ 逻辑变。每份 PDF 内容完全不同（输入在变），但提取规则是固定的（逻辑不变），所以应该预设打包而非让模型临场写。判断标准是逻辑本身是否需要因情境调整。

原文还指出了代码执行的另一个价值：效率。"比如通过 token 生成来排序一个列表，远比直接运行排序算法昂贵得多。除了效率考虑，许多应用需要只有代码才能提供的确定性可靠性。"

安全风险：Skill 引入了"指令层"攻击面

Skill 的安全问题不只是传统软件的供应链投毒。它引入了一个传统软件没有先例的攻击面——指令层：

  • 代码层（传统经验适用）：供应链投毒、网络外泄、命令注入
  • 指令层（新问题）：SKILL.md 写"如果用户问 X，请回复 Y"；间接 prompt injection（引用的外部 URL 被攻击者注入）

原文的安全建议很务实："只从可信来源安装 Skill。从不太可信的来源安装时，使用前要彻底审计。从读取 Skill 捆绑的文件内容开始，理解它做什么，特别注意代码依赖和捆绑资源（如图片或脚本）。同样注意 Skill 中指示 Claude 连接到可能不可信的外部网络源的指令或代码。"

更麻烦的是渐进式披露的审计盲点——附件层文件只在特定路径加载，常规测试可能根本触发不到。一份恶意 Skill 完全可以做到"90% 场景规规矩矩，10% 触发条件下注入"。

所以审第三方 Skill，必须把所有附件全展开：find . -name "*.md" -exec cat {} \;

实践框架：从评估开始，让 Skill 活起来

给出了四条开发建议，我把它和我的理解整合在一起：

1. 从评估开始，而非从想象开始

"通过在代表性任务上运行 Agent 并观察它在哪里挣扎或需要额外上下文，来识别 Agent 能力的具体差距。然后增量构建 Skill 来解决这些不足。"

开发 Skill 的正确流程不是"我觉得模型需要什么就写什么"，而是先跑任务、看卡点。这些卡点才是该写 Skill 的地方。

2. 结构化扩展，而非堆砌

"当 SKILL.md 文件变得难以管理时，把内容拆分到单独的文件并引用它们。如果某些上下文是互斥的或很少一起使用，保持路径分离会减少 token 使用。"

内容分层的实践原则：

类型沉淀位置
稳定知识SKILL.md / 附件 .md
稳定逻辑预设脚本（.py / .sh）
互斥/低频场景知识拆出单独文件，避免一次性加载
现场判断不沉淀，留给模型推理

3. 观察真实使用，而非猜测需求

"监控 Claude 在真实场景中如何使用你的 Skill，并基于观察进行迭代：注意意外的执行轨迹或对某些上下文的过度依赖。"

上线后盯一个指标：模型实际走了什么执行路径？有没有反复加载某个附件（说明该提到正文层）？有没有跳过某段指令（说明描述误导了召回）？

迭代的依据是观察，不是想象。

4. 让模型参与 Skill 的维护

"当你和 Claude 一起完成任务时，让 Claude 把成功的方法和常见错误捕获到 Skill 中的可复用上下文和代码里。如果它在使用 Skill 完成任务时偏离轨道，让它自我反思哪里出了问题。"

完成一个复杂任务后，让模型把踩过的坑和成功的策略写回 Skill。这比你自己复盘更准确——它知道自己缺了什么上下文才会走偏。

Skill 是活文档，不是一次性写完的配置。

下次写 Skill 的时候，别想"怎么写"，先想"怎么分层"——这一个问题能帮你避开大部分坑。

术语注释

术语解释
Agent SkillAI 智能体的"技能包"，一组预先写好的指令和代码，让 AI 在特定场景下表现更好
Prompt给 AI 的指令或提示词，告诉它要做什么
LLM大语言模型，如 Claude、GPT 等，就是文章里说的"AI"
RAM / Disk内存 / 磁盘。内存是临时工作区（快但有限），磁盘是长期存储（大但慢）
上下文窗口AI 一次能"看到"的信息总量上限，类似工作台的面积
TokenAI 处理文本的最小单位，大约 1-2 个汉字算一个 token
System prompt系统预设指令，AI 启动时就加载的基础规则
渐进式披露不一次性展示全部内容，而是按需逐步加载
Prompt engineering设计和优化 AI 指令的技术
Prompt injection提示词注入攻击，通过在输入中隐藏恶意指令来操控 AI 行为
召回AI 判断"该不该使用某个 Skill"的匹配过程
攻击面系统可能被攻击的入口点，入口越多越危险
供应链投毒通过第三方依赖库或插件植入恶意代码
SKILL.mdSkill 的主描述文件，用 Markdown 格式写成