Spring AI + Agent Skills 实战：让Java Agent拥有"即插即用"的专业能力

Agent Skills 已上线超90万个，Python开发者玩得不亦乐乎，Java人只能干看？不，Spring AI 2.x 已经支持了。本文手把手教你用 Spring AI 构建一个带 Skills 的 Code Reviewer，从零到跑通，一步不落。

一、Agent Skills 是什么？为什么 Java 开发者必须关注

简单说：Agent Skills 就是给 AI Agent 安装"专业操作手册"，让 Agent 按照预设流程完成特定任务，而不是每次都从零推理。

类比一下：

• 没有 Skills 的 Agent = 实习生，每次都要手把手教
• 有 Skills 的 Agent = 老员工，照着SOP干就行

为什么 Java 开发者要关注？

1. 效率差距明显：别人写个 Skill 一次，Agent 反复用；你还在写重复的 Prompt
2. 经验可沉淀：团队最佳实践打包成 Skill，新成员自动继承
3. 跨平台通用：同一个 Skill 文件，Claude/Copilot/Spring AI 都能用
4. 市场已爆发：2026年4月，Skill 市场已收录超90万个

二、环境准备

版本要求

组件	版本	说明
Spring AI	2.0.0-M2	Skills 需 2.x 分支
Spring Boot	4.0.1	配合 Spring AI 2.x
JDK	21+	Spring Boot 4.x 硬性要求
大模型	GLM-4.5-Flash	免费，适合体验

Maven 依赖

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.1</version>
</parent>

<properties>
    <spring-ai.version>2.0.0-M2</spring-ai.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Agent Skills 核心依赖 -->
    <dependency>
        <groupId>org.springaicommunity</groupId>
        <artifactId>spring-ai-agent-utils</artifactId>
        <version>0.4.1</version>
    </dependency>
    <!-- 智谱大模型（免费） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-zhipuai</artifactId>
    </dependency>
</dependencies>

配置文件

spring:
  ai:
    zhipuai:
      api-key: ${ZHIPUAI_API_KEY}
      chat:
        options:
          model: GLM-4.5-Flash

三、实战：构建一个 Code Reviewer Agent

3.1 创建 Skill 文件

Skills 的核心就是一个目录 + SKILL.md 文件。创建目录结构：

src/main/resources/.claude/skills/code-reviewer/
└── SKILL.md

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

在审查代码时：

1. 检查是否存在安全漏洞（如SQL注入、XSS等）
2. 验证是否遵循了Spring Boot的最佳实践
3. 查找潜在的空指针异常
4. 提出提高代码可读性和可维护性的建议
5. 提供具体的逐行反馈，并附上代码示例
6. 以中文的方式返回代码评审结果

SKILL.md 三层结构解析：

层级	内容	作用
元数据层	YAML头部（name + description）	决定何时触发该 Skill
指令层	Markdown 正文	定义执行流程和思考链
资源层	scripts/、references/ 目录（可选）	脚本、模板、参考文档

更复杂的 Skill 结构：

my-skill/
├── SKILL.md          # 必须：元数据 + 指令
├── scripts/          # 可选：可执行脚本
│   └── analyze.py
├── references/       # 可选：参考文档
│   └── coding-standards.md
└── assets/           # 可选：模板资源
    └── report-template.md

3.2 核心 Agent 代码

@Service
public class CodeReviewService {

    private final ChatClient chatClient;

    public CodeReviewService(ChatClient.Builder chatClientBuilder,
                             ResourceLoader resourceLoader) {
        // 1. 从 classpath 加载 Skills
        SkillsTool skillsTool = SkillsTool.builder()
                .addSkillsResource(resourceLoader.getResource(
                        "classpath:.claude/skills"))
                .build();

        // 2. 将 Skill 注册为工具回调
        this.chatClient = chatClientBuilder
                .defaultTools(skillsTool)
                .build();
    }

    public String reviewCode(String code) {
        return chatClient.prompt()
                .user("请审查以下Java代码：\n```java\n" + code + "\n```")
                .call()
                .content();
    }
}

关键点：SkillsTool 会将 SKILL.md 的 name 和 description 注册为工具定义。当用户请求与 Skill 的 description 匹配时，大模型会自动调用对应的 Skill 工具，获取完整的 SKILL.md 指令内容，然后按照指令执行审查。这就是"即插即用"的核心——你只负责写 Skill 文件，SkillsTool 负责注册和路由。

3.3 添加交互日志（调试必备）

开发 Agent 时，看清每一轮交互至关重要：

public class LoggingAdvisor implements CallAdvisor, StreamAdvisor {

    private final AtomicInteger round = new AtomicInteger(1);

