A Guide to Agent Skills in Spring AI

1. Overview

Modern web applications are increasingly integrating with Large Language Models (LLMs) to build solutions that go beyond simple question answering. To create AI agents capable of handling complex user requests, we often connect them to multiple Model Context Protocol (MCP) servers that provide them with specific capabilities via tools.

However, creating and running MCP servers can be overkill for lightweight and local automation tasks where we just need to expose a simple capability to a single agent.

Agent Skills is a specification that provides a structured way to locally define, package, and expose these capabilities to an AI agent.

In this tutorial, we’ll explore the Agent Skills capability in Spring AI. We’ll configure a custom skill and integrate it with a simple chatbot to summarize articles.

2. What are Agent Skills?

Agent Skills is an open specification for defining various capabilities that an AI agent can invoke. A skill is essentially a directory containing a SKILL.md file, which acts as its manifest, alongside any associated code like Python or Bash scripts, or additional resources that the skill relies on.

The SKILL.md file contains a frontmatter block with a name and description, followed by a set of natural language instructions that tell the agent how to use the skill.

When the agent receives a user request, it reads the descriptions of all available skills and decides if any is relevant. If yes, it then loads the relevant files into context and follows the instructions inside the matching skill to fulfill the request. And if no skill matches the request, the agent simply responds using its general capabilities without invoking any skill.

We’ll see an agent invoking our custom skill practically in action in the upcoming sections.

3. Setting up the Project

Before we dive into the implementation, we’ll need to include the necessary dependencies and configure our application correctly.

3.1. Dependencies

Let’s start by adding the necessary dependencies to our project’s pom.xml file:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
    <version>2.0.0</version>
</dependency>
<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-agent-utils</artifactId>
    <version>0.10.0</version>
</dependency>

Here, we first import Spring AI’s OpenAI starter dependency, which we’ll use to interact with a chat model. Support for agent skills is available in Spring AI 2 and later, so we need to make sure we’re using the correct version.

Next, we import the agent-utils dependency from the Spring AI community, which enables us to add the agent skills capability to our chat models.

3.2. Configuring a Chat Model

Next, let’s configure our OpenAI API key and chat model in the application.yaml file:

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-5.5

We use the ${} property placeholder to load the value of our API Key from an environment variable.

Additionally, we specify OpenAI’s GPT 5.5 model using the gpt-5.5 model ID. Alternatively, we can use a different chat model that supports the agent skills specification, as the specific AI model or provider is irrelevant for this demonstration.

With these two properties set, Spring AI automatically creates a bean of type ChatModel, allowing us to interact with the specified model.

4. Defining Our Custom Skill

Now let’s define a custom agent skill that can fetch an article from a URL and summarize it.

Agent skills follow a specific directory structure, so let’s set that up. We’ll start by creating an .openai/skills directory in our project’s root directory. We can define multiple subdirectories inside this, each representing a distinct agent skill.

Next, we’ll create an article-summarizer subdirectory to represent our custom skill inside .openai/skills and define our main SKILL.md file inside it:

---
name: article-summarizer
description: Summarizes articles into concise digests. Useful when user asks to summarize or get key points from an article.
---
# Article Summarizer
## Instructions
When summarizing an article:
1. If given a URL: Run `uv run scripts/fetch_article.py <url>` to retrieve the content.
2. Once content is available, extract the main thesis, few key points, and conclusion.
3. Structure the output as a TL;DR, key points, and a bottom line.

In the frontmatter block, we define the name and description of our skill. The description is especially important as the agent uses it to determine whether this skill is relevant for a given user request. Next, we define the instructions that tells the agent exactly what steps to follow when the skill is invoked, including which script to run and how to structure the final output.

Next, let’s create the fetch_article.py script inside a new scripts subdirectory that we reference in the instructions:

ARTICLE = """
... hardcoding sample article for demonstration
"""

print(ARTICLE)

Here, for our demonstration, we simply print a hardcoded article about MCP elicitations instead of actually making a web request. The AI model will run this script and read the standard output to get this article’s content regardless of the URL in the request .

Also, it’s important to note that we can define our scripts in any language of our choice. We just need to make sure that we pre-install the required runtimes for our agent to execute the necessary commands.

5. Creating a Simple Chatbot

