从 Skill 到 Skills 2.0：Anthropic 这半年怎么把 Agent Skills 做进软件工程

为什么需要 Skills

用 Claude Code 或者 Cursor 写一段时间代码，总会碰到同一种场景：模型通用能力很强，但一旦要求按公司内部流程办事，比如按团队的 commit 规范写一条 commit message、按固定模板出一份项目周报、按财务系统的字段填一份报销单，它立刻变回一个刚入职三天的实习生——不会写倒不是主要问题，它只是不知道这边是怎么干这件事的。

Anthropic 2025 年 10 月开始填这个坑，做出来的东西叫 Agent Skills。

时间线

2025 年 10 月 16 日：Skills 诞生

Anthropic 工程博客发了《Equipping agents for the real world with Agent Skills》，署名 Barry Zhang、Keith Lazuka、Mahesh Murag，文末缀了一句 “who all really like folders”。

文章对 Skill 的定义很朴素：一个 Skill 就是一个文件夹，里面有一个 SKILL.md，外加可选的脚本、参考文档和资源文件。SKILL.md 开头一段 YAML frontmatter，至少要有 name 和 description。agent 启动时把所有已安装 Skill 的 name 和 description 预加载进系统提示词，用来判断哪个任务该调哪个 Skill。

核心机制叫渐进式披露（Progressive Disclosure），分三级。第一级 metadata，所有 Skill 的 name + description 常驻上下文，模型只要一份目录知道有哪些能力可选。第二级 SKILL.md 正文，命中某个 Skill 时才读进来，理想长度 500 行以内。第三级是 bundle 进来的其他文件（references/、scripts/、assets/），按需加载，脚本甚至可以直接执行而不用先读进上下文。

官方举的例子是 PDF Skill。Claude 本身很会读 PDF，但不太会填 PDF 表单。填表的细节逻辑放在单独的 forms.md 里，只有真要填表时才去读；抽取表单字段这种确定性操作写成 Python 脚本放进 scripts/，直接执行，比让模型用 token 一个字段一个字段对着 PDF 抠便宜得多。

文章末尾埋了一句话：

Looking further ahead, we hope to enable agents to create, edit, and evaluate Skills on their own.

后来兑现了一半，就是 skill-creator。

2025 年 12 月 18 日：Skills 升级为开放标准

时隔两个月，Anthropic 把 Agent Skills 升级为开放标准，规范站点 agentskills.io 上线。Skills 从 Claude 的内部机制变成了跨平台的文件格式标准。

Simon Willison 当天的博客里给了一个挺精准的概括：规范小得可以几分钟读完，且有意留白。metadata 字段直接写"客户端可以用来存储规范未定义的其他属性"，allowed-tools 被明确标为 experimental。采用方名单里有 OpenCode、Cursor、Amp、Letta、goose、GitHub、VS Code，一天后 OpenAI Codex 也加了进去。

Anthropic 一年内先后把 MCP 和 Skills 推成了事实标准，同行里做规范比做护城河更常见的路数。

2026 年 3 月 3 日：skill-creator 的重做

让 Skills 真正好用起来的改动是半年后才落地的。2026 年 3 月，Anthropic 更新了官方的 skill-creator——一个用来生成和维护其他 Skill 的 meta-skill，同时发了一篇博客《Improving skill-creator: Test, measure, and refine Agent Skills》。因为这一版变化幅度够大，社区直接称它为 Claude Skills 2.0。

这一版没有再造新概念，解决的是一个具体的老问题：Skill 写完之后，几乎没法判断它到底有没有起作用。典型场景是随便跑两个 prompt 觉得差不多就收工；几周后模型小版本更新，或者自己改了两行 SKILL.md，某天发现输出变差，但根本定位不到是哪一步引入的回归，因为没有 baseline。

新版 skill-creator 把软件工程里那套开发循环搬了进来：写完草稿跑一轮可重现的对比测试，拿着两份输出做 diff，基于反馈改 SKILL.md 再跑下一轮。

