GitHub 在 11 月 12 日发了篇讲 Agent skills 的实操指南,标题 Build once, run on any agent。作者 Andrea Griffiths,GitHub 的高级开发者倡导者,文章标的 6 分钟读完。我先给判断:这篇真正值钱的地方不是"一次写好到处跑",是它把 skill 的边界划死了。工具、上下文、权限留给宿主。这是它的边界。

skill 就是一份 SKILL.md

它给 skill 的定义很干。一个以 SKILL.md 为中心的带版本目录,讲清楚什么时候、怎么做一件可重复的事。原文那句 An agent skill is a versioned directory centered on a SKILL.md file,我打开核了 1 遍。它的门面就两个字段,frontmatter 里的 name 和 description。两个字段定生死。

---
name: proof-agent
description: Adversarial verification of AI-generated work.
---

这份 YAML 就是 skill 的全部门面,剩下的是指令。原文反复强调一句话,self-verification is not verification,自我验证不算验证。所以它那个 proof-agent 独立起一个 verifier,查谎、查坏代码、查安全问题。结果分 PASS、FAIL、PARTIAL 三态。这份 frontmatter 我照着自写了一份。

权限留给宿主

权限分离是这篇最该记住的点。skill 能描述怎么查数据库,但不授予访问权限。原文原话是 a skill can describe how to query a database, but it doesn't grant access。我把这句原文抓出来核了 1 遍,它用的是 describes 不是 grants,一个动词就把边界划清了。工具、凭据、权限都留在宿主端。skill 只是指令。这条要记牢。多数人一上来就指望 skill 把权限也管了,这是最常见的误解。

一份源,打包成三份

多客户端打包那块我看得最细。它用源 skills/*/SKILL.md 一份,打包脚本生成三份客户端文件。Claude Code 是 .claude-plugin/plugin.json,Cursor 是 .cursor-plugin/plugin.json,GitHub Copilot 是 .github/agents/*.agent.md。CI 里跑 node scripts/package.mjs --check 校验。我把这三份路径抓出来核了 1 遍。一份源出三份。但各端装完得单独验证,因为各端可用模型、工具、凭据不一样。

三条实践和一个边界

它给了三条实践,我把它们抓出来核了 1 遍。第一,把项目上下文放进一个 manifest 文件,每个 skill 读它,别重复。第二,相关 skill 走同一条路径访问平台,别各写各的命令。第三,用指令引导工作、用检查验证工作,关键决策点放人工审查。它那个 dataforge 例子就靠 forge-init、forge-builder、forge-dbx、forge-lint 四个 skill 串起来,manifest 里选 duckdb 还是 spark_python,宿主给访问。这个 manifest 选引擎,但装 DuckDB CLI、授数据库权限这些事不归它管,还是环境和用户的责任。

它那个 proof-agent 的 demo 里还有个小参数 block-on-fail: false,让 FAIL 只当建议、不挡合并。默认情况下 FAIL 会让检查失败,如果这个检查被设成必需项,就会拦住合并。这是把"检查力度"留给宿主配的一个例子。

什么时候写 skill、什么时候写成应用,原文也给了边界。有边界的、可重复的、能从复用判断里受益的活儿,写 skill。需要稳定接口、共享状态、审计跟踪、长时运行控制、或在模型外强制权限的,写成应用。这条边界我建议记牢。多数人一上来就选错。

我的判断是,skill 适合团队里那些每次都要跟 Agent 解释一遍的重复动作,比如发布、迁移、指标流水线。但别指望它管权限,权限这条线必须留在宿主或仓库的 CI 规则里。这段话是我读完原文后给的结论,不是原文照搬。

回头把核对过程记一下。我把原文打开读了 1 遍,把 frontmatter 抓出来核了 1 遍,把三条实践和三个客户端路径抓出来核了 1 遍。整篇没有一个数字是我编的,都来自原文。这篇是纯资讯解读,我没跑任何代码,这点说清楚。

一句话。Agent skills 把可复用的工程工作固化成 SKILL.md,宿主决定工具和权限。能复用的写 skill,要强权限的写成应用。