从零搭建企业级AI Agent技能系统Spring AI Alibaba Skills实战指南摘要详解Spring AI Alibaba Skills技能系统从核心概念到企业级OSS多租户实现手把手教你打造可扩展的AI Agent能力体系。 为什么你的AI Agent总是不够聪明你有没有遇到过这样的场景给AI Agent写了一大段系统提示结果Token消耗惊人响应还慢想让Agent处理Word文档、生成PDF、做代码审查得把所有能力都塞到提示词里又乱又难维护不同用户需要不同的能力却没法做到按需加载、多租户隔离…如果你也有这些困扰那么这篇文章就是为你准备的今天我们来深入聊聊Spring AI Alibaba Agent Framework中的Skills技能系统——一个让AI Agent能力模块化、可复用、按需加载的优雅解决方案。读完这篇文章你将学会✅ Skills的核心设计思想和工作原理✅ 三种内置技能注册表的使用方式✅ 如何实现渐进式工具披露✅ 企业级多租户OSS技能中心搭建✅ 生产环境的最佳实践和踩坑指南 什么是Skills一句话讲明白Skills就是AI Agent的技能包。你可以把每个Skill理解为一本操作手册它告诉AI在什么场景下、用什么方法、按照什么步骤来完成特定任务。和传统把所有指令都塞进系统提示不同Skills采用了一个非常聪明的设计——渐进式披露Progressive Disclosure。什么是渐进式披露打个比方你去餐厅吃饭服务员不会一开始就把所有菜的做法都背给你听。而是先给你一份菜单技能列表你点了某道菜之后厨师才会按照菜谱SKILL.md来做。Skills的工作流程就是这样第一步系统提示里只放菜单——有哪些技能、每个技能是干嘛的第二步AI判断用户需要什么技能主动调用read_skill(技能名)第三步加载完整的技能说明书按照里面的步骤执行任务第四步需要的时候再调用和这个技能绑定的专用工具这样做的好处太明显了省Token不用一次性加载所有技能内容好维护技能独立成目录改一个不影响其他♻️可复用写好的技能可以在多个项目间共享易扩展想对接OSS、数据库自定义Registry就行 一个技能长什么样每个技能就是一个文件夹里面必须有一个叫SKILL.md的文件。就像这样my-skill/ ├── SKILL.md # 必需技能说明书 ├── references/ # 可选参考资料 ├── examples/ # 可选示例代码 └── scripts/ # 可选可执行脚本SKILL.md怎么写SKILL.md的开头必须有一段YAML配置叫frontmatter用---包起来--- name: docx description: 用于创建、编辑Word文档支持标题、表格、图片等。触发词Word、.docx、报告 --- # Word文档生成技能 ## 使用说明 当用户需要生成.docx文档时使用本技能... ## 工作流程 1. 第一步... 2. 第二步...划重点name技能名字要和文件夹名一致建议用小写连字符description这个太重要了AI就是靠它判断什么时候用这个技能一定要写清楚触发场景和关键词避坑提醒description写得太模糊AI就不知道什么时候该用这个技能。一定要把触发关键词列出来 快速上手三种方式加载技能Spring AI Alibaba提供了两种内置的技能注册表我们还会讲项目中自定义的OSS实现。方式一本地文件系统开发推荐最简单的方式直接从项目目录加载技能// 1. 创建注册表指向项目下的skills文件夹SkillRegistryregistryFileSystemSkillRegistry.builder().projectSkillsDirectory(System.getProperty(user.dir)/skills).build();// 2. 创建Skills钩子SkillsAgentHookhookSkillsAgentHook.builder().skillRegistry(registry).build();// 3. 构建AgentReactAgentagentReactAgent.builder().name(skills-agent).model(chatModel).hooks(List.of(hook)).build();// 4. 开始对话agent.call(你有哪些技能);适合场景本地开发、单机部署。方式二类路径加载生产打包推荐把技能文件放到src/main/resources/skills下打包进JARSkillRegistryregistryClasspathSkillRegistry.builder().classpathPath(skills).build();适合场景JAR包部署、技能随应用一起发布。方式三OSS云存储企业级多租户这是我们项目中实际在用的方案——基于阿里云OSS实现技能中心支持 公共技能 用户私有技能多租户隔离⚡ Redis三级缓存多实例共享 自动同步到本地供Shell工具访问 REST API支持技能上传删除这个我们后面详细讲⚡ 高级玩法让工具也按需加载你以为只有技能内容是按需加载的Too young工具也可以想象一下你有10个技能每个技能绑定2个专用工具那就是20个工具。如果一开始就把20个工具都给AI它会晕的。渐进式工具披露就是来解决这个问题的只有AI加载了某个技能之后和这个技能绑定的工具才会出现代码也很简单// 1. 创建你的专用工具ToolCallbackwritingToolFunctionToolCallback.builder(writing_tool,newWritingTool()).description(生成结构化中文文章).inputType(WritingRules.class).build();// 2. 把工具和技能绑定key就是技能的nameMapString,ListToolCallbackgroupedToolsMap.of(docx,List.of(writingTool));// 3. 传给SkillsAgentHookSkillsAgentHookhookSkillsAgentHook.builder().skillRegistry(registry).groupedTools(groupedTools)// 就这一行.build();效果AI没加载docx技能前看不到writing_toolAI调用read_skill(“docx”)后writing_tool自动可用会话后续轮次工具一直可用不用重复激活设计哲学渐进式披露的本质是认知负荷管理——不要让AI一次性面对太多选择在正确的时机给正确的信息和工具。 企业级实战搭建多租户OSS技能中心这部分是我们项目的干货——在官方两种Registry的基础上我们实现了基于阿里云OSS的企业级技能中心。核心特性一览特性说明多租户隔离公共技能所有用户共享用户私有技能按userId隔离Redis三级缓存技能列表、元数据、内容分别缓存TTL 30分钟本地同步技能自动同步到本地临时目录Shell工具直接访问REST API提供上传/删除接口前端可直接集成匿名访问支持公共读Bucket不用配置AK/SKOSS目录结构test/skills/ # 技能根目录 ├── frontend-design/ # 公共技能 │ ├── SKILL.md │ └── scripts/ ├── docx/ # 公共技能 │ └── SKILL.md └── users/ # 用户私有技能 ├── user001/ │ └── my-skill/ │ └── SKILL.md └── user002/ └── private-skill/ └── SKILL.md代码架构五层设计我们的代码分为清晰的五层Controller层提供REST接口POST/api/skills/public/upload上传公共技能POST/api/skills/user/{userId}/upload上传私有技能DELETE 删除技能Service层业务逻辑SkillUploadService处理文件夹上传、自动提取技能名、校验SKILL.mdSkillsChatService各种使用场景的示例代码Registry/Cache层核心能力OssSkillRegistry从OSS加载技能继承AbstractSkillRegistrySkillCacheServiceRedis缓存服务按userId隔离Config/Model层配置和数据OssSkillPropertiesOSS配置endpoint、bucket、前缀等SkillUploadResult上传结果DTOTool层适配工具WritingTool文章编写工具自动处理UTF-8 BOMQwenCompatibleChatModel通义千问JSON参数修复QwenCompatibleShellToolShell工具适配使用起来超简单SkillRegistryregistryOssSkillRegistry.builder().properties(ossSkillProperties).userId(userId)// 指定用户自动隔离私有技能.cacheService(skillCacheService)// 开启Redis缓存.localCacheDirectory(localCacheDir)// 同步到本地供Shell用.build();SkillsAgentHookhookSkillsAgentHook.builder().skillRegistry(registry).build();// 然后正常构建Agent就行啦读取优先级技能内容读取有三级优先级性能拉满Redis缓存最快多实例共享本地临时文件次快Shell工具直接读OSS远程下载兜底读完自动回写缓存️ 实战技巧这些坑我们帮你踩过了技巧1SKILL.md的description一定要写好反例别这么写description:文档处理工具太模糊了AI根本不知道什么时候用。正例学这个description:用于创建、读取、编辑Word文档.docx支持标题、目录、表格、图片。触发关键词Word文档、.docx、报告、备忘录、模板场景明确关键词清晰AI一看就知道什么时候该调用。技巧2Windows环境注意编码和路径如果你的应用跑在Windows上比如本地开发这几点一定要注意写文件用Node.js的fs.writeFileSync别用PowerShell的Set-Content大段文本会超时中文文件一定要加UTF-8 BOM\ufeff否则记事本打开乱码路径用Windows格式D:\project\...别用/home/、/tmp/多条命令用分号;分隔别用别用printf、cat这些Unix命令技巧3通义千问JSON参数问题用qwen-plus调用工具时你可能会遇到这个错误The function.arguments parameter must be in JSON format.这是因为qwen返回的ToolCall arguments有时候引号转义有问题。我们写了一个QwenCompatibleChatModel包装器自动拦截所有请求响应对arguments做Jackson解析重新序列化处理JSON截断、未转义引号等异常情况用的时候包一层就行ChatModelcompatibleModelnewQwenCompatibleChatModel(originalModel);技巧4技能上传后记得清缓存新技能上传到OSS后Redis里可能还有旧的缓存。我们的上传服务在删除/上传用户技能后会自动调用evictUserCache(userId)清缓存。如果没开自动重载下次请求重建Registry的时候就会加载最新的技能了。 生产环境Checklist上线前对照这张表检查一下Redis缓存已配置TTL设置合理建议30分钟OSS Bucket权限配置正确公共读或正确的AK/SK本地临时目录按userId隔离避免多用户冲突SKILL.md的name、目录名、groupedTools的key三者一致大模型的ToolCall JSON兼容性已处理qwen用户注意Windows环境下的中文编码BOM已加技能文件大小控制在1.5k-2k tokens长内容放references开启日志方便排查技能加载问题 总结今天我们从原理到实战完整梳理了Spring AI Alibaba的Skills技能系统核心理念渐进式披露按需加载省Token又好维护三种Registry本地文件系统、类路径、OSS云存储高级特性渐进式工具披露、自动重载、自定义提示模板企业级实现多租户隔离、Redis缓存、本地同步、REST API实战避坑description写法、Windows编码、qwen兼容性、缓存清理Skills的本质是把AI Agent的能力从臃肿的提示词中解放出来变成模块化、可复用、可管理的独立单元。这才是构建复杂AI应用的正确打开方式。希望这篇文章能帮你打造出更强大、更易维护的AI Agent 参考资源官方文档https://java2ai.com/docs/frameworks/agent-framework/tutorials/skills项目源码src/main/java/com/spring/ai/alibaba/agent/springaialibabaagent/Skills/ 三连支持动力源泉如果这篇文章帮你省下了踩坑的时间欢迎点赞—— 让更多人看到这篇干货收藏—— 以后用到的时候翻出来不迷路评论—— 你的留言是我持续输出的动力你的每一个小动作对我都很重要 ❤️ 关于作者你好我是门主一个常年和Bug战斗、持续填坑的Java开发者。这里专注分享✅ Java / Spring Boot / Spring AI Alibaba 企业级实战✅ RAG知识库、AI Agent、多智能体协作落地经验✅ Docker部署、微服务架构、线上问题排查✅ 偶尔聊聊「如何保住头发」这类程序员终极话题 不搞水文不贩卖焦虑只写能跑通、能落地、能帮你少加班的实战内容。关注我咱们一起少踩坑多写优雅代码。 更多干货推荐告别手动复制接口文档Apifox MCP AI 自动测试让开发效率起飞别再纠结学哪个了Java AI 三大框架深度对比Spring AI vs AgentScope-JavaMySQL MCP Server 从零安装到使用实战AI 直接查询数据库Spring 注入三剑客Resource、Autowired、RequiredArgsConstructor 到底该用哪个Spring Event 用了三年同事一句话把我问懵了Java 抽象类Abstract Class彻底讲透从基础到多态实战Spring AI Alibaba 多智能体Multi-agent实战6 大协作模式 完整代码Spring AI Alibaba 智能体作为工具实战别再让主 Agent 当人肉路由器了 粉丝福利本文涉及的完整源码 OssSkillRegistry可运行Demo 配置示例已打包整理好。免费获取方式在评论区留言【skills】或者直接私信我看到后会第一时间发送源码包。 对文章内容有疑问想看下一篇写什么主题直接在评论区留言你的每一条评论我都会看。说不定下一篇文章的主题就来自你的问题 项目合作 / 技术咨询平时工作之余也会接一些技术项目和咨询主要方向⚔️企业级开发Java / Spring Boot 项目开发与重构微服务架构设计与落地系统性能调优、线上问题排查AI 应用落地这是我最近的主力方向Spring AI Alibaba / RAG / Agent 应用开发企业私有知识库搭建AI能力接入现有业务系统大模型本地化部署与调优️技术顾问 / 疑难Bug排查项目架构评审与方案设计线上疑难问题定位解决技术选型与团队培训如果你正遇到以下情况欢迎找我聊聊✅ 想做AI项目但技术方案拿不准✅ 项目卡在某个Bug上很久团队搞不定✅ 想把AI接入现有业务不知道从哪下手✅ 需要靠谱的开发外包或长期技术顾问联系渠道按回复速度排序最快CSDN 站内私信一般24小时内回复邮件2929119150qq.com请注明来意和具体需求一个人踩坑是事故一群人踩坑就是《避坑宝典》。—— IT 空门与诸君共修技术大道