Spring AI Recipe: Guiding Agent Behavior with Skills

When building AI-powered applications, it’s not just about what an LLM can do — it’s about how it behaves.

LLMs are excellent at answering questions, but their responses can be:

• inconsistent
• overly generic
• lacking domain-specific nuance

What if you could guide how the agent behaves without hardcoding logic?

This is where Agent Skills come in.

NOTE: This recipe has been updated since it’s original publication to reflect changes in Spring AI 2.0.0.

What are Agent Skills?

Agent Skills provide procedural memory — domain-specific guidance that shapes how an agent responds.

Unlike tools, which enable actions, skills influence:

• how answers are formed
• how tools are used
• how domain knowledge is expressed

Adding the dependency

Spring AI Agent Utils provides support for skills:

implementation 'org.springaicommunity:spring-ai-agent-utils:0.7.0'

Defining a skill

In its simplest form, a skill is a Markdown file that provides instructions.

Create the following file at src/main/resources/.agent/skills/weather/SKILL.md:

---
name: weather-assistant
description: Provides weather information and suggestions
---

When asked for the current weather for a location, use the
get-weather-for-zipcode tool. If there are multiple zipcodes,
choose a default zipcode.
Follow the weather conditions with a statement specific to the
location.
- Miami, FL → "Locals are in light jackets…"
- San Diego, CA → "La Jolla seals are lounging…"
- New York, NY → "Central Park is packed…"
- Austin, TX → "Perfect patio weather…"
- Anaheim, CA → "A perfect day to visit Disneyland!"

This defines:

• how the agent should retrieve weather
• how it should present the result
• how to inject location-specific flavor

Configuring skills

Point Spring AI to the skill location:

agent.skills.resources=classpath:/.agent/skills

Then wire the skills into the ChatClient:

@Value("${agent.skills.resources}")
List<Resource> skillResources;

@Bean
ChatClientBuilderCustomizer addSkills() {
  return builder -> builder
      .defaultSystem(
          "IMPORTANT: Always use the available skills to assist the user..."
      )
      .defaultToolCallbacks(
          SkillsTool.builder()
              .addSkillsResources(skillResources)
              .build()
      );
}

The system message reinforces that skills should be used when applicable.

Adding a supporting tool

The skill references a tool for retrieving weather, so define it:

@Service
public class WeatherTools {
  @Tool(name = "get-weather-for-zipcode",
        description = "Gets the current weather for a given zipcode")
  public Weather getWeatherForZipcode(String zipcode) {
    return new Weather(zipcode, "Sunny", "78F");
  }
}

And the corresponding Weather record:

public record Weather(
    String zipcode,
    String conditions,
    String temperature) {}

Then register it with ChatClient using a ChatClientBuilderCustomizer :

@Bean
ChatClientBuilderCustomizer addTools(WeatherTools weatherTools) {
  return builder -> builder.defaultTools(weatherTools);
}

Trying it out

Ask:

> What is the current weather in New York, NY?

You’ll get:

• structured weather data
• plus a location-aware narrative

Example:

Current weather in New York, NY (zipcode 10001):
- Conditions: Sunny
- Temperature: 78F

Central Park is packed, iced coffees are mandatory, and someone's loudly arguing about rent on the subway.

Why this matters

Traditional applications:

• rely on hardcoded logic

LLM-based applications:

• rely on probabilistic reasoning

Agentic applications:

• combine both with guided behavior

Skills allow you to:

• inject domain-specific guidance
• influence behavior without rigid rules
• keep logic flexible and reusable

A key building block for agents

If agents are:

LLMs with tools in a loop to achieve a goal

Then:

• tools provide capability
• memory provides continuity
• skills provide direction

Takeaway

Agent Skills let you shape how your agent behaves — without writing imperative logic.

They are one of the simplest and most powerful ways to make your applications feel intentional, consistent, and domain-aware.

What’s next

In the next recipe, we’ll look at how to package and reuse skills across applications with prebuilt skill sets.