Spring AI Agent Skills 接入实战与原理分析

注：实测 Spring Boot 3.5.10、JDK 17 配合 Spring AI 1.1.2 也能运行，但建议以官方推荐版本为准。

配置文件

server:
  port: 8080
spring:
  application:
    name: pocketmind-server
  ai:
    chat:
      client:
        observations:
          log-prompt: true
          log-completion: true
        openai:
          api-key: xxxx # 替换为你的 API Key
          base-url: xxxx # 替换为你的 Base URL，不需要 /v1
      options:
        model: deepseek-chat # 替换为你使用的模型名称

示例采用 OpenAI 兼容的 API，如需支持 Anthropic，请参照对应文档切换配置。

定义 Skill

在根目录下创建对应的 skill 目录，结构如下：

my-skill/
├── SKILL.md       # Required: instructions + metadata
├── scripts/       # Optional: executable code
├── references/    # Optional: documentation
└── assets/        # Optional: templates, resources

SKILL.md 文件必须包含元信息（Front Matter）和详细的说明文档。至少需要定义技能名称和描述：

---
name: code-reviewer
description: Reviews Java code for best practices, security issues, and Spring Framework conventions. Use when user asks to review, analyze, or audit code
---
# Code Reviewer

## Instructions
When reviewing code:
1. Check **for** security vulnerabilities (SQL injection, XSS, etc.)
2. Verify Spring Boot best practices (proper use of @Service, @Repository, etc.)
3. Look **for** potential null pointer exceptions
4. Suggest improvements **for** readability and maintainability
5. Provide specific line-by-line feedback with code examples

代码实现

在 Controller 中注入 ChatClient 并注册 Skills 工具：

import org.springaicommunity.agent.tools.FileSystemTools;
import org.springaicommunity.agent.tools.ShellTools;
import org.springaicommunity.agent.tools.SkillsTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.*;
import java.util.Map;

@RestController
@RequestMapping("/demo")
public class SkillController {

    private final ChatClient chatClient;

    public SkillController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .defaultToolCallbacks(SkillsTool.builder()
                        .addSkillsDirectory(".claude/skills") // 也可以加载 classpath 资源
                        // .addSkillsResource(resourceLoader.getResource("classpath:.claude/skills"))
                        .build())
                .defaultTools(FileSystemTools.builder().build())
                .defaultTools(ShellTools.builder().build())
                .defaultToolContext(Map.of("foo", "bar")) // 防止框架报错，需传入 ToolContext
                .build();
    }

    /**
     * 测试 skill 流程
     */
    @PostMapping("/skill")
    public String chat(@RequestBody String message) {
        return chatClient.prompt()
                .user(message)
                .call()
                .content();
    }
}

运行程序后访问对应端口即可测试。这里有几个关键点需要注意：

1. DI 注入：通过构造函数注入 ChatClient.Builder，利用 Builder 模式灵活配置。
2. 工具注册：
   • .defaultToolCallbacks(...)：这是核心，将组装好的工具包（含逻辑 + JSON Schema）注册给 ChatClient，用于启用 Skill 功能。
   • .defaultTools()：注册系统级工具，如文件系统操作，辅助动态发现和使用 Skill。
   • .defaultToolContext(...)：这是一个必要的上下文参数，虽然看似多余，但当前框架版本下不传入可能导致构建失败，属于框架层面的限制。
3. 请求构建：使用链式调用 .user(message).call().content() 完成 LLM 的请求发送与内容获取。

源码深度解析

理解底层机制有助于排查问题。我们来看看 SkillsTool 是如何工作的。

目录扫描与加载

首先，框架会递归查找指定目录下的 SKILL.md 文件：

private static List<Skill> skills(String rootDirectory) throws IOException {
    Path rootPath = Paths.get(rootDirectory);
    if (!Files.exists(rootPath)) {
        throw new IOException("Root directory does not exist: " + rootDirectory);
    }
    // ... 省略部分检查代码
    List<Skill> skillFiles = new ArrayList<>();
    try (Stream<Path> paths = Files.walk(rootPath)) {
        paths.filter(Files::isRegularFile)
             .filter(path -> path.getFileName().toString().equals("SKILL.md"))
             .forEach(path -> {
                 try {
                     String markdown = Files.readString(path, StandardCharsets.UTF_8);
                     MarkdownParser parser = new MarkdownParser(markdown);
                     skillFiles.add(new Skill(path, parser.getFrontMatter(), parser.getContent()));
                 } catch (IOException e) {
                     throw new RuntimeException("Failed to read SKILL.md file: " + path, e);
                 }
             });
    }
    return skillFiles;
}

这里主要做了两件事：

• FrontMatter (YAML 头)：提取技能名称（如 name: pdf）和描述，这部分会被告诉 AI'我有这个技能'。
• Content (正文)：具体的 Prompt 指令，例如处理 PDF 的步骤。

工具回调构建

加载完所有技能后，框架会将它们编织进工具的描述中：

public ToolCallback build() {
    Assert.notEmpty(this.skills, "At least one skill must be configured");
    String skillsXml = this.skills.stream()
            .map(s -> s.toXml())
            .collect(Collectors.joining("\n"));
    return FunctionToolCallback.builder("Skill", new SkillsFunction(toSkillsMap(this.skills)))
            .description(this.toolDescriptionTemplate.formatted(skillsXml))
            .inputType(SkillsInput.class)
            .build();
}

当 AI 看到该工具时，Prompt 中会包含你定义的 Skill 列表，例如：

• <skill><name>pdf</name><description>Extract text from PDF</description></skill>
• <skill><name>git</name><description>Git version control</description></skill>

技能执行

当 AI 决定调用 Skill("pdf") 时，触发以下逻辑：

public static class SkillsFunction implements Function<SkillsInput, String> {
    private Map<String, Skill> skillsMap;

    public SkillsFunction(Map<String, Skill> skillsMap) {
        this.skillsMap = skillsMap;
    }

    @Override
    public String apply(SkillsInput input) {
        Skill skill = this.skillsMap.get(input.command());
        if (skill != null) {
            var skillBaseDirectory = skill.path().getParent().toString();
            return "Base directory for this skill: %s\n\n%s".formatted(skillBaseDirectory, skill.content());
        }
        return "Skill not found: " + input.command();
    }
}

此时返回的是'路径'和'正文内容'，AI 读取这些文字后，就能将其作为操作指南来执行后续任务。至此，Skill 的完整生命周期已闭环，AI 可根据返回的 SKILL.md 内容调用相应的说明或脚本。

如果读者对 Spring AI 框架下 AI 如何进行多次工具调用循环感兴趣，可参考相关技术文档进行深入学习。