2026 版 skill-creator 改了什么

可重复的对比 eval

Skill 草稿写完，skill-creator 会让作者凑 2~5 条真实的测试 prompt，对每条 prompt 同时跑两份，一份加载当前 Skill，一份裸跑 Claude。跑完把结果聚合成 benchmark（pass rate、耗时、token 消耗，带均值和标准差），再在浏览器里打开 eval viewer，左右对照展示两份输出。

baseline 是自动切换的。新建 Skill 时 baseline 就是不加载任何 Skill 的裸 Claude；迭代已有 Skill 时，skill-creator 会先把旧版本快照到 skill-snapshot/，然后用旧版本当 baseline，这样每轮都能看到"比上一版进步了多少"，而不是只跟裸模型比。

assertion 可选。文件转换、数据抽取、固定流程代码生成这种有确定答案的任务适合写断言；写作风格、设计这类主观任务就不必硬上断言，让人看输出即可。官方源码里埋了一条建议：能用脚本验证的就写脚本，不要肉眼看，脚本可以跨 iteration 复用，比人眼可靠。

eval 是谁跑的、跑在哪、作者要做什么

新版 skill-creator 最容易劝退人的地方就是它的运行模型和常见的"测试框架"不是一回事。是自己写 pytest？装什么框架？跑在本机还是 Anthropic 服务器？作者具体要做什么？

eval 是 skill-creator 这个 meta-skill 自己跑的，不是作者跑的。把 ~/.claude/skills/skill-creator/ 翻开看一眼就明白了，里面除了 SKILL.md，还躺着 agents/grader.md、agents/comparator.md、agents/analyzer.md 三份子 agent 的提示词，以及 scripts/aggregate_benchmark.py、eval-viewer/generate_review.py 两个脚本。skill-creator 自带一整套评测基础设施，它的定位不是"教作者怎么写 Skill"，而是"替作者把 eval 流水线跑通"。作者跟它的交互层级更接近产品经理对工程团队，而不是程序员对 IDE。

这套基础设施硬依赖 subagents，所以现实里只能在 Claude Code 和 Cowork 里跑，Claude.ai 网页端没有 subagent 能力，跑不了。OpenCode、Cursor、Amp 这些第三方客户端理论上只要支持 subagent 就能用同一份 skill-creator，但官方测试场是前两个。

典型的一次会话长这样。作者打开 Claude Code，说一句"帮我给这个仓库做一个生成周报的 Skill"，或者"我 ~/.claude/skills/weekly-report/ 这个 Skill 触发率有点低，帮我跑一轮 eval"。skill-creator 的 description 命中之后，Claude 进入它定义的工作流，反过来问作者：要支持哪些输入、什么时候该触发、有没有期望的输出样例，然后写出 SKILL.md 草稿，跟作者一起把 2~5 条测试 prompt 落到 evals/evals.json。接下来才是真正的 eval。Claude 在同一个回合里 spawn 一批 subagent，每个测试用例两份，一份加载 Skill，一份不加载，各自独立完成任务。每个 subagent 跑完回传 total_tokens 和 duration_ms，落到对应目录的 timing.json。Claude 再 spawn 一个 grader subagent，按 agents/grader.md 的协议读取 transcript 和输出文件，对每条 assertion 给出 passed/evidence 判定，写成 grading.json。所有用例跑完，Claude 直接调 python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>，把所有 grading.json 聚合成一份 benchmark.json（pass rate、tokens、duration 的均值和标准差）和一份 benchmark.md。最后 Claude 在本机 nohup 起一个小服务器（eval-viewer/generate_review.py），自动打开浏览器，左边 with_skill 的输出，右边 baseline 的输出，下面 Benchmark tab 给量化对比。这一整段流程不需要作者敲任何命令，只需要在浏览器里点用例、留 feedback、点 “Submit All Reviews”。skill-creator 拿到 feedback.json 后，把吐槽对应到具体用例，改一版 SKILL.md，再开 iteration-2/ 重跑。

