You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Skill loading fails in Spring Boot 4 fat jars due to jar:nested: protocol; request for programmatic skill registration API #50
When running an application as a Spring Boot 4 executable jar, SkillsTool.builder() throws IllegalArgumentException: At least one skill must be configured, even though the SKILL.md files are confirmed to be inside the jar at BOOT-INF/classes/.claude/skills//SKILL.md. The same configuration works fine when running from the IDE. This reproduces with spring-ai-agent-utils 0.7.0 on Spring AI 2.0.0-M6 and Java 21, both with addSkillsDirectory(...) and addSkillsResource(ClassPathResource).
The root cause appears to be Spring Boot's jar:nested: URL protocol (introduced in 3.2, still used in 4.x). Single-resource reads via ClassPathResource.getInputStream() work fine because NestedJarFile is a drop-in JarFile. But the directory enumeration that SkillsTool relies on internally — through PathMatchingResourcePatternResolver, JarURLConnection, and the manual classpath scan fallback — doesn't see entries nested under BOOT-INF/classes/ and returns zero skills. ArchUnit hit the same class of issue when Spring Boot first moved to nested jars.
The current builder API only takes directories or Resource objects representing directories, so there's no clean way around this. Affected users end up extracting SKILL.md files from the classpath to a writable temp directory at startup and pointing addSkillsDirectory() at that — which works, but requires an explicit list of skill names (defeating the original "drop a folder in" UX) and a writable filesystem (awkward in hardened containers).
Would you consider adding a programmatic registration method on the builder, something like addSkill(name, description, content), that bypasses resource resolution entirely? It would let users implement their own discovery for environments where the built-in scanners can't reach the files (Spring Boot 4 fat jars, GraalVM native images, etc.), while keeping all existing APIs untouched. Happy to discuss the API shape or send a PR if there's interest.
Thanks for the detailed analysis @hujiayi0126. An update for 0.13.0:
I verified skill loading from a Spring Boot 4.0.2 executable jar (java -jar, jar:nested: URLs) with skills packaged under BOOT-INF/classes/.claude/skills/ and under META-INF/skills/, plus a SkillsJar dependency in BOOT-INF/lib/:
addSkillsDirectory(...) takes a filesystem path, so it cannot see resources inside a jar; use addSkillsResource(new ClassPathResource(...)) for packaged skills.
For skills discovered or generated by other means, PR #93 adds programmatic registration (SkillsTool.Builder.addSkill(name, description, content)). I will close this issue once that lands.
Resolved for 0.13.0. As described in the comment above, packaged skills load from Spring Boot 4 executable jars via addSkillsResource(new ClassPathResource(...)), and with #90 (plus 5a8d1cb) skills from your own classpath directory and SkillsJars are aggregated. For skills that are not packaged as SKILL.md files, #93 adds SkillsTool.Builder.addSkill(name, description, content) (see the "Registering Skills Programmatically" section of the SkillsTool docs). Please reopen if you still hit problems on 0.13.0.
Activity
tzolov commentedon Oct 3, 2026
Thanks for the detailed analysis @hujiayi0126. An update for 0.13.0:
I verified skill loading from a Spring Boot 4.0.2 executable jar (
java -jar,jar:nested:URLs) with skills packaged underBOOT-INF/classes/.claude/skills/and underMETA-INF/skills/, plus a SkillsJar dependency inBOOT-INF/lib/:ClassPathResourcealready works in nested jars on 0.12.0 (the classpath scan fallback added after 0.7.0 handlesjar:nested:).META-INF/skillsplus SkillsJars) now returns the skills from all of them; 0.12.0 returned only the first.addSkillsDirectory(...)takes a filesystem path, so it cannot see resources inside a jar; useaddSkillsResource(new ClassPathResource(...))for packaged skills.For skills discovered or generated by other means, PR #93 adds programmatic registration (
SkillsTool.Builder.addSkill(name, description, content)). I will close this issue once that lands.feat: add programmatic skill registration via SkillsTool.Builder.addS…
tzolov commentedon Oct 3, 2026
Resolved for 0.13.0. As described in the comment above, packaged skills load from Spring Boot 4 executable jars via
addSkillsResource(new ClassPathResource(...)), and with #90 (plus 5a8d1cb) skills from your own classpath directory and SkillsJars are aggregated. For skills that are not packaged as SKILL.md files, #93 addsSkillsTool.Builder.addSkill(name, description, content)(see the "Registering Skills Programmatically" section of the SkillsTool docs). Please reopen if you still hit problems on 0.13.0.