千笔-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。

目标说明

读完你应能独立完成五件事：

1. 说清 Skills 是「带 SKILL.md 的目录」，以及三级披露各自何时进入上下文、大致 token 成本。
2. 按官方字段规则写合法的 name / description（WHAT + WHEN），并解释为何 description 是触发器。
3. 搭出一份最小可运行的目录树：SKILL.md + references/ + scripts/，并知道 Claude Code 的个人/项目路径。
4. 用检查清单验证「未触发不读正文、触发后不盲目读全库、脚本只贡献输出」。
5. 对照 system prompt 塞满与 MCP tools：前者每轮全量计费；后者是可调用 API；Skills 是程序性知识包。

规格先钉死（来自官方 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 为本地目录或插件分发。不要假设「上传一次处处可用」。

可验证点：渐进式披露检查清单

按下面清单自测；每一项都应能指出「看哪个文件 / 哪次行为」作为证据。

1. L1 合法：name 符合小写/数字/连字符且 ≤64；description ≤1024 且含 WHAT+WHEN。
2. 未触发不读正文：启动后、在无关请求下，不应出现对 SKILL.md 正文的无故 cat；上下文应主要只有元数据占用。
3. 触发才读 L2：提出与 description 匹配的请求后，应看到对 …/SKILL.md 的读取，随后行为遵循正文流程。
4. L3 懒加载：任务不需要政策细节时，不应读取 REVIEW_POLICY.md；需要时才读。
5. 脚本只贡献输出：运行 scripts/* 后，上下文出现的是结果摘要，而不是整份脚本源码被当作文档加载。
6. 路径正确：Claude Code 下 Skill 位于 ~/.claude/skills/ 或 .claude/skills/；改完后新开会话或按产品文档刷新发现机制再测。
7. 安全审计：第三方 Skill 已人工过目 frontmatter、正文、脚本与外链；无不明网络调用与越权文件访问。
8. 表面隔离：同一 Skill 若要在 API 与 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