Spring AI 接入 Agent Skill 实战教程 | 极客日志

JavaAIjava

Spring AI 接入 Agent Skill 实战教程

介绍如何在 Spring AI 框架下接入 Agent Skill。内容包括环境依赖配置（Maven）、Skill 文件结构定义（SKILL.md）、Controller 中注册 SkillsTool 的代码实现，以及源码层面的加载与调用机制分析。通过解析 SKILL.md 元数据并生成工具回调，实现大模型对自定义技能的动态发现与执行。

战神发布于 2026/4/6更新于 2026/4/175 浏览

参考文档：Spring AI Agentic Patterns (Part 1): Agent Skills - Modular, Reusable Capabilities

引言

本文聚焦于在 Spring AI 下如何快速接入 Skills，并探究其背后的实现原理。

环境准备

Maven 依赖

根据官方手册，Skill 需要 Spring AI 2.0.0-M2 版本以上。项目 Demo 的依赖配置如下：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.2</version>
    <relativePath/>
</parent>
<properties>
    <java.version>21</java.version>
    <spring-ai.version>2.0.0-M2</spring-ai.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <>
        org.springframework.ai
        spring-ai-starter-model-openai
    
    
    
        org.springaicommunity
        spring-ai-agent-utils
        0.4.2
    


    
        
            org.springframework.ai
            spring-ai-bom
            ${spring-ai.version}
            pom
            import
        
    


    
        spring-milestones
        Spring Milestones
        https://repo.spring.io/milestone

相关免费在线工具

Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。在线工具，Keycode 信息在线工具，online
Escape 与 Native 编解码
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。在线工具，Escape 与 Native 编解码在线工具，online
JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。在线工具，JavaScript / HTML 格式化在线工具，online
JavaScript 压缩与混淆
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。在线工具，JavaScript 压缩与混淆在线工具，online
RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。在线工具，Mermaid 预览与可视化编辑在线工具，online

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

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

---
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

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")
                        // 也可以使用下面这个
                        // .addSkillsResource(resourceLoader.getResource("classpath:.claude/skills"))
                        .build())
                .defaultTools(FileSystemTools.builder().build())
                .defaultTools(ShellTools.builder().build())
                .defaultToolContext(Map.of("foo", "bar"))
                .build();
    }

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

public class SkillsTool {
    // ...
    public static class Builder {
        private List<Skill> skills = new ArrayList<>();
        private String toolDescriptionTemplate = TOOL_DESCRIPTION_TEMPLATE;

        protected Builder() {}

        public Builder toolDescriptionTemplate(String template) {
            this.toolDescriptionTemplate = template;
            return this;
        }

        public Builder addSkillsResources(List<Resource> skillsRootPaths) {
            for (Resource skillsRootPath : skillsRootPaths) {
                this.addSkillsResource(skillsRootPath);
            }
            return this;
        }

        public Builder addSkillsResource(Resource skillsRootPath) {
            try {
                String path = skillsRootPath.getFile().toPath().toAbsolutePath().toString();
                this.addSkillsDirectory(path);
            } catch (IOException ex) {
                throw new RuntimeException("Failed to load skills from directory: " + skillsRootPath, ex);
            }
            return this;
        }

        public Builder addSkillsDirectory(String skillsRootDirectory) {
            this.addSkillsDirectories(List.of(skillsRootDirectory));
            return this;
        }

        public Builder addSkillsDirectories(List<String> skillsRootDirectories) {
            for (String skillsRootDirectory : skillsRootDirectories) {
                try {
                    this.skills.addAll(skills(skillsRootDirectory));
                } catch (IOException ex) {
                    throw new RuntimeException("Failed to load skills from directory: " + skillsRootDirectory, ex);
                }
            }
            return this;
        }
        // ...
    }
    // ...
}

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);
    }
    if (!Files.isDirectory(rootPath)) {
        throw new IOException("Path is not a directory: " + 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;
}

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();
}

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();
    }
}

Spring AI 接入 Agent Skill 实战教程

引言

环境准备

Maven 依赖

更多推荐文章

相关免费在线工具

YML 配置

示例代码

SKILL.md

Controller

代码解释

源码分析

0. 设置目录

1. 加载 Skill 元数据

2. 添加 Skill 技能

3. 调用 Skill

Spring AI 接入 Agent Skill 实战教程

引言

环境准备

Maven 依赖

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具

YML 配置

示例代码

SKILL.md

Controller

代码解释

源码分析

0. 设置目录

1. 加载 Skill 元数据

2. 添加 Skill 技能

3. 调用 Skill