Agent Skill 不是文档，它该进 CI

一份 SKILL.md 合并进主分支，故事才刚开始。

这是我看完 Google Agent Skills 团队那篇幕后文章后，脑子里最先冒出来的一句话。

他们的公开仓库 google/skills 已经有超过 1.5 万个 GitHub 星标。好家伙，很多开源项目走到这个量级，首页差不多可以开始写庆功稿了。Google 团队却在文章里花了大半篇幅讲另外几件事，目录规范、链接检查、提交时评测、每周全量重跑，还有坏了以后到底谁负责修。

图一，google/skills 星标增长曲线，源自 Google 团队公开文章

看着一点都不性感。

但我觉得，这才是 Agent Skill 从玩具变成工程资产的分水岭。

最近大家很爱聊 Skill。写一个文件，塞进几段指令，模型立刻像学会了新手艺。演示时确实很爽，十分钟就能从零跑起来。可只要把时间轴拉长三个月，你会碰到一串更难看的问题。

文档链接改版了，模型版本升级了，底层 API 换了参数，原来能工作的例子突然报错，某个贡献者留下了一句「优先使用最新接口」，然后再也没人知道「最新」到底是哪一天。

Skill 没有报错退出。它只是安静地开始教错东西。

这比普通代码坏掉更麻烦。代码坏了，测试通常会红。Skill 退化后，回答还会很流畅，命令还会很像那么回事，甚至评审者扫一眼也觉得挺合理。直到有人真把它贴进终端，收获一个 404、一组过期参数，或者一份看似完整却漏掉权限边界的方案。

所以我的判断很明确。

Agent Skill 不是文档，它该进 CI。

一个文件为什么会长成技术债

先别急着把 Skill 想得太神。

它通常就是一份给智能体看的操作说明，告诉模型什么时候触发、该读哪些资料、按什么步骤行动、哪些事情绝对不能做。Agent Skills 的开放规范与参考实现把它做成了一个很轻的目录约定，核心文件仍然是 SKILL.md，旁边可以放脚本、参考资料和静态资源。

轻量是它爆发的原因，也是它容易腐烂的原因。

普通代码至少有编译器、类型系统和测试框架盯着。Markdown 太自由了。名字拼错一个字符不会编译失败，链接失效不会让 Git 拒绝提交，步骤顺序写反了也不会自动亮红灯。模型还特别擅长把残缺说明补成一段自信的答案。

你想想看，一个 API 技能里若还写着两个月前的模型名，最危险的结果未必是调用失败。更可能是智能体悄悄改用一个相近接口，返回一份结构看着对、语义却已经偏掉的数据。

哦豁。

失败被包装成成功，这才是最贵的 bug。

Google 的处理方式很朴素。他们没有发明一套玄学 Prompt，而是把软件工程那套旧纪律搬了过来。每个技能要有标准目录，要有明确 owner，要带评测提示集和评分规则。内部版本里，SKILL.md、OWNERS 和 EVAL.yaml 都是必需品。

这个组合挺有意思。

SKILL.md 回答「它该怎么工作」，EVAL.yaml 回答「怎么证明它仍然工作」，OWNERS 回答「不工作时去找谁」。三个文件凑齐，Skill 才不再是一张没人认领的便利贴。

第一扇门不是评测，是让垃圾进不来

很多团队一听 Skill 质量，就想马上上大模型评审，让另一个模型给这份指令打分。

先等等。

能用确定性规则抓住的问题，别急着花 token。

Google 的提交检查会验证 frontmatter、行数、目录布局和命名约定，还会逐条检查 URL。他们甚至专门推荐了 lychee 这类链接检查器。原因很现实，Skill 经常承担「给旧模型补新知识」的工作，链接就是证据入口。一条 404 不只是阅读体验差，它会切断智能体回到一手资料核验的路。

这块很像写编译器。先做词法和语法检查，再谈程序语义。目录不对、元数据缺失、引用文件不存在、URL 已死，这些都是机器百分百能判断的硬错误。让 LLM 来审，反而更慢、更贵，还可能心软放过。

