Agent Skill 管理范式探索:像管理软件包一样管理 Agent 能力
以下全部内容是我和 Codex 共建完成,通过多轮对话,逐步推演出一套通用 Agent Skill Hub 管理范式;阅读本文,将了解如何像管理软件包一样管理 Agent 能力,并将 Skill 从本地经验沉淀为可复用、可发布、可部署、可回滚的企业级能力资产。
在过去一段时间里,Agent 生态里出现了很多关于 Skill、Prompt、Tool、MCP、Plugin、Workflow 的探索。大家都在尝试把一次有效的交互沉淀下来,让 Agent 下一次能更稳定地完成同类任务。
但在实际落地过程中,我很快会遇到一个问题,Skill 越来越多之后,该怎么管理?Skill 需要能被 Claude Code、OpenClaw、Codex、Spring AI Alibaba 等多个 Agent 应用加载,不单单被一个 Agent 固定死,需要兼容。
一开始的做法比较简单,把一个 SKILL.md 放在本地目录里,把几段提示词保存在笔记里,把某次任务中写出来的脚本丢到项目文件夹里。这个阶段很适合快速探索,但它有明显的边界:
- Skill 分散在不同 Agent 的私有目录中,难以复用。
- 缺少统一的命名、版本、发布时间和变更记录。
- 没有类似软件工程中的 package、release、deploy 和 rollback 流程。
- 不同 Agent 对 Skill 的读取和安装方式不一致。
- 企业自建 Agent 需要稳定加载能力目录,但本地文件夹很难直接进入生产环境。
这篇文章想讨论的是一个更底层的问题,当 Agent 能力开始被持续沉淀时,我们是否需要像管理软件包一样管理 Agent Skill?
我的答案是:需要。
一、从一个简单任务开始
这次探索的起点非常具体,尝试下载马蜂窝(一个旅行游记分享网站,下载仅供学习)网页上的图片,并且要下载原图,不要缩略图。
一开始,我只是完成了一个网页图片链接解析的脚本。随着任务推进,需求逐步变得清晰:
- 网页里拿到的图片链接通常带有缩略图参数。
链接中 ?后面的压缩、裁剪、质量参数需要去掉。- 最终导出的不是缩略图链接,而是原始链接。
链接清单不仅要有 URL,还要有文件大小,格式类似 链接,1.5M。输出文件夹要符合项目命名规范,比如 YYYYMMDD图片下载-地点或网页标题-原图。- 下载过程要支持断点续下,网络中断后不能从头重复下载。
- 下载完成后需要校验数量、文件有效性、链接是否仍包含缩略图参数。
我发现,问题已经从帮我下载网页上图片(简单爬虫),变成了把一类任务沉淀成可复用能力。
这就是 Skill 的工程价值。
一个高质量 Skill 是一段真实工作流的完整实现过程,它应该包含任务触发条件、输入输出规范、执行步骤、边界条件、脚本能力、样例数据和校验方式。
在这个过程中,我把马蜂窝图片下载任务沉淀成了第一个样板 Skill:mafengwo-original-images。每次对话都可以被加载进上下文,可以被复用、被安装、被验证的能力单元。
二、Skill 的工程目录
第一次接触 Skill,会把它理解成一个 SKILL.md 文件,这是起点,但不是最终形态。
如果 Skill 要面向真实任务,它至少要解决三个问题:
- 人能读懂。
- Agent 能触发。
- 程序能执行和校验。
因此,一个 Skill 更适合被组织成标准目录:
skills/
├── SKILL.md
├── skill.json
├── README.md
├── scripts/
├── examples/
└── adapters/
这里每个文件都有明确职责。
SKILL.md 是 Agent 读取的核心说明。它描述什么时候使用这个 Skill、任务目标是什么、输出格式是什么、执行流程是什么、最后如何校验。
skill.json 是机器可读元数据。它记录名称、版本、描述、入口文件、支持的 Agent、可能产生的副作用,例如网络访问或文件写入。
README.md 面向人类使用者,解释这个 Skill 怎么安装、怎么使用、典型输出是什么。
scripts/ 用来承载稳定、重复、容易出错的逻辑。比如图片下载、链接清洗、文件大小统计、断点续下等,不应该每次都让 Agent 临时重写。
examples/ 保存输入样例和输出样例,让 Skill 的行为更容易被理解和测试。
adapters/ 处理不同 Agent 之间的差异,比如 Claude Code、OpenClaw、Codex 或通用浏览器环境的使用方式。
这个结构背后有一个重要原则,Skill 是 Prompt、脚本、元数据、样例和适配文档的组合。
Prompt 负责表达意图,脚本负责保证确定性,元数据负责可发现和可治理,样例负责降低理解成本,适配层负责跨 Agent 复用。
三、从单个 Skill 到 Skill Hub
当只有一个 Skill 时,目录规范似乎已经足够。但只要继续往前走,就会出现新的问题,如果未来有几十个、几百个 Skill,该怎么组织?
这时我联想到软件工程中代码的组织规范,就是需要从 Skill 进一步抽象到 Skill Hub。
Skill Hub 的定位不是一个存放 Skill 的文件夹,而是一个跨 Agent 的能力仓库。它要服务三类对象:
- 人:需要阅读、维护、贡献和审阅 Skill。
- Agent:需要理解、触发、安装和执行 Skill。
- 企业运行时:需要稳定加载、发布、回滚和审计 Skill。
因此,Skill Hub 的根目录需要承担更高层次的治理职责:
skill-hub/
├── README.md
├── AGENTS.md
├── CLAUDE.md
├── SKILL_RELEASES.md
├── USAGE.md
├── DEPLOYMENT.md
├── registry.json
├── schemas/
├──…