    @Override
    public String getName() { return "loggingAdvisor"; }

    @Override
    public int getOrder() { return 0; }

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request,
                                          CallAdvisorChain chain) {
        System.out.println("=== 第 " + round.getAndAdd(1) + " 轮 ===");
        System.out.println("USER: " + truncate(request.prompt().getContents(), 300));

        ChatClientResponse response = chain.nextCall(request);
        String output = response.chatResponse().getResult().getOutput().getText();
        System.out.println("ASSISTANT: " + truncate(output, 300));
        return response;
    }

    @Override
    public Flux<ChatClientResponse> adviseStream(ChatClientRequest request,
                                                  StreamAdvisorChain chain) {
        return chain.nextStream(request);
    }

    private static String truncate(String text, int maxLen) {
        if (text == null) return "null";
        return text.length() <= maxLen ? text : text.substring(0, maxLen) + "...";
    }
}

3.4 运行测试

@SpringBootTest
class CodeReviewServiceTest {

    @Autowired
    private CodeReviewService service;

    @Test
    void testReview() {
        String code = """
            @Controller
            public class UserController {
                @Autowired
                private UserRepository userRepo;

                @GetMapping("/user/{id}")
                public User getUser(@PathVariable String id) {
                    return userRepo.findById(id).get();
                }
            }
            """;

        String result = service.reviewCode(code);
        System.out.println(result);
    }
}

预期输出包含：

• @Controller 应改为 @RestController（如果返回JSON）
• @Autowired 字段注入不推荐，应改构造器注入
• .get() 没有空值检查，可能抛 NoSuchElementException
• 缺少异常处理

四、Skill 发现 → 工具调用 → 结果输出完整链路

实际运行中，Agent 的完整工作流：

用户输入代码
    ↓
SkillsTool 将 Skill 的 name + description 注册为工具定义
    ↓
大模型根据工具描述自动匹配，调用 code-reviewer 工具
    ↓
SkillsTool 返回完整 SKILL.md 内容（含审查指令）
    ↓
大模型按 Skill 指令逐步审查代码
    ↓
生成结构化审查报告

关键机制：SkillsTool 在启动时扫描 Skill 目录，将每个 SKILL.md 的 name 和 description（YAML frontmatter）注册为工具定义。大模型看到这些工具描述后，会根据用户请求自动决定调用哪个 Skill 工具，获取完整指令后执行。整个过程对开发者透明——你只需把 Skill 文件放在 .claude/skills/ 目录下。

五、企业级场景：团队经验固化为 Skill

Skill 的最大价值不是个人效率，而是团队知识沉淀。

场景：统一团队代码规范

假设你的团队有这些规范：

• 禁止使用 @Autowired 字段注入
• Controller 方法必须有 @Operation 注解（Springdoc OpenAPI）
• 异常必须用全局异常处理器

把这些规范写成 Skill：

---
name: team-java-standards
description: Review code against team Java coding standards.
  Use for all code review tasks.
---

# Team Java Coding Standards Review

## Instructions

审查代码时，检查以下团队规范：

### 强制规范（违反必须指出）
1. 禁止 @Autowired 字段注入，使用构造器注入
2. Controller 方法必须有 @Operation 注解（Springdoc OpenAPI）
3. 不允许在 Controller 中直接处理异常，使用 @RestControllerAdvice

### 建议规范（违反给出建议）
4. Service 方法建议添加 @Transactional(readOnly=true)
5. DTO 和 Entity 之间必须使用 MapStruct 转换
6. 日志使用 Slf4j，禁止 System.out.println

## Output Format

输出格式：
- 🔴 强制规范违反：(行号) 说明 + 修正代码
- 🟡 建议规范违反：(行号) 说明 + 修正代码
- ✅ 通过项：简要说明

效果：团队每个成员用 Agent 审查代码，都自动遵循同一套规范，新人入职也不需要"口口相传"。

写在最后

Agent Skills 的核心思想很简单：把"怎么做"写下来，Agent 照着做。但它解决了一个真实痛点——AI Agent 的输出不稳定，同样的问题每次回答不同。

有了 Skill，Agent 就有了标准操作流程，输出更稳定、更可控。对于 Java 开发者来说，Spring AI 2.x + agent-utils 让这套体系真正可用。

建议下一步：

1. 从简单的 Reviewer Skill 开始体验
2. 逐步添加 scripts/ 目录，让 Skill 能调用实际工具
3. 把团队规范沉淀成 Skill，在 CI/CD 中集成自动审查

---

本文基于 Spring AI 2.0.0-M2 + spring-ai-agent-utils 0.4.1 实测。Spring AI 2.0 GA 预计本月发布，届时 API 可能有调整。