在之前的开发中，我使用 ClasspathSkillRegistry 作为 Agent Skill 的查找策略，本地开发环境下调试、运行都一切正常，没有出现任何异常。
感兴趣的小伙伴可以回顾上一篇相关内容：https://www.lucaju.cn/index.php/archives/168/
一、问题出现：上线后频繁报「Skill not found」
本以为本地测试无误后，上线就能顺利运行，结果程序部署到服务器后，日志中频繁出现 Skill not found: 错误，导致相关功能完全无法使用。
二、问题排查：排除常见误区
遇到问题后，首先排查了最容易出现问题的两个点，均排除异常：
- 确认 Skill 已成功打包：检查部署的 jar 包，解压后确认 skill 相关文件已正常包含在内，不存在打包遗漏的情况；
- 确认 Skill Name 无误：核对代码中调用 Skill 的名称与配置文件中的名称，完全一致，排除拼写错误、大小写错误等问题。
三、问题根源：找到官方 Issue
排除上述常见问题后，推测可能是框架本身的兼容性问题，于是去 GitHub 上搜索相关问题，果然发现已有其他开发者遇到过相同情况，并且提交了 Issue：https://github.com/alibaba/spring-ai-alibaba/issues/4426
从 Issue 中得知，问题根源在于 SpringBoot 项目打包成 jar 包后，路径机制发生变化，导致 ClasspathSkillRegistry 无法正常加载 resources 下的 Skill 目录，这是目前 spring-ai-alibaba 框架的一个已知 bug。
四、临时解决方案：改用 FileSystemSkillRegistry
由于官方尚未修复该 bug，为了不影响线上功能正常使用，我采用了临时解决方案：将 Skill 目录存放在服务器的文件系统中，通过指定真实路径获取 Skill，对应的查找策略改用 FileSystemSkillRegistry。
修改后的核心代码如下：
/**
* 获取技能智能体钩子。
*/
private static SkillsAgentHook getSkillsAgentHook() {
// 注释掉原有的ClasspathSkillRegistry方式（本地可用，打包后失效）
// SkillRegistry registry = ClasspathSkillRegistry.builder()
// .classpathPath("skills")
// .build();
/*
临时解决方案说明：
spring ai alibaba 目前使用 ClasspathSkillRegistry 打包后，无法获取 Resource 下的目录
因此修改为使用 FileSystemSkillRegistry，从文件系统真实路径获取 Skill
相关 Issue：https://github.com/alibaba/spring-ai-alibaba/issues/4426
*/
String skillPath = SpringUtils.getProperty("doc.skills-path");
log.info("skillPath: {}",skillPath);
FileSystemSkillRegistry registry = FileSystemSkillRegistry.builder()
.projectSkillsDirectory(skillPath)
.build();
return SkillsAgentHook.builder()
.skillRegistry(registry)
.build();
}
五、后续
需要说明的是，这只是一个临时解决方案——使用该方案后，需要手动将 Skill 配置文件同步到服务器的指定路径（即配置项 doc.skills-path 对应的路径），增加了少量部署成本。
后续会持续关注官方 Issue 的修复进度，待 bug 修复后，再切换回 ClasspathSkillRegistry 方式，减少部署环节的手动操作。
也希望遇到相同问题的小伙伴，能通过这篇踩坑记录少走弯路～
