AI 世界是一片蛮荒西部,AI 编码智能体则是新来的牛仔。这让事情既刺激又混乱。在这篇文章中,我尝试解释 AI Agent Skills 的现状,因为我自己之前也不了解,不得不费一番功夫才弄明白。
TL;DR:AI Skills 是可复用的软件包。它们就像是 React 网站的 NPM 包、笔记本电脑的即插即用设备、Skyrim 游戏的 mod。
那么,就让我们在这片混乱中坐下来,看看能学到什么。

什么是 Agent Skill?
Agent Skills 规范定义了一种以 SKILL.md 文件为核心的可移植格式。
一个 skill 通常长这样:
my-skill/
├── SKILL.md
├── scripts/
│ └── validate.sh
├── references/
│ └── guidelines.md
└── assets/
只有 SKILL.md 是必需的。其他目录都是可选的。
文件以 YAML frontmatter 开头:
---
name: my-skill
description: Validate a project against
security best practices.
---
# Security Validation
1. Inspect the project.
2. Identify security issues.
3. Recommend improvements.
4. Generate a report.
frontmatter 指的是两条 --- 之间的部分。它包含 skill 的名称、描述和其他元数据,采用键值对格式。之所以叫 frontmatter,是因为它不是文件的主要内容,类似于书籍的前置部分,包含扉页、版权页和目录。
智能体通过名称和描述发现 skill,然后在需要时加载详细说明。这种机制称为渐进式披露。它意味着智能体在被调用之前不需要加载整个 skill,从而节省内存并提升性能。
该规范定义了 skill 的结构,但没有定义通用的分发机制。
而有趣的地方就在这里。
不同的 AI Agent 客户端
支持 Agent Skills 格式的客户端越来越多:
- OpenAI Codex — 支持 skills、捆绑脚本、references 以及客户端特定的元数据。
- GitHub Copilot — 在编码智能体、代码审查和兼容的 IDE 工作流中支持 skills。
- Cursor — 发现本地 skills,并支持基于插件的分发。
- Gemini CLI — Google 的终端智能体,支持 skills。
- Google Antigravity — 支持用于智能体工作流的可复用 skills。
- OpenCode — 通过项目级和用户级目录支持 skills。
- OpenClaw — 支持通过 ClawHub 分发的 skills。
这些客户端大多支持相同的核心 SKILL.md 格式,但安装位置、调用行为、支持的元数据和安全控制可能有所不同。
例如,一个客户端可能从 .agents/skills/ 发现 skill,而另一个客户端期望的是 .claude/skills/ 或 .github/skills/。
可移植的格式不一定意味着可移植的行为。
Skill 作者应在其目标客户端上测试同一工作流,而不是假设格式兼容就能保证执行结果一致。
在哪里可以发布 Skills?
与传统软件包不同,AI Agent Skills 没有像 npm 或 PyPI 那样单一的主导注册表。
取而代之的是多个市场、目录和分发机制。
Skill 市场和目录
- skills.sh — 一个流行的目录和安装生态系统。Skills 通过 skills CLI 从 GitHub 仓库分发。
- SkillsMP — 一个索引包含 Agent Skills 的公共 GitHub 仓库的市场。
- ClawHub — OpenClaw 的 skill 注册表,支持直接发布、版本管理,并可通过其 CLI 安装。
- GitHub — 可移植 skills 的天然分发地点。GitHub CLI 还提供 gh skill 命令用于发现、安装和发布。
- LobeHub Skills — 一个支持 GitHub 托管技能的社区市场。
插件市场
有些平台把技能作为更大插件的一部分来分发:
- Claude Plugin Directory — 技能可以打包为 Claude 插件并提交审核。
- Cursor Marketplace — 支持包含技能、MCP 服务器、规则及其他组件的插件。
- OpenAI Plugins Directory — 支持包含技能、MCP 集成或两者的软件包。
发布流程差异很大。
有些目录会自动发现 GitHub 仓库。另一些则要求 CLI 认证、打包、手动提交或审批。
这给技能作者带来了维护问题:把一个技能发布到多个市场,可能需要多份 manifest、不同的打包格式,以及独立的版本跟踪。
发布、索引与审批是不同的步骤
把一个软件包放进注册表、让它出现在搜索目录中、以及被一个精选市场接纳,是三种不同的结果。上传成功只能证明第一点。
例如,skills.sh 使用安装遥测数据来生成其排行榜。SkillsMP 索引公开的 GitHub 内容,其开发者 API 提供发现与搜索能力。这两者都不能成为在发布流程中添加人为安装量的理由,也不能假定一个新 tag 就保证能获得收录。
对于 SIP,我把自动化的软件包发布与目录提交分开处理。下面的发布结果显示哪些部分真正生效了。
Skill vs. Kit vs. MCP Server
这些概念彼此相关,但它们解决的是不同的问题。
| 概念 | 用途 | 示例 |
|---|---|---|
| Agent Skill | 教会 agent 如何执行某项任务 | 审计 Dockerfile 并生成 SBOM |
| Docker Sandbox Kit | 定义 agent 的执行环境、工具、指令与能力 | 一个带有 Codex、Trivy 和受限网络访问的沙箱 |
| MCP Server | 通过标准化协议暴露工具、资源和提示词 | 一个从安全服务检索漏洞信息的工具 |
| Plugin | 为在特定生态中安装而打包的能力 | 一个包含技能和 MCP 服务器的插件 |
Skill 回答的是如何做某件事。
MCP 服务器暴露的是 agent 可以与什么交互。
Docker Sandbox Kit 定义的是 agent 可用的环境与能力。
例如,考虑一个实现容器安全工作流的 agent:
- Skill 指示 agent 检查依赖、构建 SBOM 并扫描漏洞。
- Docker Sandbox Kit 提供执行这些操作所需的工具、配置、凭据和网络限制。
- MCP 服务器可以暴露额外能力,例如查询漏洞数据库。
这些机制相互补充。
Docker Sandbox Kit 尤其值得关注,因为其 v3 格式使用普通的 OCI 镜像。Kit 可以使用现有的容器工具进行构建、分发、版本管理和签名。
此外还有一个新兴的 MCP Skills 扩展,允许 MCP 服务器在提供其他能力的同时暴露 Agent Skills。这进一步缩小了可复用指令与远程提供的工具之间的隔阂。
打包技能:为什么不用 OCI Artifacts?
我们已经知道如何可靠地分发软件。
容器镜像、Helm chart、SBOM 和签名都可以通过兼容 OCI 的注册表和工具链来管理。
为什么 Agent Skills 不能以同样的方式工作?
目前,一个典型的技能存放在 GitHub 仓库中。安装可能涉及克隆该仓库、把文件复制到特定目录,或使用某个市场专用的 CLI。
这行得通,但带来了若干挑战:
- 我们如何识别一个技能的不可变版本?
- 我们如何验证它的完整性和发布者?
- 我们如何分发企业私有技能?
- 我们如何跨多个平台同步发布?
- 我们如何附加来源信息、签名和安全报告?
- 我们能否为一个技能及其依赖创建 SBOM?又或者创建 SkBOM(Skill Bill of Materials,技能物料清单)?
OCI 制品或许能提供一种答案。
现有提案
目前有两个值得关注的规范正在制定中:
- Agent Skills OCI Artifacts Specification
Thomas Vitale 的提案定义了一种用于单个技能和技能集合的 OCI 制品格式。
它引入了一种专用的制品类型:
application/vnd.agentskills.skill.v1
该规范涵盖清单(manifest)、配置、打包、版本管理以及基于摘要(digest)的安装。Arconia 等实现展示了如何将技能发布到 OCI 注册表。
- NVIDIA Agent Package Specification
NVIDIA 提出了一个更宽泛的格式,同时支持技能和插件。
其技能制品类型为:
application/vnd.agentpackage.skill.v1
该提案保留原生技能文件,同时提供 OCI 元数据、文件清单和完整性校验。
这些方案都建立在 OCI 约定之上,但使用不同的制品类型和元数据 schema。其中任何一个都不应被视为 Agent Skills 已被普遍采用的打包标准。
OCI 分发会是什么样子?
设想你以如下注册表引用的形式发布一个技能:
ghcr.io/containersecurity-dev/sip:1.0.0
一条发布流水线可以:
- 校验 SKILL.md 规范。
- 打包技能及其配套资源。
- 发布带版本的 OCI 制品。
- 使用 Cosign 对制品签名。
- 附加来源证明和安全证明。
- 将其分发到兼容的客户端或市场适配器。
使用方可以通过不可变的摘要来固定该制品:
ghcr.io/containersecurity-dev/sip@sha256:...
现有的 OCI 基础设施可以提供存储、身份认证、访问控制、完整性校验和制品发现。
然而,OCI 打包并不会自动让技能可以被每一个 AI 客户端安装。兼容的安装器仍然必须解包制品、校验其内容,并把技能放到客户端期望的位置。
OCI 解决了分发问题中的很大一部分。它并不能消除平台兼容性要求。
技能所有者的检查清单
在发布你的技能之前,请考虑以下事项。
规范与兼容性
- 该技能是否符合 Agent Skills 规范?
- SKILL.md 是否包含有效的 name 和 description 字段?
- 技能的目录名是否与它声明的名称一致?
- 你是否已在你声称支持的客户端上测试过该技能?
- 平台相关的依赖和限制是否有文档说明?
安全
- 你是否审查了所有脚本和打包进来的资源?
- 你是否检查了内嵌的凭据、令牌和敏感数据?
- 该技能是否说明了它需要的工具、网络访问和权限?
- 在执行破坏性或安全敏感的变更之前,它是否需要显式授权?
- 你是否检查了指令中的提示注入和依赖风险?
- 可执行组件是否经过测试,最好是在隔离环境中测试?
打包与发布
- 仓库是否包含 README 和明确的许可证?
- 你是否分配了版本号并编写了发布说明?
- 使用方能否安装一个不可变、经过审查的发布版本?
- 你是否考虑过对发布版本签名并生成来源信息?
- 你是否检查了各个市场的许可和提交要求?
- 你能否从同一源修订版本重现发布包?
- 你是否确认了已发布的市场条目引用的是预期的发布版本?
维护
- 当依赖或客户端 API 变化时,是否有更新技能的流程?
- 用户能否报告缺陷和安全漏洞?
- 你能否撤销、弃用或替换一个已失陷的发布版本?
- 旧版本和兼容性变更是否有文档记录?
AI 技能及其分发方式
一项技能并不一定因为它主要由 Markdown 构成就无害。它的指令可能促使智能体执行脚本、安装依赖项、访问凭据或修改基础设施。
应把第三方技能视为软件供应链依赖项,而不仅仅是文档。
勾选这些检查项实际涉及什么?
可复现打包:从一份明确的待发布文件清单开始。排除 .git、凭据、缓存和构建输出。规范化归档顺序、时间戳、所有权、权限和 gzip 元数据,然后构建两次并比较字节。SIP 的打包脚本还会拒绝符号链接,并写入 SHA-256 清单。生成的目录是 sip/,与 name: sip 匹配,尽管仓库名为 sip-skill。
完整性与来源:校验和告诉你字节是否与预期值匹配。如果攻击者能同时替换下载内容和其校验和,仅凭这一点并不能确定它由谁生成。构建来源添加了关于生成工作流和源代码的可验证声明。SIP 的分发任务会在发布下载的资产之前验证仓库、发布工作流和源标签。这仍然不能证明这些指令是安全的,也不能证明每个客户端都会正确执行它们。
安全测试:测试可能绕过某项控制的失败情况。在这项工作中,我发现 SIP 的 npm 验证器可能跳过没有版本号的格式错误的依赖项条目。现在它会拒绝该条目。测试还覆盖注册表故障、冷却边界和完整性不匹配。验证器将 lockfile 值与注册表元数据进行比较;它不会独立下载每个依赖项的 tarball 并计算哈希。这一区别应写入文档。
安全重试:多个注册表无法原子更新。一个可能成功,而另一个失败。SIP 独立运行每个发布任务,并且仅当现有版本与预期文件或包完整性匹配时才允许重试。不同的字节会导致失败,而不是覆盖。身份验证失败也会停止任务。特定版本的注册表标签可避免在重试较旧版本时将 latest 指针向后移动。
付诸实践:SIP
我最近创建了 SIP——Security Immediate Plan,这是一个用于实施五项供应链安全控制的智能体技能:
- 使用 Docker Sandboxes 隔离 AI 智能体。
- 强制执行依赖发布冷却。
- 使用 Docker Hardened Images。
- 生成 SBOM 和来源证明。
- 检测到可修复的严重漏洞时阻止晋级。
SIP 使用规范的 SKILL.md、额外的技术参考资料,以及带有回归测试的可执行 npm lockfile 验证器。
核心指令保留在一个地方。注册表包和客户端特定的插件清单围绕该规范技能生成。格式兼容性与每个客户端中经过测试的行为保持分离。
SIP v1.
| 渠道 | 发布如何运作 | SIP v1.0.0 状态 |
|---|---|---|
| GitHub Releases | 构建归档文件,附加溯源信息,创建草稿,然后发布 | 已发布,包含三个包和校验和 |
| GHCR | 使用 ORAS 将已验证的文件作为带版本的 OCI 包推送 | 已成功发布 |
| GitHub Packages | 使用工作流的 GitHub token 发布生成的 npm tarball | 已发布;重试时验证了匹配的包 |
| npmjs.org | 使用 npm 凭据和命名空间访问权限发布同一个 npm tarball | 已实现但已禁用;实际发布未测试 |
| Docker Hub | 使用注册表凭据推送 OCI 包 | 已实现但已禁用;实际发布未测试 |
| skills.sh / SkillsMP | 使 GitHub 源可被发现;目录索引是单独的 | 未声称有已验证的上架条目 |
| Claude / Cursor 目录 | 生成插件清单并通过商店的审核流程提交 | 已生成插件 ZIP;客户端测试和提交尚未完成 |
| LobeHub | 声明所有权并通过其经过身份验证的用户工具发布 | 未由 SIP 自动化或发布 |
| ClawHub | 根据其分发条款通过其 CLI 发布 | 为保留所选许可条款而排除 |
npm 包是 @containersecurity-dev/sip-skill,包含 skills/sip/ 和支持文档。它没有安装脚本或依赖。将其发布到 GitHub Packages 并不会同时将其发布到 npmjs.org,安装该包也不会自动向智能体注册该技能。
许可最终成为一个实际的发布约束。ClawHub 的发布文档称,上传的技能以 MIT-0 发布。我为 SIP 选择了 Apache-2.0,并排除了该渠道,而不是因为自动化带来的副作用而授予额外的许可条款。在将某个商店视为另一个上传目的地之前,请检查这些要求。
从标签到多个注册中心
SIP 使用两个工作流:
Version tag
→ validate metadata and run regression tests
→ build the canonical skill archive
→ derive npm and plugin packages
→ generate build provenance and create a draft release
→ publish the reviewed GitHub release
→ verify its downloaded assets
→ publish independently to each enabled registry
发布工作流会检查标签是否与 VERSION 匹配。规范归档用于派生 npm tarball 和 Claude/Cursor 插件 ZIP;后者包含 skills/sip/ 以及两个客户端的插件清单。所有三个归档都会获得溯源信息。
分发工作流在稳定的 GitHub 发布版本发布时启动。它会在将下载的归档交给注册中心客户端之前验证这些归档。它不会为每个商店单独重新构建技能。
GHCR 和 GitHub Packages 使用工作流的限定作用域 GitHub token。npm 发布需要 NPM_TOKEN 密钥和 NPM_PUBLISH=true 仓库变量。Docker Hub 有自己的凭据和启用标志。已禁用的作业会被报告为已跳过,这与成功发布不同。分发指南记录了确切的设置和剩余的手动提交。
下载并验证发布版本
在安装 GitHub CLI 并按需完成身份验证后,将发布资产下载到一个新目录:
mkdir sip-v1.0.0
cd sip-v1.0.0
gh release download v1.0.0 \
--repo ContainerSecurity-dev/sip-skill \
--pattern 'sip-*.tar.gz' \
--pattern 'sip-*.tgz' \
--pattern 'sip-*.zip' \
--pattern SHA256SUMS
sha256sum --check SHA256SUMS
gh attestation verify sip-1.0.0.tar.gz \
--repo ContainerSecurity-dev/sip-skill \
--signer-workflow ContainerSecurity-dev/sip-skill/.github/workflows/release.yml \
--source-ref refs/tags/v1.0.0
使用支持 gh attestation verify 的 GitHub CLI 版本。如果你打算安装的是对应的 .tgz 或 .zip 包,也要验证它。在将 sip/ 复制到所选客户端的技能目录之前,请查看已验证的内容。
OCI bundle 也可以在注册表认证后通过 ORAS 获取(如需要):
oras pull ghcr.io/containersecurity-dev/sip-skill:v1.0.0
SIP 使用项目专属的 artifact 类型 application/vnd.containersecurity.sip.bundle.v1。它是一组可下载文件的 bundle,不是可运行的容器,也不是前文讨论的任一 OCI skill 提案的实现。使用方可以用发布任务记录的 digest 对 bundle 做不可变固定。他们仍需要为自己的客户端验证并安装该 skill。
本地测试未能发现的发布故障
第一个 GHCR 任务在安装 ORAS 时失败了。尽管 ORAS 1.3.0 已经存在,但固定版本的 setup-oras action 内含一份较旧的、随附的发布目录,其中不识别该版本。
我将安装器 action 更新到一个经过验证、支持该 CLI 版本的 commit,然后从 main 针对现有 release 重试分发:
gh workflow run distribute.yml --ref main \
-f tag=v1.0.0 --repo ContainerSecurity-dev/sip-skill
随后 GHCR 成功,GitHub Packages 任务验证了首次运行已发布的版本。v1.0.0 标签和 release 资产保持不变。
固定工具版本能让流水线可复现,但安装器与所请求的工具版本也必须相互兼容。本地打包测试和工作流 lint 无法确认这一点;托管的 release 运行做到了。
接下来是什么?
Agent Skills 规范让可复用的 AI 工作流更具可移植性。下一个挑战是让它们的分发同样可靠。
理想情况下,skill 作者应当能够一次编写 skill、验证它、发布带版本的 artifact,并将其分发到兼容的市场。借助适当的发布管理、不可变 artifact、数字签名、安全验证和客户端专属适配器,发布 Agent Skills 可以变得像发布容器镜像一样常规。
OCI 提供了大部分底层基础设施。剩下的则是对打包约定、可互操作的安装器以及可靠的市场集成的共识。
我们已经标准化了 agent 学习 skill 的方式。现在我们需要标准化这些 skill 的流转方式。