Agent Skills 半年演变：从开放格式到可评测开发循环

事实核验截止日期：2026-07-17。本文保留 Agent Skills 与 skill-creator 的历史脉络；Claude Code 当前的 listing 预算、重复调用和 compact 恢复规则，以当日官方文档为准。

为什么需要 Skills

通用模型一旦面对团队内部流程，通常缺少 commit 规范、周报模板或报销字段等局部知识。能力缺口不在通用推理，而在可执行的本地流程和材料。

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。宿主在启动上下文里暴露可用 Skill 的轻量目录，模型据此判断是否需要调用；具体 API role 和消息包装属于各宿主的实现细节。

核心机制叫渐进式披露（Progressive Disclosure），分三级。第一级是 metadata，模型先得到一份受宿主预算约束的能力目录。第二级是 SKILL.md 正文，命中某个 Skill 时才读进来；当前官方 best practices 建议正文保持在 500 行以内，接近上限时拆分文件。第三级是 bundle 里的其他文件（references/、scripts/、assets/），按需加载，脚本可以直接执行而不必先把源码放进上下文。

官方示例是 PDF Skill。通用 PDF 理解能力并不包含特定表单的填写流程。填表逻辑放在单独的 forms.md，只在相关分支读取；字段抽取等确定性操作则写成 Python 脚本放入 scripts/，执行脚本比逐字段生成更稳定。

文章末尾提出了后续方向：

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

后续 skill-creator 覆盖了其中的创建与评估环节。

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

2025 年 12 月，Anthropic 把 Agent Skills 发布为开放标准，规范站点 agentskills.io 上线。Skills 从 Claude 的内部机制变成了跨平台的文件格式标准。

Simon Willison 当天的博客指出，该规范规模很小并有意留白。metadata 字段允许客户端保存规范未定义的属性，allowed-tools 被标为 experimental。当时列出的采用方包括 OpenCode、Cursor、Amp、Letta、goose、GitHub 和 VS Code；OpenAI Codex 随后加入。

这一步把 Skill 从单一产品能力推进到可由不同 Agent 宿主实现的公共格式。

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

2026 年 3 月，Anthropic 更新了官方的 skill-creator，即用来生成和维护其他 Skill 的 meta-skill，同时发布《Improving skill-creator: Test, measure, and refine Agent Skills》。社区文章把这一版称为 Claude Skills 2.0；它不是 Agent Skills 规范中的正式版本号。

这一版主要解决 Skill 缺少可重复评估的问题。零散运行少量 prompt 无法形成 baseline；模型版本或 SKILL.md 发生变化后，也难以定位输出回归来自哪一轮修改。

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

2026 版 skill-creator 改了什么

可重复的对比 eval

Skill 草稿完成后，skill-creator 要求准备 2~5 条真实测试 prompt。每条 prompt 分别运行 with-skill 与 baseline，随后把 pass rate、耗时和 token 消耗聚合成带均值与标准差的 benchmark，并在浏览器 eval viewer 中并排展示输出。

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

assertion 可选。文件转换、数据抽取和固定流程代码生成等存在确定答案的任务适合写断言；写作风格、设计等主观任务可以采用人工审阅。源码建议优先把可确定验证的条件写成脚本，以便跨 iteration 复用。

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

新版 skill-creator 的运行模型不同于常见测试框架。评测由 meta-skill、子 Agent、本地脚本和浏览器 viewer 共同完成。

eval 由 skill-creator 驱动。其目录除 SKILL.md 外，还包含 agents/grader.md、agents/comparator.md、agents/analyzer.md 三份子 Agent 提示，以及 scripts/aggregate_benchmark.py、eval-viewer/generate_review.py 等脚本。它把评测流程封装在 Skill 内，使用者负责提供用例、审核输出和决定是否继续迭代。

按 2026 年 3 月发布时的官方材料，完整评测流程以 Claude Code 和 Cowork 作为支持 subagent 与本地脚本的宿主。第三方客户端即使兼容 Agent Skills 格式，也不等于兼容这套评测运行时。

典型会话从创建某个 Skill 或优化既有 Skill 的触发率开始。skill-creator 收集输入、触发条件和输出样例，写出 SKILL.md 草稿，并把 2~5 条测试 prompt 保存到 evals/evals.json。评测阶段会为每个用例分别运行 with-skill 与 baseline 子 Agent，各自记录 total_tokens、duration_ms、transcript 和输出文件。grader 子 Agent 再按 agents/grader.md 对 assertion 生成 passed/evidence 判定。全部用例完成后，aggregate_benchmark.py 聚合出 benchmark.json 和 benchmark.md，generate_review.py 启动本地 viewer，展示两份输出及量化差异。使用者在 viewer 中审核用例并提交 feedback；skill-creator 根据 feedback.json 修改 SKILL.md，再进入下一轮。

产物全在本机磁盘上，是作者的文件，不是 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。grading.json 的 expectations 数组字段固定为 text/passed/evidence；其他字段名不符合 viewer 的输入契约。

