Newshot

AI 技能及其分发方式

Translation(model translation, not the source's own text)

AI 世界是一片蛮荒西部,AI 编码智能体则是新来的牛仔。这让事情既刺激又混乱。在这篇文章中,我尝试解释 AI Agent Skills 的现状,因为我自己之前也不了解,不得不费一番功夫才弄明白。

TL;DR:AI Skills 是可复用的软件包。它们就像是 React 网站的 NPM 包、笔记本电脑的即插即用设备、Skyrim 游戏的 mod。

那么,就让我们在这片混乱中坐下来,看看能学到什么。

一个名叫 Jack 的身披装甲的机器人牛仔从 AI 包中弹出,周围环绕着发光的代码、工具和工作流符号。
一个名叫 Jack 的身披装甲的机器人牛仔从 AI 包中弹出,周围环绕着发光的代码、工具和工作流符号。

什么是 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 格式的客户端越来越多:

  • Claude Code — Anthropic 的编码智能体,支持 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 制品或许能提供一种答案。

现有提案

目前有两个值得关注的规范正在制定中:

  1. Agent Skills OCI Artifacts Specification

Thomas Vitale 的提案定义了一种用于单个技能和技能集合的 OCI 制品格式。

它引入了一种专用的制品类型:


        application/vnd.agentskills.skill.v1
      

该规范涵盖清单(manifest)、配置、打包、版本管理以及基于摘要(digest)的安装。Arconia 等实现展示了如何将技能发布到 OCI 注册表。

  1. 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 的流转方式。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