With our configurations in place, let’s build a simple chatbot.

In Spring AI, the ChatClient class acts as the main entry point for interacting with our configured chat completion model. Let’s define its bean using the auto-configured ChatModel bean:

@Bean
ChatClient chatClient(ChatModel chatModel) {
    String skillsRootDirectory = ".openai/skills";
    return ChatClient
      .builder(chatModel)
      .defaultTools(
        SkillsTool.builder()
          .addSkillsDirectory(skillsRootDirectory)
          .build(),
        FileSystemTools.builder()
          .allowedDirectory(skillsRootDirectory)
          .build(),
        ShellTools.builder()
          .build()
      ).build();
}

In our bean definition, we first register our custom skills directory using SkillsTool, pointing it to the .openai/skills directory.

Secondly, we register FileSystemTools, which gives the agent the ability to read and write any files on the local filesystem. To restrict the tool’s operations to the configured skills directory, we use the allowedDirectory() method.

Finally, we register ShellTools, which allows the agent to execute shell commands, enabling it to run the Python script we’ve defined.

However, it’s important to note that ShellTools executes our scripts directly on the local machine without sandboxing. As such, we should carefully review the scripts we expose to our agent and consider containerizing our application to limit potential exposure.

Next, let’s inject the ChatClient bean in a controller class and expose a REST API:

@PostMapping("/chat")
ResponseEntity<ChatbotResponse> chat(@RequestBody ChatbotRequest chatbotRequest) {
    String answer = chatClient
      .prompt()
      .user(chatbotRequest.question)
      .call()
      .content();
    return ResponseEntity.ok(new ChatbotResponse(answer));
}

record ChatbotRequest(String question) {}

record ChatbotResponse(String answer) {}

Here, we simply pass the user’s question to the chatClient instance and return the LLM’s response. We’ll use this API endpoint to interact with our chatbot in the upcoming section.

6. Interacting With Our Chatbot

Now that we’ve built our implementation, let’s interact with our chatbot and test the agent skill capability.

We’ll use the HTTPie CLI to invoke the chatbot’s API endpoint:

http POST :8080/chat question="Can you summarize the following article: https://www.baeldung.com/sample-non-existing-article"

Here, we ask the chatbot to summarize a specific article by passing a URL in the question. We deliberately provide the URL of a non-existent article to verify that the chatbot summarizes the article we’ve hardcoded in our Python script.

Let’s see what we get as a response:

{
  "answer": "## TL;DR\nThis article explains how to implement MCP Elicitations in Spring AI, allowing MCP servers to request additional user information dynamically during tool execution.
    \n\n## Key Points\n- MCP Elicitations solve the problem of missing user information during MCP tool execution.
    \n- The tutorial demonstrates building an MCP server using Spring AI.
    \n- The MCP server exposes a tool that fetches author details and conditionally requests additional information.
    \n- The `elicit()` method is used to pause execution and gather required details from the user.
    \n- The article also demonstrates configuring an MCP client and integrating it with an Anthropic Claude model
    \n- Spring AI automatically creates MCP clients and tool callback providers from configuration.
    \n- An `@McpElicitation` handler is used on the client side to respond to elicitation requests.
    \n- The tutorial concludes with a working chatbot example and log outputs showing the complete elicitation flow.
    \n\n## Bottom Line\nMCP Elicitations enable interactive AI applications where tools can dynamically collect additional context from users during execution,
    making MCP-based systems more flexible and user-aware."
}

As we can see, the LLM summarizes our hardcoded article and the response is structured exactly as our skill’s instructions prescribed, with a TL;DR, a set of key points, and a bottom line.

Behind the scenes, the agent matched the user’s request to the article-summarizer skill based on its description, loaded the instructions into context using FileSystemTools, executed the fetch_article.py script via ShellTools to retrieve the article content, and then structured the response following the instructions in our SKILL.md file.

7. Conclusion

In this article, we’ve explored the concept of Agent Skills using Spring AI.

We started by understanding what Agent Skills are and how they help us in exposing reusable capabilities to an AI agent.

Then, we defined a custom article summarizer skill and wired it into a chatbot. Finally, we interacted with our chatbot to confirm that it correctly discovers and invokes our skill.

As always, all the code examples used in this article are available over on GitHub.