产物全在本机磁盘上，是作者的文件，不是 Anthropic 的云服务。目录契约是固定的，理解它对排查问题很重要：

~/.claude/skills/weekly-report/          # Skill 本体
~/.claude/skills/weekly-report-workspace/ # 平级工作区，所有 eval 产物都在这
├── iteration-1/
│   ├── eval-0-some-name/
│   │   ├── with_skill/
│   │   │   ├── outputs/        # subagent 实际产出的文件
│   │   │   ├── transcript.md   # subagent 的完整执行记录
│   │   │   └── timing.json
│   │   ├── without_skill/      # baseline 同结构
│   │   ├── eval_metadata.json
│   │   └── grading.json        # grader 的判定结果
│   ├── eval-1-.../
│   ├── benchmark.json          # 聚合后的整轮指标
│   ├── benchmark.md
│   └── feedback.json           # viewer 里留的反馈
├── iteration-2/                # 改完 SKILL.md 后的下一轮
├── skill-snapshot/             # 旧版本 SKILL.md 快照，作为 baseline 参照
└── evals/evals.json            # 测试 prompt 集，跨 iteration 复用

benchmark.json 有一个细节容易踩：每个 with_skill 配置必须紧挨着排在它对应 baseline 的前面，viewer 才能正确渲染 delta，这是 schema 的硬约束。grading.json 里 expectations 数组的字段名固定是 text/passed/evidence，写成 name/met/details viewer 会直接报错。平时不会踩到这两个坑，但想手写 grading.json 覆盖某条 case 时就得注意。

用户在这套流程里真正要干的事其实不多，剩下都交给 skill-creator。最关键的一件是 review 测试 prompt：skill-creator 自己会拟一版，但 Skill 到底会被怎么用、哪些 case 有代表性、哪些是钉子户难题，只有用户自己知道，随手批准一份太宽松的 prompt 集，后面 benchmark 数字就都没意义了。其次是在 viewer 里给具体 case 留具体反馈，“整体感觉差点意思"没用，要写"eval-0 生成的 docx 第三栏列宽不够，文字被截断了"这种，越具体下一轮 skill-creator 改得越准（空 feedback 不代表惩罚，等价于"这条 case 满意”）。还剩一件是判断什么时候停，大致几个信号可以用来收工：用户觉得够了、所有 feedback 都空、连续两轮 benchmark 核心指标不再提升。5 轮以内一般就到边际效用拐点，不要为了"再优化一下"无限刷迭代。

明确不用做的事同样重要：不用装 pytest、jest 之类测试框架；不用自己 spawn subagent 或写并发代码；不用手写 grading.json（除非要覆盖某条 case）；不用把 evals 配到 CI 里。Claude Code 里的 eval 是面向 Skill 作者的本地开发循环，不是面向流水线的回归测试，虽然整个 workspace 完全可以提交到 git，下次换模型时 Claude 直接重跑也能出对比报告。

Claude.ai 网页端的用户用不了完整循环。退化方案是手写 SKILL.md，自己拟几条 prompt 在两个对话窗口分别跑（一个加载 Skill 一个不加载），肉眼对比。能用但难规模化，所以 Anthropic 实际上在用 skill-creator 把"严肃的 Skill 开发者"温柔地推向 Claude Code。

还有一个常被问到的问题：这套 eval 跟 description optimization 是同一回事吗？不是，是两条独立循环。eval 循环优化的是 SKILL.md 正文（流程、措辞、scripts/references 怎么组织），description optimization 优化的是 frontmatter 里那一句 description（决定 Skill 会不会被触发）。两者用的是不同的 prompt 集和不同的脚本，都属于 skill-creator 的内置能力。

