至少从 2025 年下半年到我写这篇（2026-05-06）这段产品叙事看，“Agent Skills"是一个在 AI 工具圈快速升温的概念：Anthropic 在 Claude / Claude Code 里推它，Cursor、GitHub Copilot、Gemini CLI、OpenCode、Goose、Roo Code 等一批工具也陆续宣布支持，agentskills.io 则把它整理成了一个开放标准。至少在叙事层面，它确实有点像 AI 工具圈想长出来的一个"USB-C 接口”。

但热闹归热闹，更冷静的那一面是：skill 真的有用吗？什么时候有用？怎么知道它有用？ 这一篇我把三份资料串起来聊一下：

我现在更愿意把 skill 拆成两个层面来看：规范层面，它解决的是上下文如何按需分发；工程效果层面，它解决的是这份指令包能不能在你当前仓库里产生净增益。 前者解释它为什么会流行，后者决定它值不值得进你的工作流。

Agent Skills 是什么#

按照 agentskills.io 的定义，一个 skill 本质上就是一个文件夹 + 一个 SKILL.md：

my-skill/
├── SKILL.md          # 必需：metadata + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
├── assets/           # 可选：模板、资源
└── ...

SKILL.md 至少包含 name 和 description 两个 metadata 字段，加上一段告诉 agent “这件事该怎么做” 的指令。除了 markdown 指令本身，skill 还可以打包：

  • 脚本（scripts/），让 agent 直接调用，而不是反复用 LLM 重新生成；
  • 参考资料（references/），按需读入；
  • 模板和静态资源（assets/），用于产出固定格式的内容。

它和 system prompt、CLAUDE.md、MCP 工具的差别在哪？一句话：skill 是"可发现、可按需展开、可附带可执行物的指令包"。它的目标不是把所有上下文塞进对话，而是把上下文做成可挂载的盘符。

渐进披露（progressive disclosure）#

skill 的关键机制是三段式加载：

  1. Discovery：启动时只把每个 skill 的 name 和 description 装进 context，让模型知道"我手边有哪些工具"。
  2. Activation：当任务匹配某个 skill 的描述时，agent 才把完整的 SKILL.md 内容读进来。
  3. Execution：根据指令执行，必要时再加载脚本或被引用的文件。

这意味着 skill 集合可以做得很大，而 context 占用却很小——只有真正被用到时才付代价。这套机制对长会话和多 skill 共存比较关键，否则一上来就把几十 KB 的 markdown 全塞给模型，在我看来也不太符合 agent 上下文治理的基本约束。

谁在用？#

agentskills.io 的 Client Showcase 已经列出不少兼容 client（至少在 2026-05-06 我写这篇时），覆盖编辑器、终端 agent、云端 agent 和框架/SDK 几类；完整名单我建议直接看原页面。

格式最初由 Anthropic 提出并开源，目前在 GitHub 上以社区标准的形式继续演进。也就是说，写一个 skill，至少在格式层面理论上可以跨这些工具复用——这也是它对比 system prompt、对比各家私有 plugin 接口时，一个很关键的吸引力。

实证拷问：SWE-Skills-Bench#

听起来很美，那到底好不好用？

按论文自己的说法，SWE-Skills-Bench 是第一个专门讨论 “agent skill 是否真的会给软件工程任务带来边际增益” 的需求驱动基准。研究者把 49 个公开 skill 投放到约 565 个真实 GitHub 仓库的任务实例上，做了带 / 不带 skill 的成对对比。

结果比流行叙事要克制得多：

  • 49 个 skill 里有 39 个没有观察到 pass rate 提升；
  • 平均增益只有 +1.2%；
  • 真正带来明显收益的只有 7 个，最高带来 30% 的提升；
  • 还有 3 个 skill 让结果反而退化，最高 -10%；
  • token 开销区间很宽，从"省 token"到"+451% token 但没有收益"都有。

论文给出的解释是，skill 的有效性高度依赖三件事：domain fit（skill 描述的领域是否真和任务对齐）、abstraction level（指令颗粒度是否匹配 agent 当前的瓶颈）、contextual compatibility（skill 假设的项目上下文是否和当前仓库一致，比如版本、目录结构、依赖）。

换言之，至少从这组实验看，skill 不是银弹，更像是"调好参数的局部最优"。把别人写的 skill 直接塞进自己仓库，常见结果未必是提升，也可能只是多花 token、多绕一圈，甚至偶尔反向。

没有 eval 的 skill，更像 Markdown + 一厢情愿#

这一节标题借自 Sogl 那篇 Skills Without Evals Are Just Markdown and Hope。他把上面那个结论往前再推了一步：skill 部署不带 eval，更接近于把"它有用"当成一个未经验证的假设上线。他指出 skill 至少有两种隐性的失败模式：

  1. 能跑，但毫无增益——skill 文件正常被加载、agent 也老老实实读了，但整段指令里有相当一部分内容对最终结果没贡献；
  2. 几乎不被触发——skill 明明在那里，但 description 没有覆盖真实的提问方式，导致对话场景下很难稳定激活。

