Mastering Agent Skills in LangChain4j: Build a Java Code Analysis Assistant

Introduction to LangChain4j

LangChain4j is a Java‑focused framework that provides a unified abstraction layer for building LLM‑powered applications, similar to how Spring standardizes Java web development. It offers a consistent API for various models, tool calling, RAG support, and memory management.

Agent Skills Overview

Agent Skills, introduced in version 1.12.1 (March 2026), allow developers to package reusable, self‑contained behavior instructions for LLMs. Compared to a traditional system prompt (a bulky manual the model must constantly reference), an Agent Skill acts like a modular "skill pack" that can be activated on demand.

A skill consists of:

name : the skill identifier, e.g., "process-order".

description : a brief summary of its purpose.

content : detailed execution instructions, steps, cautions, examples, etc.

resources : optional references such as configuration files or documentation.

Practical Example: Creating a Code‑Analysis Skill

Scenario

The goal is to build a skill that helps developers understand complex code by providing analogies, ASCII diagrams, step‑by‑step explanations, and highlighting common pitfalls.

Step 1 – Add Maven Dependency

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-skills</artifactId>
    <version>1.12.0-beta20</version>
</dependency>

Step 2 – Create the Skill File

Directory layout:

skills/
└── explain-code/
    └── SKILL.md

Content of SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life.
2. **Draw a diagram**: Use ASCII art to show flow, structure, or relationships.
3. **Walk through the code**: Explain step‑by‑step what happens.
4. **Highlight a gotcha**: Point out a common mistake or misconception.

Keep explanations conversational. For complex concepts, use multiple analogies.

Step 3 – Load the Skill and Integrate into an AI Service

import dev.langchain4j.service.AiServices;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.skill.FileSystemSkillLoader;
import dev.langchain4j.skill.Skills;
import java.nio.file.Path;
import java.util.List;

public class CodeExplainer {
    public static void main(String[] args) {
        // 1. Load Skills
        List<FileSystemSkill> skillList = FileSystemSkillLoader.loadSkills(Path.of("skills/"));
        Skills skills = Skills.from(skillList);

        // 2. Create AI Service
        ExplainerService service = AiServices.builder(ExplainerService.class)
                .chatModel(chatModel)
                .tools(new CodeAnalysisTools()) // register tools
                .toolProvider(skills.toolProvider()) // register Skills
                .systemMessage(
                        "You are a code analysis assistant.
" +
                        "You can use the following skills:
" +
                        skills.formatAvailableSkills() +
                        "
When the user asks to explain code, activate the explain-code skill."
                )
                .build();

        // 3. Use the service
        String result = service.explainCode("src/main/java/Example.java");
        System.out.println(result);
    }

    interface ExplainerService {
        String explainCode(String filePath);
    }
}

Step 4 – Expected Runtime Behavior

When service.explainCode("src/main/java/Example.java") is invoked, the AI will:

Detect that the "explain-code" skill should be used.

Call activate_skill("explain-code") to load the detailed instructions.

Execute the steps defined in SKILL.md:

Provide an analogy (e.g., "the singleton pattern is like a company with only one CEO").

Generate an ASCII diagram via generateDiagram().

Read the source code with readCode().

Analyze complexity using analyzeComplexity().

Walk through the execution flow step‑by‑step.

Highlight common pitfalls (e.g., thread‑safety concerns).

Finally, the assistant returns a comprehensive code‑analysis report.

Conclusion

Agent Skills bring modularity to Java AI development, allowing developers to manage AI behavior as reusable, self‑contained modules—much like managing code libraries. Starting with LangChain4j 1.12.1, Java developers can encapsulate code analysis, data processing, document editing, and more into independent skills that are easily shared across projects.