Skip to content

Skill loading fails in Spring Boot 4 fat jars due to jar:nested: protocol; request for programmatic skill registration API #50

Closed

Description

@hujiayi0126

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.

Activity

  1. tzolov commented on Oct 3, 2026

    @tzolov
    Contributor

    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/:

    SkillsTool.builder()
        .addSkillsResource(new ClassPathResource(".claude/skills"))
        .build();
    • Loading via ClassPathResource already works in nested jars on 0.12.0 (the classpath scan fallback added after 0.7.0 handles jar:nested:).
    • With fix: aggregate skills across multiple SkillsJars sharing the same classpath prefix #90 and its follow-up (5a8d1cb), a classpath location contributed by several entries (your own META-INF/skills plus 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; 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.

  2. added a commit that references this issue on Oct 3, 2026
    87081aa
  3. added this to the 0.13.0 milestone on Oct 3, 2026
  4. tzolov commented on Oct 3, 2026

    @tzolov
    Contributor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions