SKILL.md + 脚本 + 参考文档:Agent Skills 结构解剖,凭什么跨 Cursor/Claude 通用

原创2026-10-14 12:52:351,426 阅读
文章标签:CLI开发工具AI 技能插件系统包管理器

SKILL.md + 脚本 + 参考文档:Agent Skills 结构解剖,凭什么跨 Cursor/Claude 通用

在 AI 编程助手从"聊天机器人"向"虚拟工程师"演进的节点上,Agent Skills 是今年最像"基础设施"的一件事:Vercel 的 skills CLI 仓库横扫数十万星标,skills.sh 上沉淀了数十万个社区技能包,Cursor、Claude Code、Codex、Trae、Copilot 甚至 Gemini CLI 都在同一时间向一套结构靠拢。社区里最常被引用的结论是"技能包 = SKILL.md + 脚本 + 参考文档"——但这句话只说对了一半。真正值得拆解的问题是:这套三层结构为什么能被不同厂商同时接受?触发一个技能靠的是自动还是显式?"跨平台通用"的承诺究竟来自哪一层?

本文以 skills 仓库源码为解剖对象,从文件契约、发现机制、安装链路到兼容性表格,逐层还原 Agent Skills 的工程真相。

三层结构各自的职责边界

先看一个真实技能长什么样。find-skills 是官方自带技能,它只有两个文件:SKILL.md 与配套的 scripts/ 目录——这个仓库里 scripts/ 是 CLI 的构建脚本,技能本身的"脚本"则是通过调用 npx skills find/add/update 完成的。这恰好点破了三层结构的本质:

SKILL.md 是契约与说明书,不是代码。 它的头部是一段 YAML frontmatter,只有两个必填字段:name 和 description。src/skills.ts 的 parseSkillMd 会严格校验这两项,缺一即跳过,且要求两者必须是字符串——YAML 解析出的数字、布尔值会被直接拒绝。其余字段全部可选,例如 metadata.internal: true 可以把技能从正常发现中隐藏,只有设置 INSTALL_INTERNAL_SKILLS=1 时才可见。frontmatter 之下才是正文:When to Use、Steps、分类表,这些是写给模型看的自然语言指令。

脚本是"手脚",负责把指令变成可执行的动作。 技能目录里的脚本(scripts/、hooks/ 等)是被 SKILL.md 正文引用、由 Agent 调用执行的程序;而 scripts/sync-agents.ts、scripts/execute-tests.ts 这类仓库级脚本则负责维护 CLI 自身——比如自动把 75+ Agent 的路径表生成回 README.md。两层脚本的共通点是:它们只做 Agent 做不了或做不好的事(文件系统操作、外部 API、批量生成),判断逻辑与操作规范永远留在 Markdown 里。

参考文档是"弹药库",负责压缩上下文成本。 官方对技能目录的建议结构中,references/、examples/、templates/ 都是可选资源,find-skills 的正文就直接引用了 skills.sh 排行榜与安装量作为检索依据。这层设计的精妙之处在于:Agent 不需要把所有规范塞进上下文,只需按需读取 references/ 里的文件,SKILL.md 保持轻量。三层结构因此形成一条清晰的分工线——契约管"是什么",正文管"怎么做",脚本管"做出来",文档管"做得好"。

触发机制:自动识别 vs 显式调用

技能包装进 ~/.claude/skills/ 或 .agents/skills/ 之后,何时被激活?源码给出了两条截然不同的路径。

自动识别依赖 description 驱动的语义路由。 Agent 启动时会扫描技能目录(src/skills.ts 的 discoverSkills 遍历 skills/、.agents/skills/ 等标准容器,默认深入 3 层,浅层 SKILL.md 会遮蔽嵌套的同名技能),把每个技能的 name 和 description 纳入自己的工具清单;当用户需求与 description 描述的触发场景匹配时,技能被加载。所以 find-skills 的 description 里写满了触发句式:"how do I do X"、"find a skill for X"、"is there a skill that can..."——这些不是废话,而是路由索引。配套的 src/detect-agent.ts 甚至能从环境变量判断 CLI 是否运行在某 Agent 内部(例如对 Cursor 要求 CURSOR_AGENT 或 CURSOR_EXTENSION_HOST_ROLE=agent-exec 强信号,避免误判),从而跳过交互直接执行。

显式调用则绕开模型路由,把技能变成"管道"。 src/use.ts 的 buildUsePrompt 给出了答案——它把选中的 SKILL.md 原文整体包进 <SKILL.md>...</SKILL.md> 标签,附上一句"把这些指令作为你的执行规范",再把技能目录里的支持文件下载路径告知 Agent:

npx skills use vercel-labs/agent-skills@web-design-guidelines | claude
npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code

skills use 不需要安装,解析、下载、物化到临时目录、拼 prompt 一条龙,最后要么把 prompt 打印到 stdout 由你管道给任意 Agent,要么用 --agent 直接拉起 claude-code / codex / sarvam-code 的交互会话。第三条路径是 src/find.ts 的 fzf 风格交互搜索:输入关键词,对 skills.sh 的 /api/search 做防抖查询,回车即内部调用 runAdd 完成安装。自动触发靠"模型的语义判断",显式调用靠"shell 的确定性",两者互为兜底——这正是技能包敢跨 Agent 分发的底气。

对照谷歌 5 种设计模式的异同

