How to Build and Use Spring AI Agent Skills in Spring Boot 3

1. Introduction to Agent Skills

Agent Skills are modular capabilities packaged as a folder containing a SKILL.md file written in Markdown with a YAML header. The header can hold simple strings or complex structures (lists, nested objects). Each skill may also include optional scripts, templates, and reference materials.

Typical folder layout:

my-skill/
├── SKILL.md      # Required: description and metadata
├── scripts/       # Optional: executable scripts
├── references/   # Optional: documentation
└── assets/       # Optional: template resources

Core SKILL.md structure:

---
name: skill-name
description: Clear description of the skill and its use case
---
# Skill Title
[Instructions executed when the skill is invoked]
## Examples
- Example usage 1
- Example usage 2
## Guidelines
- Guideline 1
- Guideline 2

Example – a code‑reviewer skill that checks Java code for best practices, security issues, and Spring conventions.

---
name: 代码审查
description: 审查 Java 代码是否符合最佳实践、是否存在安全问题，以及是否遵循 Spring Framework 的规范。当用户请求审查、分析或审计代码时使用。
---
# 代码审查
## 使用说明
在审查代码时，请执行以下操作 :
- 检查安全漏洞（如 SQL 注入、XSS 等）
- 验证是否遵循 Spring Boot 最佳实践（如正确使用 @Service、@Repository 等注解）
- 查找潜在的空指针异常（NullPointerException）
- 提出可读性和可维护性方面的改进建议
- 提供逐行的具体反馈，并附上代码示例

2. Why Use Agent Skills?

Inject domain expertise and standards: Package team‑specific best practices, coding standards, or proprietary workflows so the LLM can act like an experienced employee.

Optimize context management: Skills are loaded on demand, preventing context bloat and saving resources.

Increase task determinism: Complex logic can be delegated to Python or Bash scripts, reducing AI‑generated errors.

Provide “hands‑and‑feet” for the AI brain: Structured files tell the model what to do and how to do it, enabling multi‑step autonomous work.

3. Practical Spring AI Example

3.1 Add Maven Dependencies

<dependency>
  <groupId>com.alibaba.cloud.ai</groupId>
  <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
  <version>1.1.2.0</version>
</dependency>
<dependency>
  <groupId>org.springaicommunity</groupId>
  <artifactId>spring-ai-agent-utils</artifactId>
  <version>0.4.1</version>
</dependency>

3.2 Configuration (application.yml)

spring:
  ai:
    dashscope:
      api-key: sk-xxxooo
      base-url: https://dashscope.aliyuncs.com
      chat:
        options:
          stream: true
          model: qwen-turbo
          temperature: 0.1

3.3 Define a Skill

Create a folder d:/agents/skills/code-reviewer containing the SKILL.md shown above. The directory structure is illustrated below:

3.4 Register the Skill Tool

@RestController
@RequestMapping("/skill")
public class SkillController {
  private final ChatClient chatClient;

  public SkillController(ChatClient.Builder chatClientBuilder) {
    this.chatClient = chatClientBuilder
        .defaultAdvisors(new SimpleLoggerAdvisor())
        .defaultToolCallbacks(SkillsTool.builder()
            // Register the skill directory
            .addSkillsResource(new FileSystemResource("d:/agents/skills"))
            .build())
        .defaultTools(FileSystemTools.builder().build())
        .defaultTools(ShellTools.builder().build())
        .build();
  }

  @GetMapping(produces = {"text/html;charset=utf-8"})
  public String chat() {
    return this.chatClient.prompt()
        // Prompt format: "Review the following class ... write result to ..."
        .user("审查以下类是否符合最佳实践: %s。最终文件写入: %s"
            .formatted(
                "D:\\java\\spring-boot-ai_agents\\src\\main\\java\\com\\pack\\ApiController.java",
                "D:\\result.md"))
        .call()
        .content();
  }
}

3.5 Example API Controller

@RestController
@RequestMapping("/api")
public class ApiController {
  private final RestClient restClient;

  public ApiController(RestClient restClient) {
    this.restClient = restClient;
  }

  @GetMapping("/query")
  public ResponseEntity<?> query() {
    Object body = this.restClient.get()
        .uri(URI.create("http://localhost:8080/api/search"))
        .retrieve()
        .body(Map.class);
    return ResponseEntity.ok(body);
  }

  @GetMapping("/search")
  public ResponseEntity<?> search() throws Exception {
    TimeUnit.SECONDS.sleep(3);
    return ResponseEntity.ok(Map.of("code", 0, "message", "success"));
  }
}

3.6 Run and Verify

Access /skill endpoint (see screenshot) to trigger the code‑review skill. Console logs show the AI’s response and the generated result.md file.

3.7 Common Pitfall and Fix

If the following exception appears:

throw new IllegalArgumentException("ToolContext is required by the method as an argument");

Modify org.springframework.ai.tool.method.MethodToolCallback to skip the context validation (as shown in the screenshot).

4. Summary

The article demonstrates how to package reusable AI capabilities as Agent Skills, define them with markdown metadata, and integrate them into a Spring Boot 3 application using Spring AI. By adding the required dependencies, configuring the AI provider, registering the skill directory, and exposing a controller endpoint, developers can let large language models perform concrete, deterministic tasks such as Java code review while leveraging custom scripts for complex logic.