Eliminate SKILL.md Duplication: Managing Agent Skills with Spring AI and LangChain4j

Java AI developers have long struggled with the lack of a unified package management mechanism for Agent Skills, forcing them to copy SKILL.md files across projects, leading to high maintenance cost, version drift, and collaboration friction.

What is SkillsJars

SkillsJars treats Agent Skills (Markdown files that describe how an AI should act in specific scenarios) as Maven artifacts, effectively providing an "Agent Skills Maven Central". Each skill file is placed under META-INF/skills/ inside a JAR and published to Maven Central.

---
name: debugging-and-error-recovery
description: Guides systematic root-cause debugging. Use when tests fail, builds break, or behavior doesn't match expectations.
allowed-tools: Bash Read Edit
license: MIT
---

# Debugging and Error Recovery

## When to use this skill
...

The artifact ID follows the pattern {github-org}__{github-repo}__{skill-name}, for example:

addyosmani__agent-skills__debugging-and-error-recovery

Adding a dependency automatically handles versioning and team synchronization.

Usage 1 – Supplying Skills to AI Coding Assistants

Most AI coding assistants (Claude Code, Codex, etc.) expect skills as files in specific directories. SkillsJars provides a Maven/Gradle plugin that extracts the packaged skills to the required location.

<build>
    <plugins>
        <plugin>
            <groupId>com.skillsjars</groupId>
            <artifactId>maven-plugin</artifactId>
            <version>0.0.6</version>
            <dependencies>
                <dependency>
                    <groupId>com.skillsjars</groupId>
                    <artifactId>addyosmani__agent-skills__debugging-and-error-recovery</artifactId>
                    <version>2026_04_03-a806c63</version>
                </dependency>
                <dependency>
                    <groupId>com.skillsjars</groupId>
                    <artifactId>addyosmani__agent-skills__code-review-and-quality</artifactId>
                    <version>2026_04_03-a806c63</version>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

Run the extraction command to place the files where the assistant expects them:

# Extract to Claude Code directory
./mvnw skillsjars:extract -Ddir=.claude/skills

# Or to Codex directory
./mvnw skillsjars:extract -Ddir=.agents/skills

After execution, the .claude/skills/ directory contains the corresponding SKILL.md files, which Claude Code automatically recognizes.

Usage 2 – Integrating SkillsTool in Spring AI

When building an agent with Spring AI, the spring-ai-agent-utils library provides a SkillsTool that reads skills directly from the classpath, eliminating the extraction step.

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-agent-utils</artifactId>
    <version>0.5.0</version>
</dependency>

<dependency>
    <groupId>com.skillsjars</groupId>
    <artifactId>addyosmani__agent-skills__code-review-and-quality</artifactId>
    <version>2026_04_03-a806c63</version>
</dependency>

Configure the skill path in application.properties: agent.skills.paths=classpath:/META-INF/skills Inject the tool into the ChatClient:

@Configuration
public class AgentConfig {
    @Value("${agent.skills.paths}")
    private List<Resource> skillPaths;

    @Bean
    public ChatClient chatClient(ChatClient.Builder builder) {
        return builder
            .defaultToolCallbacks(
                SkillsTool.builder()
                    .addSkillsResources(skillPaths)
                    .build()
            )
            .build();
    }
}

The agent automatically perceives registered skills and activates the appropriate one based on the request.

Usage 3 – Using Skills API in LangChain4j

LangChain4j offers native support for skills via the langchain4j-skills module.

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-skills</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Load skills from the file system:

Skills skills = Skills.builder()
    .loader(new FileSystemSkillLoader(Path.of(".claude/skills")))
    .build();

Or load from the classpath when using a SkillsJar:

Skills skills = Skills.builder()
    .loader(new PathSkillLoader("META-INF/skills/addyosmani/agent-skills"))
    .build();

Integrate the loaded skills into an AI service:

MyAiService aiService = AiServices.builder(MyAiService.class)
    .chatModel(chatModel)
    .tools(new PigOrderTools()) // business tools
    .toolProvider(skills.toolProvider())
    .systemMessage(
        "You have access to the following skills:
" +
        skills.formatAvailableSkills() +
        "
When the user's request relates to one of these skills, activate it first using the `activate_skill` tool before proceeding."
    )
    .build();

Skills can also register dedicated tools that become visible only after the corresponding skill is activated, preventing tool overload.

Publishing Your Own SkillsJar

Teams can package project‑specific skills into a SkillsJar for internal or community sharing.

Directory layout example:

skills/
├── pig-permission-review/
│   ├── SKILL.md
│   └── permission-patterns.md
└── pig-api-design/
    └── SKILL.md

Each SKILL.md starts with a frontmatter block, e.g.:

---
name: pig-permission-review
description: Conducts permission and data‑scope review for Pig RBAC systems. Use when reviewing code that touches SysUser, SysRole, or DataScope.
allowed-tools: Bash Read Edit
license: MIT
---

Add the packaging plugin to pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>com.skillsjars</groupId>
            <artifactId>maven-plugin</artifactId>
            <version>0.0.6</version>
            <executions>
                <execution>
                    <goals>
                        <goal>package</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Running mvn package bundles the skills/ content into META-INF/skills/{org}/{repo}/{skill}/ inside the JAR. After pushing the repository to GitHub, submit the form on SkillsJars.com to publish the artifact to Maven Central.