谷歌官方曾以"5 种 Agent Skill 设计模式"总结这一领域的形态差异,社区多篇文章将其视为开发者指南。对照 skills 的实现,能清晰看到这套生态在哪些维度上选择了特定模式、又在哪里故意留白:

  • 单一职责 vs 大而全:设计模式强调一个技能只解决一个问题。find-skills 的正文刻意收敛为"理解需求 → 查排行榜 → 搜索 → 校验质量 → 推荐 → 安装"六步,不掺杂其他能力;Vercel 的 agent-skills 按 react-best-practices、web-design-guidelines、vercel-deploy-claimable 拆成独立技能包,与"单一技能单目录"的容器约定完全同构。
  • 描述路由 vs 显式路由:设计模式把"何时触发"视为技能设计的第一决策点。自动识别模式依赖 description 质量——parseSkillMd 强制 description 非空正是为了保住这个路由的索引完整性;而 skills use 提供的显式路由则对应"用户明确指定技能"的模式,二者在 src/use.ts 中由 resolveSelector 统一仲裁冲突。
  • 文档优先 vs 代码优先:与把逻辑写进脚本的模式相反,skills 生态的规范文件默认只保证 frontmatter 的 name/description 两个字段,正文结构(When to Use、Steps)只是建议而非强制——README.md 的"Creating Skills"一节给出了模板但从不校验。这意味着生态里同时存在"纯提示词技能"和"脚本密集型技能"两种风格,各自对应不同的设计模式取向。
  • 元数据约束 vs 无约束:metadata.internal、INSTALL_INTERNAL_SKILLS 是少数被规范化的元数据控制点,对应模式中"技能可见性治理"的诉求;除此之外不加更多 schema,把扩展空间留给各家 Agent 自行实现(如 Claude Code 的 context: fork、hooks)。
  • 可移植性优先 vs 平台绑定:这是本仓库最自觉的模式选择——兼容性表格(见下节)明确标注哪些高级特性是 Agent 专属,宁可牺牲高级功能也要保住"基础技能全兼容"的下限。

可移植性的真正来源:标准还是生态

这是整篇文章最容易被误解的问题。答案是:标准给出下限,生态决定上限。

标准层:所有 Agent 都承认一份共享的 Agent Skills 规范——目录里放 SKILL.md、frontmatter 有 name 和 description。这份契约极薄,薄到任何工具实现起来成本都极低,这正是它能被 Cursor、Claude Code、Codex、Trae、Windsurf、Gemini CLI 同时接受的根本原因。README.md 的兼容性表格给出了残酷的细节:基础技能 18 家 Agent 全支持,但 allowed-tools 有 2 家不支持,context: fork 只有 Claude Code 支持,Hooks 只有 4 家支持。可移植性在标准层是"有条件的真"——跨平台通用的是薄契约,不是全部特性。

生态层:真正的通用性来自中立包管理器把碎片目录抹平。skills CLI 维护着一张 75+ Agent 的路径映射表(src/agents.ts),Cursor 读 .agents/skills/ 与 ~/.cursor/skills/,Claude Code 读 .claude/skills/ 与 ~/.claude/skills/,Trae 读 .trae/skills/——安装时 CLI 自动探测本机已装的 Agent(detectInstalledAgents),只向存在的目录写入。写入方式有两种:默认把技能放进统一的 canonical 目录 .agents/skills/,再给各 Agent 目录建符号链接("单份源码、多端同步",见 src/installer.ts);不支持软链接的环境退化为 --copy。项目级(随 git 提交、团队共享)与全局级(-g,本机所有项目可用)双作用域进一步把"共享"做进了工作流。

支撑这层"抹平"的工程细节在源码里俯拾皆是:项目根生成 skills-lock.json 记录每个技能的来源、路径与内容哈希(src/local-lock.ts),全局另有 .skill-lock.json(src/skill-lock.ts),skills update 借此实现类似 npm update 的增量升级;src/source-parser.ts 统一解析 GitHub 简写、GitLab、Azure Repos、本地路径、well-known 端点六类来源;src/providers/wellknown.ts 让任何网站挂一个 .well-known/agent-skills/index.json 就能发布技能,企业内网可用一个代理层把 Git 仓库转成静态索引,把"仓库访问控制"改造成"Web API 访问控制"。

生态层的信任成本同样真实。 社区审计曾指出超过三成技能包存在恶意脚本与权限滥用风险,skills 的回应是工程化的:frontmatter 解析器明确不做 JS 引擎以规避 eval 型 RCE(src/frontmatter.ts);所有来自 SKILL.md 或远程 API 的字符串先过 src/sanitize.ts 的终端转义清洗,防御 CWE-150 注入;zip/tar 解包有字节与文件数上限、拒绝软硬链接与路径穿越(src/archive.ts);well-known 索引强制 sha256 digest 校验;安装时还会向审计 API 拉取风险评分展示给用户。这些措施共同回答了一个问题:"类 npm 化"要成立,必须先解决 npm 时代踩过的坑。

结论

拆开 skills 仓库,跨平台通用性的答案不是某个魔法协议,而是一组精心配比的设计:极薄的 frontmatter 契约保证所有 Agent 都读得懂;description 驱动的自动路由与 skills use 的显式管道覆盖两种触发场景;统一的 canonical 目录 + 符号链接 + 双锁文件把安装、同步、升级变成纯工程问题;安全防线则确保这套分发网络不至于成为供应链攻击的新入口。 标准负责让各家"愿意兼容",生态负责让用户"无需关心差异"——前者是底线,后者才是 Agent Skills 真正值钱的资产。当技能包像 npm 包一样可搜索、可安装、可更新、可审计时,"把 Vercel 十年的 React 经验装进任意 Agent"就不再是营销话术,而是目录树里看得见的现实。

登录后查看全文
skills