使用者主要负责审核测试 prompt、给出具体反馈并决定停止条件。skill-creator 会生成初稿，但用例代表性和边界难题仍需人工审核。反馈应指向具体 case 和可观察问题，例如“eval-0 生成的 docx 第三栏列宽不足，文字被截断”；空 feedback 表示该 case 无需修改。可用的停止信号包括：需求已经满足、全部 feedback 为空，或连续两轮核心指标不再提升。最多 5 轮是该流程的默认迭代上限，不应解释为所有 Skill 的最佳轮数。

这套流程不要求另装 pytest、jest 等测试框架，也不要求使用者编写 subagent 并发逻辑或手写 grading.json。Claude Code 中的 eval 是面向 Skill 开发的本地循环，不等同于已经接入 CI 的持续回归系统；workspace 可以进入版本控制，供模型或 Skill 版本变化后重跑。

缺少相应 subagent 与本地脚本运行能力的宿主无法执行完整循环。退化方案是另行准备 prompt，分别运行 with-skill 与 baseline，再人工比较输出；这种方法缺少统一的工作区、聚合指标和 viewer。

eval 与 description optimization 是两条独立循环。eval 循环优化 SKILL.md 正文，包括流程、措辞以及 scripts/references 的组织；description optimization 优化 frontmatter 中用于候选选择的 description。两者使用不同的 prompt 集和脚本。

Blind A/B 会隐去两份输出的来源，再由独立实例选择较优结果并给出理由。可比较 with-skill 与 baseline、旧版与新版、两个同类 Skill，或同一 Skill 在不同模型上的表现。该机制依赖 subagents；2026 年 3 月的官方材料以 Claude Code 和 Cowork 为支持宿主。

用 train/test split 优化 description

description 写得不好时，Skill 正文仍然存在，但模型可能不会触发。候选选择主要依赖 metadata 中的描述，正文尚未进入工作集。Anthropic 文章指出 Claude 存在偏低的触发倾向，因此 description 需要同时写清能力和适用场景。

2026 年这版 skill-creator 把 description 调优做成自动循环。系统先生成 20 条接近真实请求的 prompt，一半应触发，一半不应触发；负例会包含相关关键词，但任务意图不属于该 Skill。使用者可在浏览器中修改、删除或补充这组 prompt。

20 条 prompt 会切成 60% 训练集与 40% 保留测试集，目的是防止描述过拟合到训练 prompt。在训练集上，每条 prompt 运行 3 次，至少 2 次命中才算触发成功。系统根据漏触发和误触发样本生成新版描述，最多迭代 5 轮，并要求各轮尝试实质不同的写法。

winner 由测试集分数而不是训练集分数决定，以降低对训练 prompt 的过拟合风险。训练集分数最高的版本不一定能泛化。

Anthropic 在 6 个内置文档类 Skill 上运行该优化循环，其中 5 个的触发率得到改善。这个结果说明 description 可以作为独立的选择层配置进行评测，但不代表任意 Skill 都能获得同等幅度的提升。

Skill 构建的方法论

结合 2026 版 skill-creator 源码（GitHub 仓库 anthropics/skills）和官方 best practices 文档，可以归纳出以下写法。

把 SKILL.md 写成目录

官方 best practices 建议 SKILL.md 正文保持在 500 行以内，接近这一规模时拆分文件。这个 500 行是作者侧的组织建议；Claude Code compact 时每个 Skill 最多回灌 5,000 tokens，是运行时恢复上限，两者不能换算成同一条规则。