改了一版 Skill，想确认新版是不是真的更好、而不是作者觉得更好，skill-creator 可以把两份输出隐去来源，交给一个独立的 Claude 实例评判，让它挑出赢家并给出理由。能比较的组合包括：有 Skill 对没 Skill、旧版对新版、两个做同一件事的不同 Skill，以及同一个 Skill 在两个不同模型上的表现。机制依赖 subagents，目前只在 Claude Code 和 Cowork 里可用。

用 train/test split 优化 description

description 写得不好时，Skill 的逻辑还在，但模型根本不会触发。触发机制完全走 description 字段，模型只看那段描述就决定要不要激活。Anthropic 自己在文章里承认，Claude 天然有"低触发倾向"，哪怕 Skill 对当前任务明显有用，也常被跳过，所以 skill-creator 里反复强调 description 要写得有点推力。

2026 年这版 skill-creator 把 description 调优做成了自动循环。先让 Claude 生成 20 条真实风格的 prompt，一半应该触发、一半不应该触发；不该触发的那些是故意写成有迷惑性的，关键词沾边但其实要干的不是一回事。用户在浏览器里审阅这份 prompt 集，可改、可删、可加。

20 条 prompt 会切成 60% 训练集 + 40% 保留测试集，就是机器学习里经典的 train/test split，目的是防止描述过拟合到训练 prompt 上。在训练集上跑时，为了对抗模型行为的随机性，每条 prompt 跑 3 次，2/3 以上命中才算触发成功。看哪些该触发没触发、哪些不该触发却触发了，让 Claude 基于失败样本写一个新版本的描述。最多迭代 5 轮，每轮都能看到之前所有版本，并被明确告知不要和前面几版重复，逼着它尝试实质不同的写法。

选 winner 时用的是测试集分数而不是训练集分数，这是整个流程里最关键的防过拟合设计。训练集分数最高的那版可能只是把训练 prompt 记住了，未必能泛化。

Anthropic 在自家 6 个内置文档类 Skill 上跑了这个优化循环，其中 5 个触发率有改善。description 是个容易被当成"随便写两句"的字段，但把它当可优化对象跑一轮 train/test，实际回报和工作量的比值挺不错。

Skill 构建的方法论

2026 版 skill-creator 源码（GitHub 仓库 anthropics/skills）和官方 best practices 文档合起来看，实际可抓住的写法就这么几条。

把 SKILL.md 写成目录

新手最常见的毛病是把所有知识都往 SKILL.md 里塞，写出一个 2000 行的巨无霸，然后奇怪 Claude 为什么调用得这么慢。500 行是反复提到的上限，官方 best practices 给的是 “5000 单词以内”，两个口径差不多等价。