第一种问题很隐蔽。Sogl 给自己的 @ngrx/signals skill 做基准时，pass rate 从 84% 拉到 100%，看起来很漂亮。但 A/B 拆分后他发现整整一节内容对增益的贡献是 0——把它删掉，效果一样。如果不做对照，这段"死说明书"就会带着延迟和 token 成本一直留在生产里。

第二种问题更结构化。Sogl 文中援引 Anthropic 对公开 document-creation skills 的 description 优化结果：6 个 skill 里有 5 个触发改善，但这也说明连官方样例都需要专门优化触发条件。另一边，Vercel 的一组 Next.js 16 agent evals 则显示，56% 的场景里即便挂着 skill 也没有实际被 invoke。Sogl 自己再做三轮 description 迭代，触发率依然没有超过基线——至少在这些材料里，description rewriting 并不是万能药。

成本也是实打实的：他给出的口径是每次 skill 调用平均增加约 14 秒和约 12,400 tokens，按当时的 API 价格大约 0.04 美元一次。一个不能稳定触发、又不能稳定带来增益的 skill，意味着团队可能只是在为"安心感"付费。

两类 skill，两种保质期#

这篇文章里我最愿意带回团队讨论的是这个分类：

  • Capability uplift skills：教模型一件它本来不稳定会做的事（比如解析某个冷门格式、调用某种非标 API）。这类 skill 的有效期，很多时候取决于"下一代模型把它内化掉"的速度。
  • Encoded preference skills：把团队/产品的写法、风格、流程沉淀为可执行规范（比如"我们的 commit message 模板"“我们的服务上线 checklist”）。只要团队的偏好还在，这类 skill 就一直有价值。

工程上的含义对我来说很直接：优先投资 encoded preference 类 skill。capability uplift 类 skill 往往从写完那一刻就开始倒计时，写得越精致，也越可能在下一轮模型升级后被"白送"掉。

怎么务实地用 skill#

把上面几份资料折叠到一起，我现在更像按一个小决策树来用 skill：这件事是不是需要按需加载、是不是需要附带脚本或模板、是不是跟当前仓库/团队偏好强相关。如果三个答案都偏否，我通常会优先考虑 AGENTS.md / CLAUDE.md / system prompt，而不是先造一个 skill。基于这个判断，我自己会遵守下面几条规则：

  1. 我自己尽量不直接用别人的 skill 仓库。SWE-Skills-Bench 的数据已经说明，公开 skill 在你的仓库里未必有增益，因为 domain / version / 上下文不一定对齐。它更适合作为参考实现，而不是开箱即用的生产资产。

  2. skill 之前先问"放进常驻上下文不行吗"。skill 的真正价值在于"按需加载"和"附带脚本"。如果你的指令几乎每个对话都需要、又不依赖额外可执行物，写到 AGENTS.md、CLAUDE.md 或 system prompt 往往更直接，也省掉一次触发与加载的不确定性。

  3. description 是 skill 里我最舍得花时间打磨的一行。在三段式加载里，模型起步时只能看到 name + description 来决定要不要激活。Vercel 的 56% 不触发率提醒我：写得不够具体、没有明确"何时使用"的 description，在长对话里很容易变成哑炮。

  4. 跑成对的 eval，别相信一两次手感。最低门槛是：写一组真实任务的小测试集，跑两遍——一遍挂 skill，一遍不挂。结合 Sogl 的做法，我会把最小检查面拆成四项：capability 提升、token 成本、description 触发率、pass rate 是否已经饱和。如果你不知道 skill 给你带来了什么，就还不该把它纳入工作流。

  5. 给 skill 定好类型：capability uplift 还是 encoded preference。前者我会默认它是"易腐品"，下一轮模型升级或客户端升级时就重测、必要时直接丢掉；后者才更像团队资产，适合写进 monorepo，跟 code review 一起演进。

  6. token 成本要进总账。当 skill 数量上 10、上 50 时，即便启用渐进披露，描述列表本身也会占走可观的 context；执行阶段一展开，像 Sogl 这个案例里，单次调用 +12k token 并不夸张。把 skill 当成一种有成本的能力借贷，而不是免费的工具栏。

小结#

至少到我写这篇时，Agent Skills 作为格式已经足够清晰：一个文件夹、一个 SKILL.md、三段式加载、一个跨工具开放标准。它确实在解决"agent 需要可移植、可发现、可携带脚本的能力包"这个工程问题。

但作为方法，它还在被实证反复拷问。SWE-Skills-Bench 告诉我们 skill 的命中率和增益都可能比直觉低很多；Sogl 那篇文章则提醒我，没 eval 的 skill 在生产里很容易退化成"看运气"。这些发现并不否定 skill 的价值，反而是在提醒我们：skill 不是配置，更像产品。 配置上线常常只看"文件存在"，但如果把 skill 当产品维护，就需要指标、A/B 和持续维护。

如果只能记住一句话，我希望是：Skill 真正的难点不在写出来，而在证明它真的在帮你。

参考#