SKILL.md 适合作为主流程与资源目录。主流程、判断分支和写作风格等高频内容保留在正文；API 文档、长案例和扩展语法放入 references/*.md 并按需引用；确定性计算、文件操作和格式验证放入 scripts/；模板、字体和图片放入 assets/。

一个 Skill 支持多个变体时，例如 cloud-deploy 同时覆盖 AWS、GCP 和 Azure，可以按变体拆分 reference，SKILL.md 只保留选择逻辑。运行时按当前分支读取所需 reference，其他材料继续留在工作集之外。

description 只写触发条件

description 同时影响发现与选择，边界需要单独处理。

一个代码审查案例显示，如果 description 概述了完整工作流，模型可能停在概述层而不读取正文。案例中的 description 只表达“进行代码审查”，模型完成一轮后停止，而正文要求分阶段执行两轮。把 description 收敛为触发条件，并把完整协议留在正文后，执行才覆盖两轮。

description 同时承担发现和选择职责，但不应替代正文中的完整协议。写法可以概括为 What it does + Use when [trigger phrases] + Key capabilities；完成后再用 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 的迭代过程。初版存在标题与正文字号冲突、表格列宽不足等问题。把包含三栏对比表的销售周报 prompt 纳入 eval 后，viewer 可以并排展示旧版和新版截图；后续将自适应列宽写进 scripts/，由 python-pptx 根据实际列宽调整。brand-guidelines Skill 也把主色检查从人工观察改为脚本化的 Delta E 比对，使 benchmark 从主观判断转为可重复验证。

这套循环也能观察模型升级带来的 regression。同一个 Skill 在模型版本变化后，触发率和步骤遵循情况可能发生偏移。保留 benchmark、旧版快照和固定 eval prompt 后，可以在更换模型时重跑，并通过 viewer 定位退化的 case 与步骤。

评估不应只看总分。grading 提供结构化指标，viewer 则把同一 prompt 的两版输出并排展示，支持逐 case 审阅。具体反馈应指向可观察差异，例如“第 3 条 case 生成的 docx 列宽仍然不足”，再据此修改 SKILL.md 并重跑。

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

skill-creator 的改进原则强调：少量 eval 用例只是快速反馈面，不应演变成只对固定样本有效的补丁集合。出现大量大写 MUST、ALWAYS、NEVER 或僵化结构时，应优先解释约束原因、适用边界和回退路径。

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

Anthropic 当前的 prompting best practices建议直接陈述工具使用条件，不必把 CRITICAL、MUST 等强语气当成默认写法。这里应当区分两件事：明确的强约束仍然可以存在，但大写命令不能代替原因、边界和回退路径。该建议属于 prompt 设计原则，不等于“大写措辞必然降低所有模型表现”的普遍定律。

僵化的命令式措辞还会遮蔽规则要保护的意图，典型场景是例外处理。NEVER call the production API without a 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 后，原因和回退路径都变得明确。skill-creator 源码中的同类反例是：ALWAYS use tool X 会在工具不可用时锁死任务，而 Use X because it gives structured output; if X fails, fall back to Y and note the degradation 保留了原意与降级路径。

description 与 SKILL.md 正文也可能发生冲突。代码审查案例中，description 概述为“进行代码审查”，正文则要求分两轮执行；模型完成一轮后停止。类似地，正文开头的 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 数量增加时，成本确实会上升，但不能再用「每个 Skill 固定约 100 token」或「20 到 50 个是安全上限」来估算。description 的长度、模型窗口、可见性配置、已调用正文和 compact 状态都会改变结果。

截至 2026-07-17，Claude Code 对 Skill listing 有明确预算：

默认预算为模型上下文窗口的 1%，可通过配置调整；
description + when_to_use 每项最多 1,536 个字符；
预算不足时保留全部 Skill 名称，优先缩减较少使用的描述；
disable-model-invocation: true 的 Skill 不进入模型可见目录，只能由用户显式调用；
/context 的 Skills 行用于观察当前会话实际占用，不能用安装目录数量代替。

这套预算治理修正了早期「description 随安装数量线性膨胀」的问题，但 listing 只是目录驻留成本。Skill 正文在调用后会进入会话历史，后续请求继续携带；Claude Code v2.1.202 起，相同渲染结果的重复调用只追加简短提示，参数或动态内容变化时才追加新正文。

Compact 形成独立的恢复成本。Claude Code 会重新附加近期调用的 Skill 正文，每个 Skill 最多取前 5,000 tokens，所有 Skill 合计最多 25,000 tokens，并从最近调用的 Skill 开始填充。较老 Skill 可能因总预算不足而整体丢弃。这个 5,000 是 compact 回灌上限，不是「典型 Skill 大小」。

因此容量评估至少要分开记录：

listing resident size
loaded body resident size
uncached input
cache creation input
cache read input
compaction rehydration size

社区 issue 和单次实测仍有历史价值，但它们只能说明某个版本、某组配置和某次会话的表现，不能升级为 Claude Code 的长期产品常数。若要比较安装规模，需固定 Claude Code 版本、模型、Skill 集合、调用状态和 compact 状态，再记录 /context 与 API usage。

Skill 与 Tool Search 处理的是两类目录

Skill progressive disclosure 面向指令、流程和资源包；Tool Search 面向工具 schema。二者都在解决「目录轻量常驻，正文或定义按需进入工作集」，但不能把 MCP server 数量、tool schema token 与 Skill metadata 直接相加后归因给同一种加载机制。

Anthropic Tool Search 允许把工具定义标为 deferred，模型先看到轻量搜索入口，需要时再加载具体 schema。是否启用、启用在哪组工具上由 API 与宿主配置决定，不能从「支持 Tool Search」推导出所有 MCP 工具都已自动延迟加载。

实操建议

项目级 Skill 放在 .claude/skills/，个人通用 Skill 放在 ~/.claude/skills/；显式调用型工作流可使用 disable-model-invocation: true，减少模型可见 listing。description 应写清适用任务和触发条件，并通过 /context 观察预算裁剪结果。

规模治理不应围绕某个固定数量展开。更可靠的门槛是：listing 是否被裁剪、关键 Skill 是否仍能正确路由、已加载正文是否挤压工作集、compact 后关键步骤能否恢复，以及 cache read/write 是否出现异常变化。

运行与维护建议

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

确定性操作适合写成脚本。Anthropic 的 PDF Skill 示例把坐标抽取等确定性逻辑放入脚本，从而减少每次生成的差异；散文指令与脚本承担的职责不同。

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

Skill 可以通过正文指令形成链式工作流。例如在一个 SKILL.md 中写明“完成 X 后调用 ai-writing-guard Skill 检查”，宿主与模型具备相应调用能力时，可继续选择下一个 Skill。该行为依赖宿主实现与候选可见性，不是 Agent Skills 文件格式本身保证的调用语义。