比较好的写法是把 SKILL.md 当目录用。主流程、判断分支、写作风格这种每次都要看的东西放在 SKILL.md 本体；API 文档、长案例、扩展语法这种只有部分分支才用得到的东西放 references/*.md，从 SKILL.md 里按需指向；确定性计算、文件操作、格式验证这种写成代码更准的放 scripts/；输出要用到的模板、字体、图片放 assets/。

一个 Skill 要支持多个变体（比如一个 cloud-deploy Skill 同时覆盖 AWS、GCP、Azure）时，就按变体拆分 reference，SKILL.md 只负责选型逻辑。Claude 只读真正需要的那个 reference，其它的根本不进上下文。

description 只写触发条件

description 是最容易写错的字段。

本地那份 writing-skills 的 SKILL 文档里记了一个踩坑经验：如果在 description 里概述了 Skill 的工作流程，Claude 可能直接按 description 的概述执行，而不去读 Skill 正文。原话是一个代码审查 Skill，description 里写了"进行代码审查"，结果 Claude 做了一轮审查，但 Skill 正文里写的是分阶段两轮。把 description 改成纯粹的触发条件（“当执行带独立任务的实施计划时使用”）、不再描述流程之后，Claude 反而老老实实读 Skill 正文，按正文的流程走了两轮。

背后的逻辑不复杂：description 是工作流的捷径，它能独立工作的时候，模型就不再读正文了。所以写 description 有一条反直觉的纪律——只描述触发条件，别把流程一起写进去。官方公式是 What it does + Use when [trigger phrases] + Key capabilities。写完以后用 skill-creator 的 description optimization 跑一轮，能把触发准确率再拉一截。

把评估当成默认开发环节

2026 版 skill-creator 在推的范式转变就是这个：评估不再是做完 Skill 以后"有空再跑"的事，而是写 Skill 的默认开发环节。完整的循环长这样：

写 SKILL.md 草稿
  ↓
整理 2~5 条真实 prompt 进 evals/evals.json
  ↓
同一回合内并发跑 with-skill 和 baseline 两套
  ↓
启动 eval-viewer，人对着 diff 留反馈
  ↓
读 feedback.json，做下一轮修改
  ↓
新建 iteration-N+1/ 目录，重跑
  ↓
直到反馈都为空或者用户满意
  ↓
（可选）跑 description optimization
  ↓
打包成 .skill 文件交付

每轮的结果（输出、timing、grading、benchmark）都落在 <skill-name>-workspace/iteration-<N>/eval-<ID>/ 下，可追溯、可对比。下一轮带 --previous-workspace 参数时，viewer 里能看到每个 case 的上一版输出和上一版反馈，迭代手感很接近打磨代码。

Anthropic 官方在博客里展示过 pptx 生成 Skill 的迭代过程。第一版让 Claude 生成 PPT，标题字号和正文字号经常打架，表格列宽也常塞不下最长的那条数据。他们把"生成一份包含三栏对比表的销售周报"这类 prompt 放进 evals，跑完之后 viewer 左边是旧版本 PPT 截图、右边是新版本，一眼就看得出改好了没有。到第三轮作者才意识到字号问题不该靠 prompt 里的文字描述解，应该在 scripts/ 里写一个 autofit_table.py，用 python-pptx 拿到实际列宽自动调整。brand-guidelines Skill 的迭代也类似，起初靠肉眼看输出是否符合品牌色，跑五次会得到五种不同的"几乎符合"，后来干脆把 assertion 写成脚本，抽取生成图的主色做 Delta E 比对，超过阈值判失败；脚本一写，benchmark 就从主观打分变成了可以每版自动跑的回归测试。

这套循环另一个不太明显的用途是抓模型升级带来的 regression。同一个 Skill 在 Claude 小版本升级后行为常常悄悄漂移，以前 100% 命中的触发词可能降到 80%，以前按步骤跑两轮审查的现在只跑一轮。没有 benchmark 留档，这种偏移几乎不可能被注意到，因为每次输出都还是"差不多能用"的样子。有上一版本快照做 baseline、有一组固定的 eval prompt，换模型第一天就能重跑一遍，哪些 case 退化了、退化在哪一步，viewer 里一目了然。这也是为什么 Anthropic 把旧版本自动快照做成默认行为：跨模型回归测试原本是要专门建设的能力，现在顺手就能做。

社区复现这套循环最常见的误区是把"评估"理解成"打分"。skill-creator 源码里的 grading 其实是副产品，主产品是带 diff 的 viewer——一条 prompt 的两版输出并排摆着，作者 30 秒内就能判断这一版是不是朝期望方向走，比任何总分都直观。比较成熟的用法是一天迭代五六次，每次扫一眼 viewer，留一两条具体反馈（“第 3 条 case 生成的 docx 里列宽还是不够”），让 skill-creator 基于反馈生成下一版 SKILL.md，然后继续跑下一轮。

改进时不要过拟合到几个测试用例上

skill-creator 源码 Improving the skill 部分有两段值得抄出来（原文英文，此处翻译并略作转述）：

我们在写的是要被用一百万次甚至更多的 Skill。你和用户反复在几个例子上迭代，只是因为这样推进得快，用户对这几个例子门儿清，评估起来也快。但如果这个 Skill 只在这几个例子上好使，那它就没用。与其往里加一堆细抠小细节的修正，或者堆一大坨压迫性的 MUST，不如跳出来试试不同的隐喻、不同的工作模式。反正试一次很便宜。

以及：

如果你发现自己在写全大写的 ALWAYS 或 NEVER、或者非常僵化的结构，这就是一个黄牌信号。如果可能，换成解释原因的措辞，让模型理解为什么这件事重要。今天的 LLM 是聪明的，它们有不错的心智理论能力，给一个好的 harness，它们能超越死记硬背，真正把事情做成。

全大写的 ALWAYS / NEVER / YOU MUST 看起来像在加强约束，实际效果和作者的预期几乎相反，背后有几个原因。

最直接的一个原因是早期模型的历史遗产在新模型上会过度触发。2023 年那会儿 GPT-3.5 指令遵循弱，温和的 “please follow this rule” 常常被当没看见，用户只好写 YOU MUST NEVER EVER OUTPUT JSON OUTSIDE THE TAGS 才有响应。到 Claude 4.5/4.6、GPT-5 这一代，模型能读出"语气"了。Anthropic 的 prompting best practices 里明确建议：过去写 “CRITICAL: You MUST use this tool when…”，现在直接写 “Use this tool when…” 就够了。Gabriel Anhaia 一篇 2026 年的实证对比里也观察到，上一代为了对抗"欠触发"设计的吼叫式 prompt，在 Claude Opus 4.5/4.6 上会变成"过度触发"，模型把敌意语气当成敌意上下文，反而更容易拒答、更容易刻板复述规则、更容易在输出里原样回吐一遍那条 NEVER。社区把这种现象称作 compliance theater（合规戏），模型不是在照规则做事，而是在表演自己看到了规则。

僵化的命令式措辞还会遮蔽它自己要保护的意图，最典型的场景是例外处理。写 NEVER call the production API without a dry-run 听起来很严密，但如果某一类任务本来就没有 dry-run 接口，或者正在跑的就是 dry-run 校验的测试流水线，模型面对这条规则要么硬套（去调一个不存在的 dry-run 接口），要么干脆跳过整个流程以示"遵守"。换成 Prefer to dry-run first so we can surface schema mismatches before touching prod data; if no dry-run exists, print the intended payload and ask the user to confirm，原因和兜底都讲清楚了，模型遇到没想到的情况自己会对齐。Anthropic 官方 skill-creator 源码里的反例就是这一类，ALWAYS use tool X 在工具 X 暂时不可用时会把任务锁死，而 Use X because it gives structured output; if X fails, fall back to Y and note the degradation 能让模型在维持原意的前提下继续工作。

还有一种情况是 description 和 SKILL.md 正文打架。前面提到过作者自己踩的那个坑：一个代码审查 Skill，description 只写"进行代码审查"，正文里写的是"分两轮审查"，结果 Claude 按 description 的概述跑了一轮就停了。ALWAYS / NEVER 往往也是这样被注入的，作者在 SKILL.md 开头塞一块 YOU MUST ALWAYS... 的大写块，本意是"我这里特别重要你要看完"，但它读起来像一个自洽的小闭包，模型反而真的把它当结论用了，底下正文那套更细的流程根本没被读进来。换成 Why two-pass review matters: first pass catches correctness, second pass catches style consistency. See below for the full protocol. 之后，模型才会老老实实往下读。

所以写 SKILL.md 的时候，把"为什么这么做"交代清楚，模型遇到没预想到的分支时自己就能对齐。真正需要机器级强制的约束，比如"不要把生产数据库密码写进日志"，放在 prompt 里本来就不可靠，应该在执行层做下游校验。

跨测试用例抽取通用脚本

跑完 eval 以后，读每个 subagent 的 transcript，看它们是不是都独立写了类似的辅助脚本。如果 3 个测试 case 的 subagent 都分别写了一个 create_docx.py 或 build_chart.py，说明这段代码应该抽出来放进 Skill 的 scripts/ 里，写一次以后每次调用直接用。高频被调用的 Skill 做这一步的收益很大。

Skill 装多了会把上下文窗口撑爆

Skill 越写越多之后，每次会话一开始上下文就先被一大堆 description 占掉。这个顾虑半年下来一直没消失。

Anthropic 给这件事起过一个名字，叫 progressive disclosure 的第一层。每个 Skill 的 YAML frontmatter（主要是 name + description）会在会话初始化时一股脑进系统提示词，让 Claude 能看到当前手头有哪些能力。官方的参考数字是每个 Skill 大概 100 token（name 几个 token，description 一到两句话）。按 Claude 200k 上下文窗口算，100 个 Skill 是 10k token、占 5%，500 个约 50k、占 25%，到 1500 个左右会把上下文直接打穿。按"只加载名字和描述，正文按需拉取"的算盘，数字本来不难看。

真实使用里有两件事让理论数字变难看。第一，Skill 要和其他全局上下文抢位置。Claude Code 的 session 里还有 CLAUDE.md、custom agents、subagent 定义、MCP tools，都是进会话就常驻的。2026 年 2 月社区在 anthropics/claude-code 仓库开了 issue #22613，标题直接叫《Feature request: lazy-load agent descriptions and skill names to reduce context usage》。作者测过一个典型重度用户的配置：13 个 GSD agents 在描述里吃掉约 5000 token，27 个 gsd:* skill 再吃 800 token，其他自定义 agent 再加 1000 token，加上 CLAUDE.md，一次空会话起手就 20%+ 上下文已经没了，还没说一句话。

更糟的是实测感知比理论数字更难看。bswen 在 2026 年 3 月写过一篇实测：他装了 45 个 Skill，首次响应延迟从 3 秒飙到 8 秒，多文件操作反复撞上下文上限；清到 15 个之后，首次响应回到 3 秒，复杂任务不再中途失忆。Reddit 上有一条高赞评论说得更直白：“that startup scan at 100 tokens per skill kills you if you install more than 30.”

所以 20~50 这个经验上限大致对应 2~5k token 的 startup 开销，这个量级基本感知不到；超过 50 之后感知迅速非线性恶化，不只是多吃 token，更重要的是剩下的可用上下文在真正写代码时会频繁告急。

让模型自己决定何时加载

这个问题在社区里有一个通用说法叫 skill context bloat（技能上下文膨胀），相关讨论里比较主流的思路就是"预先告知本次项目会用到的 Skill 范围，什么时候真正进上下文由模型决定"。

目前被讨论或已落地的做法有三条路。

一条是项目级 scope，已经可用。Claude Code 支持在项目根目录放一个 .claude/ 目录，里面只装这个项目需要的 Skill，并在 CLAUDE.md / .claude/config.json 里显式声明启用/禁用清单。全局 ~/.claude/skills/ 放日常驾驶员级别的通用 Skill（代码审查、commit 规范之类），项目目录放领域专属 Skill（某框架的脚手架、某业务的模板）。立刻可用，代价是完全依赖人来划定范围，项目本身大或者跨域的时候，池子还是会膨胀。

另一条是 lazy-load description，目前还是 feature request。Issue #22613 里的方案是系统提示词里只注入 Skill 的名字（或者一个极短的 tag 列表，比如 pptx, docx, pdf, brand, ...），description 正文不进；模型判断要不要用某个 Skill 时，先发一个"查一下这个 Skill 的 description"的内部调用再读进来。等价于给 progressive disclosure 再加一层，从两级变成纯名字 → description → SKILL.md 正文 → bundle 资源。这个 issue 当时被 Anthropic 关了、没给明确时间表，但类似诉求在 OpenCode、Cursor 的 Skills 实现里以相近形态出现，说明大家判断差不多：静态全量注入 description 是 progressive disclosure 没做彻底留下的缺口。

最激进的一条是 skill router / skill pack，目前还在社区实验阶段。玩法是系统提示词里根本不放具体 Skill，只放一个路由 Skill，它的 description 大意是"用户提到写 PPT 就去 ~/.claude/skills/pptx/ 看，提到品牌规范就去 brand-guidelines/ 看"。真正的 Skill 池被扁平化成路由表里的一条条 tag → path，router 根据用户 prompt 的语义让模型自己去拉正文。GitHub 上已经有一些这个方向的尝试（比如 SZoloth/skill-pack、alirezarezvani/claude-skills 的 bundle 机制）。缺点是多一跳，首次命中延迟会比静态注入稍高；Skill 规模到 200+ 级别的时候，这点延迟换到的上下文空间是划算的。

三条路其实可以叠着用：10~15 个最常用的 Skill 全局常驻，项目目录里装 20 个领域 Skill，再用一个轻量 router 把团队私有的 100+ Skill 分域挂在背后。

MCP 一年前踩过同样的坑

Skill 遇到的这个问题，MCP 一年前就先踩过一遍，解法可以参考。

MCP 的 tool 一开始是全量注入：每个 MCP server 的所有 tool schema 都在会话一开始就进系统提示词。接入多个 server 之后很快撑爆，一个只装了 GitHub、Jira、Postgres、Slack 四个 server 的配置，schema 就能占到 15k+ token。社区后来推的解法叫 dynamic tool discovery：模型先只看到"有哪些 server 可用"（每个 server 一两行说明），真要用时再 list_tools 拉具体 schema。

Skill 的 progressive disclosure 和 MCP 的 dynamic tool discovery 解决的是同一类问题，一个作用在知识和流程上，一个作用在工具和 API 上。任何常驻上下文的东西，只要规模会线性增长，迟早都要走分层和懒加载这条路。Reddit 上有一句总结挺到位：“Skills are progressively disclosed, but MCP tools load all-at-once.”，这句话现在其实已经不太准确了，MCP 也在补这一课。

实操建议

Skill 数量管理的一些经验是这样的。最常用的 10~15 个装全局，项目专属的装 .claude/skills/，长尾的单独放一个 ~/.claude/skills-backup/ 留着但不启用。写 description 的时候把它当一条路由规则写，触发条件比能力描述重要，写得精准才不会让模型误触发去加载正文。再加一个定期审计的习惯，bswen 文章里那个 shell one-liner（ls ~/.claude/skills | wc -l 乘以 100）就够用，突破 3000 token 就该清了。

规模再大一档就上 router 或者按 workspace 切 profile。Claude Code 目前支持在 .claude/config.json 里显式声明 enabled/disabled 清单，是目前最轻量的 scope 手段。另外值得关注 Anthropic 和 Claude Code 后续 release notes 里关于 lazy description loading 的动向，这件事官方大概率会做，只是时间问题。

一些其它的零散经验

新模型发布后重跑一轮 benchmark 是值得养成的习惯。上一代模型能 100% 命中的 Skill，在新模型上行为未必一致，skill-creator 的 benchmark 基础设施本来就是为跨模型回归测试准备的。

确定性操作尽量写脚本。Anthropic 官方的 PDF Skill 早期让 Claude 按散文指令去填表单位置，效果很差；后来把坐标抽取逻辑写成脚本，问题直接消失。散文指令做不到每次调用都一致，脚本可以。

给 Skill 加一个版本号。在 frontmatter 里放一个 metadata.version 字段，benchmark 出问题的时候能快速对齐到具体版本。

Skill 之间是可以串起来用的。在一个 Skill 的 SKILL.md 里明确写"完成 X 以后，调用 ai-writing-guard Skill 检查一遍"，Claude 会真的链式触发下一个 Skill。这样复杂工作流可以拆成一堆职责单一的小 Skill 组合起来，不用硬塞进一个巨型 SKILL.md。