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
      chat:
        options:
          model: deepseek-chat # 替换为你使用的模型名称

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

技能定义

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

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

SKILL.md 至少应包含元信息和详细说明文档：

---
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 并通过 DI 注入，利用 SkillsTool 注册技能功能。

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

    public SkillController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .defaultToolCallbacks(SkillsTool.builder()
                        .addSkillsDirectory(".claude/skills")
                        // 也可以使用下面这个
                        // .addSkillsResource(resourceLoader.getResource("classpath:.claude/skills"))
                        .build())
                .defaultTools(FileSystemTools.builder().build())
                .defaultTools(ShellTools.builder().build())
                .defaultToolContext(Map.of("foo", "bar"))
                .build();
    }

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

此时运行程序，访问对应端口即可查看返回内容。

关键点说明

1. 工具包组装：通过 .defaultToolCallbacks(...) 给 ChatClient 传入已组装好的工具包（包含代码逻辑 + JSON Schema 描述），此处即为注册 Skill 功能。
2. 系统工具注册：.defaultTools() 用于注册对应的系统工具名称，支持动态发现 Skill 进行使用。
3. 上下文处理：.defaultToolContext(Map.of("foo", "bar")) 添加工具上下文。这是为了避免框架报错，需传入 Map 作为 ToolContext，否则无法正常 Build，属于框架当前版本的必要配置。
4. 请求构建：通过链条 .user(message).call().content() 完成 LLM 请求加载、发送及内容获取。

源码分析

目录设置与加载

SkillsTool 的 Builder 模式支持添加多个技能路径：

public static class Builder {
    // ... 省略部分代码
    public Builder addSkillsResources(List<Resource> skillsRootPaths) { /* ... */ }
    public Builder addSkillsDirectory(String skillsRootDirectory) { /* ... */ }
    // ... 省略部分代码
}

其中 toolDescriptionTemplate 用于定义技能描述的模板格式。

元数据解析

加载器会递归查找指定文件夹中的 SKILL.md 文件：

private static List<Skill> skills(String rootDirectory) throws IOException {
    Path rootPath = Paths.get(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 头)：包含技能名字和描述，告诉 AI'我有这个技能'。
• Content (正文)：具体的 Prompt 指令，例如'处理 PDF 的步骤是：1. 转换文本… 2. 提取摘要…'。

工具注册与调用

扫描到的技能列表会被编织进工具的描述中：

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 决定调用 Skill("pdf") 时，触发以下逻辑：

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 调用对应的说明或脚本资源。