公开仓库可以直接用 skills-ref 的校验器接进 GitHub Actions。最小流程并不复杂。

name: Validate Skills

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install skills-ref
      - run: |
          for skill_dir in skills/*/; do
            agentskills validate "$skill_dir"
          done

这段配置不聪明，甚至有点无聊。棒棒的，质量基础设施就该无聊。它的价值是把最低标准从「评审者记得检查」变成「机器不通过就别合并」。

如果是自己的内部技能库，还可以再补几项确定性检查。比如 frontmatter 里的触发描述是否为空，正文引用的相对文件是否存在，脚本有没有可执行权限，示例命令是否包含已废弃参数，禁止动作有没有真的写进规则区。

这些检查一旦固定下来，维护者就不必在每个 PR 里重新扮演人肉 linter。省下来的注意力，留给真正需要判断的地方。

真正的评测要同时问两个问题

结构合法，只能证明 Skill 长得像 Skill。

它有没有用，还得跑。

Google 会在技能提交时比较智能体「带 Skill」和「不带 Skill」的表现，主要看两条轴，准确性和效率。准确性包括回答质量与任务完成率，效率则看 token 消耗和完成时间。他们还会在不同 Agent 框架上重复运行，让结果别太依赖某一套脚手架。

这里有个很容易被忽略的坑。

一份 Skill 完全可能让准确率上涨，同时把上下文撑爆。原本模型用 3000 token 就能完成的任务，加了厚厚一叠参考资料后要吃掉 18000 token，还多走了五次工具调用。结果是对了，延迟和成本也一起上天。

反过来也有。你把指令压得极短，模型确实跑快了，却开始漏边界条件。看着 token 曲线很漂亮，线上返工的人已经在骂街。

只测答没答对不够，只测省没省钱也不够。Google 用一个 2×2 矩阵看技能是否同时带来准确性和效率提升，这个思路很值得抄。

图二，评测同时观察任务完成质量、token 与耗时，而不是只看单一分数

最实用的做法，是给每个 Skill 留一小组能长期复跑的代表任务。别贪多，先覆盖三类就行，主路径、容易误触发的近邻任务、最可能翻车的边界条件。每个任务都写清可观察的预期，调用了哪个工具，参数是否包含某字段，输出是否引用官方来源，有没有触碰禁止动作。

注意，预期结果不要只写「答案高质量」。这种 rubric 看着正确，实际上没法稳定验收。要写成能查的证据。

假设有一个云资源清理 Skill，评测不该只看解释是否专业，还要确认它先列出目标资源、做只读检查、等待明确授权，并且没有直接执行删除。一个 API 迁移 Skill，则要检查它是否用了当前 SDK、是否移除了废弃字段、示例代码能不能通过最小测试。

这才叫验收。

每周重跑，比合并那天的高分更重要

提交时全绿，为什么还要每周跑？

因为 Skill 的依赖不全在仓库里。

模型会更新，系统提示会更新，Agent 框架会更新，远程工具会更新，官方文档也会改。你的 Skill 一行没动，运行环境已经换了一圈。传统代码把这类问题叫依赖漂移，Agent 世界里还多了一层模型行为漂移。

同一份指令在旧模型上需要把步骤写得很细，新模型可能嫌啰嗦，反复读取相同资料。原来能稳定选中的工具，框架升级后也许因为描述相似开始误路由。更离谱的是，答案表面仍然没毛病，只有 token、延迟和失败重试次数在一点点变坏。

所以 Google 不只在提交时评测，还会每周对整个技能库跑定时质量检查。

我自己的感受是，这个动作比「我们有一套 Skill 模板」重要得多。模板解决出生证明，周期评测才管健康体检。没有后者，技能库越大，沉默退化越多，到头来谁也不敢升级模型，因为没人知道会炸掉哪一排任务。

当然，全量重跑会花钱。可以按风险分层。涉及写操作、账号权限和外部消息的 Skill 高频跑，纯格式化和只读查询低频跑。最近改过的、依赖刚升级的、历史上容易回归的先跑。稳定区只保留一组烟雾测试，夜间或周末再补完整矩阵。

怎么说呢，这跟普通 CI 没啥神秘差别。快测试守门，慢测试巡检，高风险路径多给一点预算。

厉害的地方不在概念，而在他们真把它做成了日常制度。

远程 MCP 不是潮流装饰，它在处理知识保鲜

Google 在文章里还给出一条架构偏好，尽可能引用远程 MCP 工具，只有必要时才退回 CLI 或直接 API 调用。

MCP，也就是 Model Context Protocol，可以理解成智能体调用外部工具的一套通用接口。远程 MCP 服务把工具描述、认证和权限治理放在服务端，Skill 更像一张路线图，告诉智能体什么时候去用哪个能力。

这条选择背后，其实还是维护成本。

如果把大量 API 细节、字段说明和账户权限规则全部复制进 SKILL.md，你得到的是一份今天很完整、下个月很可疑的快照。远程工具把变化留在服务端，Skill 只保留决策逻辑和安全边界，文档漂移的表面积会小很多。

但别把 MCP 当免死金牌。工具 schema 也会变，鉴权也会失效，服务也会超时。Skill 仍然要写清失败方式、重试边界和降级路径，评测里也要验证工具不可用时它会不会胡编一个结果。

不是哥们，连不上就说连不上。别让模型靠气势把接口补出来。

公开仓库干净，靠的是导出而不是克制

Google 的另一处做法也很工程化。他们先在内部构建和评测，发布时用自动规则导出公开版本，剥离 OWNERS、内部评测套件、测试 mock 和私有数据。

这比要求每位贡献者「提交前记得删干净」可靠多了。

内部 Skill 经常会碰到账号别名、测试数据、私有端点和组织流程。手工复制很容易漏，公开仓库又不能为了保密把所有评测证据一并扔掉。把公开导出当成构建产物，既能保留内部完整工程链，也能让外部用户拿到干净目录。

图三，Google 团队公开的 Skill 维护与发布链路

这套思路和发布软件包很像。源码仓库不是最终制品，构建流程决定哪些文件进入发行包。Skill 既然被当成产品，就该有自己的发布管线。

Google 还用 Agent Development Kit 做作者辅助工具，让多智能体循环帮助起草 Skill、编写评测和自我批评。这个部分有点子牛逼，但顺序不能反。AI 可以帮你写测试，不能替你定义责任。责任仍然要落到 owner 身上，API 变了有人修，质量下降有人接告警。

真想把 Skill 管起来，可以从一条小流水线开始

看到这里，先别急着搭一个内部平台。

给 Skill 加工程纪律，不需要一上来复制 Google 的规模。一个仓库、一份目录规范、一条 GitHub Actions、每个 Skill 三到五个代表任务，已经能挡住大部分低级退化。

然后给每份 Skill 写上 owner。不是作者昵称，而是现在仍然对它负责的人或团队。再设一个每周定时任务，记录成功率、平均 token、耗时和工具失败次数。模型或框架升级前后，把同一组任务跑两遍，差异超过阈值就先别全量切。

等这些基础数据真的跑起来，再决定要不要做复杂平台。否则大概率会先造出一个漂亮仪表盘，里面展示一堆没有稳定样本支撑的分数。

我一直觉得，Agent 工程最容易被演示骗到。一次成功看起来像能力，重复一百次仍然稳定，才接近产品。

Google 那个 1.5 万星仓库最值得拿走的，也不是某一份现成 Skill。是他们承认了一件不太浪漫的事，指令会过期，模型会漂移，链接会死亡，贡献者会离开。

没有哪份 Markdown 能永远正确。

所以要检查它，评测它，定期重跑它，还要在它坏掉时找到负责的人。

写完不是交付。

持续能用，才是。