千笔-AIWritePaper · https://www.aiwritepaper.com
Agent 要同时「会很多流程」又「不把上下文撑爆」，靠的不是把手册一次性塞进 system prompt，而是按需加载。Anthropic 的 Agent Skills 把能力包成文件系统目录：入口是 SKILL.md，加载策略叫 progressive disclosure（渐进式披露）。官方文档写得很清楚：启动时只把元数据放进 system；用户请求匹配 description 后，再用 bash 读正文；更深层的 references、scripts、assets 只在任务真正用到时访问。脚本经 bash 执行，进入上下文的是输出，不是脚本源码本身。
本文依据官方 Agent Skills Overview，以及工程博文《Equipping agents for the real world with Agent Skills》，把三级加载、字段约束、Claude Code 目录、与 MCP / 整段 system 的对比摊开，并给出一份可核对的最小目录与检查清单。不编自制分数，只复述能对照文档的行为。
图：L1 始终在场；匹配 description 后加载 L2；L3 按需读文件或跑脚本，未访问不计 token。
目标说明
读完你应能独立完成五件事：
规格先钉死（来自官方 Overview）：
- 形态：文件系统目录；必需文件 SKILL.md（YAML frontmatter + Markdown 正文）。
- Level 1：name + description，启动时进入 system，约 ~100 tokens/skill；未触发时几乎无额外上下文代价。
- Level 2：请求匹配 description 后，Claude 用 bash（例如 cat …/SKILL.md）读入正文；官方表记为 Under 5k tokens；实践上正文常控在 500 行以内，超长细节外移到 references。
- Level 3：references / scripts / assets 按需；引用文件读入才占上下文；脚本经 bash 跑，只有输出进上下文。
- 字段：name 仅小写字母、数字、连字符，最长 64，且不能含 XML 标签与保留词 anthropic/claude；description 非空、最长 1024，且必须同时说明 做什么 与 何时用。
- Claude Code 路径：个人 ~/.claude/skills/；项目 .claude/skills/。
- API：Skills 跑在带 code execution 的容器里；自定义 Skills 的共享范围因表面而异（claude.ai 个人、API workspace、Claude Code 文件系统/插件）。
适用场景与边界
适合做成 Skill
- 可重复的程序性工作流：发 PR、改 PDF 表单、按仓库约定写测试、走固定审计步骤。
- 需要「很多技能并存」，但不能每轮把所有手册塞进 prompt。
- 细节很长（schema、API 参考、样例集），但单次任务只碰其中一小块。
- 希望确定性步骤用脚本落地：校验、转换、生成报表——输出短、源码不必进上下文。
- 团队要把「新人 onboarding 手册」固化成 Agent 可发现的包（官方比喻就是 onboarding guide）。
不该指望 Skills 单独搞定
- 需要稳定、契约化的外部能力调用：那是 MCP tools（或普通 function calling）的职责；Skills 教「怎么做」，tools 提供「可调用端点」。
- 一次性、无复用价值的临时指令：直接写在当前对话即可，不必建目录。
- 没有 code execution / 文件系统的运行面：API 侧必须带 code execution 容器；否则无法按官方模型用 bash 读 Skill。
- 跨表面自动同步：claude.ai、API、Claude Code 的自定义 Skills 不互通，要分别部署。
- 把 Skills 当「免审计插件市场」：不可信来源的 Skill 可能诱导工具调用、外联或泄露数据。
风险提示
官方安全章节要求：只使用可信来源；使用前审计 SKILL.md、脚本与资源；警惕外链拉取内容；把安装 Skill 当作安装软件。API 容器常见约束包括无网络、不可运行时装包；Claude Code 则与本机权限一致，网络可达性更强，治理要更严。
机制：三级加载如何咬合
Level 1 — 元数据始终在场
启动时，系统把每个 Skill 的 name 与 description 放进 system。模型靠 description 做相关性匹配。因此 description 不是摘要文案，而是触发条件说明书：写清能力边界，并列出用户可能说出的关键词与场景。官方 PDF 示例同时包含「能做什么」与「提到 PDF / 表单 / 抽取时使用」。
Level 2 — 触发后读 SKILL.md 正文
匹配发生后，Claude 从文件系统读入正文。正文放流程、约束、反模式与「下一步该读哪个文件」的指针，而不是把整本 API 手册贴进去。接近长度上限时，把专章挪到 FORMS.md、REFERENCE.md 等，并在正文里写明触发条件。
Level 3 — 按需资源与脚本
任务若只需抽取文本，就不必读表单指南。需要确定性操作时，跑 scripts/fill_form.py 之类；上下文只接收 stdout/stderr 或结果文件说明。这样 Skill 可以打包大体量资料，而未用部分为零成本。
与 system 塞满、与 MCP 的对照
| 整段 system / 长 CLAUDE.md | 每轮（或长前缀）常驻 | 极短、全局不变的硬约束 |
| MCP / tools | schema 常驻或按平台策略延迟；调用返回结果 | 外部系统 API、有状态工具 |
| Agent Skills | L1 常驻；L2/L3 按需 | 程序性知识、长参考、可执行步骤 |
Skills 与 MCP 可互补：MCP 提供工具面，Skill 提供「在什么顺序下调用哪些工具、如何验收」的流程包。工程博文也把 Skills 定位为可组合的领域专长，而不是替代工具协议。
触发条件怎么写才稳
把 description 当成「路由表条目」而不是产品简介。有效写法通常包含三类信息：能力动词（抽取、校验、合并、生成）、对象名词（PDF、changelog、schema）、场景线索（用户提到某关键词、正在做某类任务）。反例是只写「帮助处理文档」——几乎任何请求都能沾边，也几乎没有任何请求能精确命中。
同一仓库里多个 Skill 并存时，description 要互斥到「不会同时命中」或「命中后可组合」。例如 pdf-extract 与 pdf-forms 应在 WHEN 里切开：前者强调文本/表格抽取，后者强调填表与字段映射。官方强调 description 是主要触发机制，「何时使用」写在 frontmatter，而不是埋在正文深处等模型先读完再判断。
正文里如何指向 Level 3
推荐模式是：L2 给出默认最短路径；仅在分支条件成立时点名文件。例如「若需要高级填表，见 FORMS.md」「若校验失败，运行 scripts/validate.py」。这样模型有明确的下一步动作，而不是把 references 目录当知识库全文检索。对超过约 300 行的参考文件，官方实践建议在参考文件头部放目录，降低一次读入的盲目性。
步骤：写一份可验证的最小 Skill
1. 落盘目录（Claude Code）
项目级示例：
.claude/skills/
└── pr-checklist/
├── SKILL.md
├── references/
│ └── REVIEW_POLICY.md
└── scripts/
└── check_diff_stats.sh
个人级则放到 ~/.claude/skills/pr-checklist/。目录名与 name 字段建议一致，便于人与机器对齐。
2. 最小 SKILL.md
—
name: pr-checklist
description: 按仓库约定检查 PR 的测试、changelog 与风险说明。在用户要求开 PR、自检 diff、或提到 pull request / changelog 时使用。
—
# PR Checklist
## 快速流程
1. 用 git 查看当前分支相对主分支的 diff 范围。
2. 确认测试命令与 changelog 条目是否齐全。
3. 若 diff 统计异常（过大或仅格式化），先读 `references/REVIEW_POLICY.md`。
4. 需要机器汇总时，运行 `scripts/check_diff_stats.sh`，只根据脚本输出决策。
## 约束
– 不要在未读 diff 的情况下声称「已覆盖全部文件」。
– 政策细节以 `references/REVIEW_POLICY.md` 为准，不要凭记忆编造门槛。
注意：description 同时含 WHAT（检查测试/changelog/风险说明）与 WHEN（开 PR、自检 diff、提到相关词）。正文保持短，把政策长文外置。
3. 引用与脚本各放什么
- references/REVIEW_POLICY.md：阈值、禁止合并条件、审查问题列表——只在流程走到「需要政策」时读取。
- scripts/check_diff_stats.sh：输出增删行数、文件类型分布等短结果；避免把脚本全文贴进 Skill 正文反复占用 L2。
4. API / 多表面注意点
通过 API 使用时，需在 container 中启用 code execution，并按 Skills API / skill_id 声明。自定义 Skill 在 API 为 workspace 共享；在 claude.ai 为用户个人上传；在 Claude Code 为本地目录或插件分发。不要假设「上传一次处处可用」。
可验证点：渐进式披露检查清单
按下面清单自测；每一项都应能指出「看哪个文件 / 哪次行为」作为证据。
建议用两个对照请求做烟测：一条明显无关（例如问天气），一条明显命中（例如「按仓库约定帮我自检这个 PR」）。对比工具轨迹里对 Skill 文件的访问是否符合预期。
用「访问轨迹」而不是「感觉」验收
在 Claude Code 或带工具轨迹的会话里，把下列观察写成测试记录：
- 无关请求：轨迹中不应出现对该 Skill 目录下 SKILL.md 的读取。
- 命中请求：应出现一次（或少量）对 SKILL.md 的读取，且随后步骤与正文一致。
- 命中但走短路径：不应额外读取未引用的大体量 reference。
- 命中且需要脚本：应出现 bash 执行脚本；上下文增量主要是输出文本。
若你在自建 Agent 中复刻该机制，最小实现同样是三层：启动注入 metadata 列表；触发时 read_file(SKILL.md)；正文解析出的路径再按条件 read_file / run_script。不要在启动时把所有 SKILL.md 正文拼进 system——那会退化成 system 塞满。
踩坑
-
description 只写能力、不写场景：模型难以触发，Skill 变成「装了等于没装」。把用户原话里的关键词写进 WHEN。
-
把 L3 全塞进 L2：正文膨胀到接近或超过建议规模，触发即大额占上下文，渐进式披露名存实亡。
-
在正文里内联大段脚本：每次触发都为源码付 token；应改为 scripts/ + 执行。
-
用 Skill 代替 MCP：需要稳定 RPC/资源访问时，先暴露 tool，再在 Skill 里写调用顺序。
-
跳过审计直接装社区包：指令可诱导 bash 与文件操作；按官方建议当作安装软件。
-
忽略运行面差异：API 无网、不可随意 pip；Claude Code 权限更大——同一脚本可能一边能跑一边不能。
-
跨表面以为已同步：改了本地目录，不等于 claude.ai 或 API workspace 已更新。
-
用保留字或非法 name：含大写、下划线、空格，或夹带 claude / anthropic 等保留词，可能导致发现失败或校验拒绝。先按字符集与长度规则过一遍。
-
把动态会话状态写进 Skill：Skill 是可复用知识包，不是当前 ticket 的草稿。会话专属路径、临时密钥、单次分支名应留在对话或环境变量，避免污染可分享目录。
总结
Agent Skills 的核心不是「又一种 prompt 模板」，而是带发现元数据的文件系统知识包：L1 用廉价元数据换可发现性，L2 在触发后注入程序性知识，L3 把长参考与确定性脚本留在磁盘上按需使用。写好 description 的 WHAT+WHEN、把正文压在可触发的体量、用目录树表达懒加载，再用对照请求验证访问轨迹——这套闭环比空谈「增强 Agent」更可核对。
进一步阅读以官方为准：
- Overview：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- 工程博文：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- 开放规格可参考 agentskills 规范站点（若你的工具链声明兼容该格式）：https://agentskills.io
