直接说结论:Skill 系统正在成为 AI Agent 工程化落地的一块关键拼图。HagiCode 把“技能”做成了一等公民,让 AI 能力的组织方式从“写死提示词”变成了“声明式技能文件”。这篇文章会从架构设计、目录结构、MCP 边界、可扩展机制、实操案例到排坑经验,一次性讲清楚怎么搭一个能持续长出技能的 AI 技能管理平台。
先交代一下背景。做 AI Agent 相关开发的朋友,最近两年应该没少听到“Skill”这个词。从 Anthropic 的 Claude Code 把 Skill 作为扩展机制推到台前,到 Codex、Cursor、OpenCode 这些 AI 编程工具纷纷跟进,再到 Spring AI 也在往技能注册的方向靠,Skill 几乎成了 AI 应用开发绕不开的抽象层。HagiCode Skill 系统本质上就是干这件事的:把 AI 能力拆成可复用、可扩展、可治理的“技能单元”,让 Agent 不再只会聊天,而是能按需调用工具、执行流程、输出结构化结果。
我自己在多个项目里实践过这套思路,从最早的“提示词写死在代码里”,到后来用 Skill 目录管理几十个技能,整个过程踩了不少坑,也总结出了一些可复用的套路。HagiCode 的设计理念和我不谋而合的地方在于:它解决的是三个非常实际的问题。第一,技能怎么定义、怎么组织,才能让模型“看得懂、用得上”;第二,技能数量上来了以后,怎么维护、升级、避免冲突;第三,第三方开发者怎么把自己的专业能力沉淀成技能,而不需要改 Agent 主程序。带着这三个问题去读这篇文章,你会更有体感。
1. HagiCode Skill 系统的设计思路与整体架构
1.1 从“写死提示词”到“技能即文件”
很多团队最早做 Agent,实现方式就是提示词硬编码。用户说“帮我分析一下这个项目”,代码里就拼一段固定的 prompt,再调一个写死的函数,把上下文传给大模型。这种做法的痛点是:每加一个能力,就要改代码、走发布流程,提示词和业务逻辑完全耦合,时间一长维护成本高得吓人。HagiCode 换了个思路——把技能定义成一组标准文件,放在约定的目录里,由 Agent 在运行时按需发现和加载。这个思路可以叫“技能即文件”,和配置中心、插件体系的思路一脉相承,只是粒度更细,语义更明确。
“技能即文件”的直接好处是什么呢?我在自己项目里实测下来,最大的感受就是:技能不需要重新编译,不需要改动主程序,就能热插拔。我把一个“接口文档生成”技能丢进 skills 目录,再配一个简单的注册清单,Agent 下一次对话就能识别并调用它。整个上线过程不用重启服务,对现有系统几乎零侵入。对比之前那种硬编码工具函数的方案,维护体验不是一个量级。
这里有一个关键点要展开说:为什么“文件”比“数据库记录”更合适?我一开始也想过把技能存到数据库里,后来发现文件系统天然具备几个优势。第一,可版本化,技能文件可以直接进 Git,每次改动有历史记录,可以 review、可以回滚;第二,可测试,技能目录拉下来就能在本地跑,不依赖线上环境;第三,生态友好,第三方贡献者通过 Pull Request 就能提交新技能,不需要数据库权限。HagiCode 在这一点上选了和社区一致的做法,看似简单,实际是经过权衡的。
1.2 技能粒度:按任务划分,不按原子操作划分
设计技能粒度是我踩过最深的坑之一。最初我天真地认为,技能当然拆得越细越灵活,于是做了“读取文件”“搜索代码”“运行测试”这种一个功能一个技能。结果 Agent 每次完成一个简单目标,都要串五六个技能,上下文 token 开销巨大,而且经常出现调用顺序错乱——模型并不知道应该先读文件还是先搜代码,我也没有在技能描述里给它讲清楚。后来才意识到,技能粒度应该按“任务”来划分,而不是按“原子操作”来划分。
一个合格的技能,应该对应一个完整的、可以用自然语言描述的任务。比如“项目体检”“接口文档生成”“代码评审”“依赖安全扫描”,这些都是任务。而“读取文件”“写入文件”是原子操作,它们应该被封装在技能内部,作为脚本的一部分,而不是暴露给模型让模型自己拼。HagiCode 的设计在这个点上非常清晰:元信息负责描述“技能是干什么的”,说明文档负责教模型“技能怎么做”,脚本负责真正执行“底层操作”。三者配合,模型看到的是任务级描述,调用的是封装好的能力,而不是面对一堆细碎函数手足无措。
我的建议是,技能粒度可以参考“一个技能对应一次完整的用户诉求”这个标准。如果一个任务的完成需要多个步骤,那这些步骤应该写进技能内部的工作流文档里,由技能自己去调度,而不是让外部 Agent 去编排。这样做还有一个隐藏好处:技能的脚本和说明文档可以独立测试,只要你把输入输出定义清楚,技能的复用率会大幅提升。
1.3 整体架构分层:注册中心、运行时、沙箱
HagiCode 的整体架构,拆开来看可以分成三层。最上层是注册中心,负责维护所有技能清单、版本、依赖关系,相当于一个技能目录。中间是运行时,负责把 Agent 的意图转换成具体的技能调用,包括技能匹配、参数注入、上下文拼装。最底层是执行沙箱,负责实际运行技能脚本,并对网络、文件系统、外部命令做权限控制。
这个分层的逻辑,和操作系统管理进程的思路很相似。注册中心相当于“进程表”,运行时相当于“调度器”,沙箱相当于“用户态隔离”。为什么一定要分这么多层?因为要把“技能声明”和“技能执行”彻底解耦。这样当技能脚本出问题的时候,不会拖垮整个 Agent 进程;技能升级时,只需要替换注册中心里的版本引用;技能有风险时,可以在沙箱里直接禁用它,而不用改其他代码。这些好处在本地小玩具项目里不明显,一旦上了生产环境,碰上线上故障,你就知道分层是多么重要了。
三层里面最容易被忽略、但实际最值得关注的是沙箱层。很多 Skill 系统暴露出安全问题,基本都是栽在这一层。你把技能开放给第三方作者编写,就相当于让别人在你的进程里跑代码。如果不做权限隔离,一个恶意技能就能读取你的环境变量、删除你的文件、向外发送数据。HagiCode 在沙箱里做了命令白
