从零掌握 Spring AI Alibaba Skill：定义、注册与渐进式披露

Spring AI Alibaba Skill 注册机制详解与实战指南

1. 引言

在构建基于大语言模型的智能 Agent 应用时，如何有效地管理和组织 Agent 的能力是一个关键挑战。Spring AI Alibaba 提供了一套完整的 Skill（技能）注册和使用机制，使得我们可以模块化地管理 Agent 的各种能力，并支持渐进式的能力披露。本文将深入解析这套机制的原理和实际使用方法。

你将学到什么

Spring AI Alibaba 中 Skill 的概念和作用
如何定义和注册 Skill
SkillsAgentHook 的工作原理
如何将工具与 Skill 绑定实现渐进式披露
实际项目中的最佳实践

2. 核心概念解析

2.1 什么是 Skill？

在 Spring AI Alibaba 的语境中，**Skill（技能）**是指 Agent 可以执行的特定任务或能力的封装。一个 Skill 通常包含：

技能描述文件（SKILL.md）：定义技能的名称、描述、适用场景等元信息
执行逻辑：具体的业务实现代码
工具集合：技能执行过程中可能用到的工具（可选）

2.2 为什么需要 Skill 注册机制？

传统的 Agent 实现方式往往将所有工具和能力一次性暴露给大模型，这会导致：

Token 浪费：大量工具描述占用上下文窗口
决策困难：过多的选择可能让模型难以做出最优决策
维护困难：缺乏模块化的组织结构

通过 Skill 注册机制，我们可以实现：

✅ 按需加载：只在需要时才暴露具体工具
✅ 模块化管理：每个 Skill 独立维护和测试
✅ 渐进式披露：根据对话进展逐步展示能力

3. 项目结构说明

让我们通过一个实际项目来理解 Skill 的使用：

复制代码

L03-skill-creator/
├── src/main/
│   ├── java/com/git/hui/springai/ali/
│   │   └── L03Application.java          # 主应用程序
│   └── resources/
│       ├── skills/                       # 技能定义目录
│       │   ├── blog_creator/
│       │   │   └── SKILL.md             # 博客创作技能定义
│       │   └── modern_poetry/
│       │       └── SKILL.md             # 现代诗创作技能定义
│       └── application.yml               # 应用配置
└── pom.xml                               # Maven 依赖配置

4. 技能定义文件详解

4.1 SKILL.md 文件结构

每个技能都需要一个 SKILL.md 文件来定义其元数据。以 modern_poetry 为例：

markdown 复制代码

---
name: modern_poetry
description: 创作优美的现代诗歌。使用富有想象力的语言，表达情感、意境和哲思。
allowed-tools: [Read, Write, Shell]
tags: [poetry, creative-writing, literature, art]
platforms: [Claude, ChatGPT, Gemini]
---

# 现代诗创作技能

## 何时使用此技能
- 表达个人情感和内心体验
- 描绘自然景物和生活片段
- 探索哲理和人生思考
...

4.2 关键字段说明

字段	说明	示例
`name`	技能的唯一标识符	`modern_poetry`
`description`	技能的详细描述	"创作优美的现代诗歌..."
`allowed-tools`	允许使用的工具列表	`[Read, Write, Shell]`
`tags`	技能标签，便于分类检索	`[poetry, creative-writing]`

5. 技能注册与使用

5.1 基础配置

首先配置必要的依赖：

xml 复制代码

<dependencies>
    <!-- Spring AI OpenAI Starter -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
    
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

5.2 应用配置

在 application.yml 中配置模型信息：

yaml 复制代码

spring:
  ai:
    openai:
      api-key: ${silicon-api-key}
      chat:
        options:
          model: Qwen/Qwen2.5-7B-Instruct
      base-url: https://api.siliconflow.cn

5.3 技能注册代码实现

步骤一：创建 SkillRegistry

java 复制代码

@Bean
CommandLineRunner commandLineRunner(ChatModel chatModel) throws IOException {
    return args -> {
        // 使用 ClasspathSkillRegistry 从 classpath 的 skills 目录加载技能
        SkillRegistry registry = ClasspathSkillRegistry.builder()
                .classpathPath("skills")
                .build();
        
        // 也可以使用 FileSystemSkillRegistry 从文件系统加载
        // SkillRegistry registry = FileSystemSkillRegistry.builder()
        //         .projectSkillsDirectory("/path/to/skills")
        //         .build();
    };
}

说明：

ClasspathSkillRegistry：适合打包在 JAR 中的技能
FileSystemSkillRegistry：适合动态添加/修改的技能场景

步骤二：创建 SkillsAgentHook

java 复制代码

// 创建 SkillsAgentHook，注册 read_skill 工具
SkillsAgentHook hook = SkillsAgentHook.builder()
        .skillRegistry(registry)
        .build();

工作原理：

SkillsAgentHook 会自动向 Agent 注册一个 read_skill 工具
该工具会将所有可用技能的元数据（名称、描述）注入到系统提示中
当模型调用 read_skill(skill_name) 时，会返回对应技能的完整内容
技能被激活后，其关联的工具也会在后续对话中可用

步骤三：添加其他工具 Hook

如果技能需要执行 shell 命令或其他操作，需要注册相应的工具：

java 复制代码

// Shell Hook：提供 Shell 命令执行能力
ShellToolAgentHook shellHook = ShellToolAgentHook.builder()
        .shellTool2(ShellTool2.builder(System.getProperty("user.dir")).build())
        .build();

// 如果需要 Python 脚本支持
// ToolCallback pythonTool = PythonTool.createPythonToolCallback(PythonTool.DESCRIPTION);

步骤四：构建 ReactAgent

java 复制代码

// 创建网络获取工具（可选，用于从网络搜索素材）
var webFetchTool = WebFetchTool.builder(ChatClient.builder(chatModel).build())
        .withName("web-fetcher")
        .withDescription("这是一个网络查询的工具，当你需要从网络上进行搜索相关信息时，使用这个工具")
        .build();

// 构建 Agent
ReactAgent agent = ReactAgent.builder()
        .name("skills-agent")
        .model(chatModel)
        .systemPrompt("""
            你是一个专业的协作助手，当需要进行创作、写文章、写诗歌，
            你可以通过 read_skill 工具来获取技能
            """)
        .enableLogging(true)
        .saver(new MemorySaver())  // 启用记忆保存
        .tools(webFetchTool)        // 注册全局工具
        .hooks(List.of(hook, shellHook))  // 注册 Hook
        .build();

步骤五：调用 Agent 执行任务

java 复制代码

// 场景 1：创作诗歌
AssistantMessage msg = agent.call("帮我写一首关于爱情的诗");
System.out.println(msg.getText());

// 场景 2：结合网络搜索创作博文
AssistantMessage msg = agent.call("""
    帮我写一篇关于 ReAct 原理的介绍文章
    在开始之前，请先使用 web-fetcher 从 
    https://www.ppai.top/ai-guides/tutorial/hello-agent/03.Agent%E6%80%9D%E8%80%83%E6%A1%86%E6%9E%B6-ReAct.html 
    中搜索相关的素材作为博文的准备材料
    """);
System.out.println(msg.getText());

6. 进阶用法：工具与技能绑定

6.1 渐进式工具披露

通过将工具与特定 Skill 绑定，可以实现更精细的控制：

java 复制代码

Map<String, List<ToolCallback>> groupedTools = Map.of(
    "technical-writing",  // 与 SKILL.md 的 name 一致
    List.of(webFetchTool)
);

SkillsAgentHook hook = SkillsAgentHook.builder()
        .skillRegistry(registry)
        .groupedTools(groupedTools)  // 绑定工具到技能
        .build();

工作流程：

初始状态：只暴露 read_skill 工具和技能列表
模型调用：read_skill("technical-writing")
系统响应：返回 technical-writing 技能的完整描述
工具激活：同时暴露与该技能绑定的 webFetchTool
后续对话：模型可以使用已激活的工具完成写作任务

6.2 优势分析

特性	传统方式	Skill 绑定方式
Token 消耗	所有工具描述	仅激活技能的工具
决策效率	选择过多	聚焦相关工具
可维护性	分散	模块化组织
扩展性	困难	容易

7. 执行流程图解

复制代码

用户请求
   ↓
[ReactAgent]
   ↓
[SkillsAgentHook] ← 注入技能列表到系统提示
   ↓
[LLM 思考]
   ↓
决定调用 read_skill("blog_creator")
   ↓
[SkillsAgentHook] ← 返回技能完整内容
                    激活关联工具
   ↓
[LLM 再次思考] ← 使用技能知识和工具
   ↓
执行工具调用 → [WebFetchTool] 获取素材
   ↓
生成最终结果
   ↓
返回给用户

8. 最佳实践建议

8.1 技能设计原则

单一职责：每个 Skill 专注于一个特定领域
- ✅ 好：blog_creator（博客创作）
- ❌ 差：everything_helper（什么都做）

清晰描述：在 SKILL.md 中明确说明使用场景

markdown 复制代码

## 何时使用此技能
- 撰写技术教程和指南
- 分享项目实战经验
...

合理分组工具：将相关工具绑定到同一技能

java 复制代码

Map.of(
    "data-analysis",
    List.of(pythonTool, chartTool, fileTool)
)

8.2 性能优化

使用 MemorySaver：保持对话上下文
java 复制代码
```
.saver(new MemorySaver())
```
启用日志：便于调试和监控
java 复制代码
```
.enableLogging(true)
```

合理设置模型：根据任务复杂度选择

yaml 复制代码

# 简单任务：使用较小模型
model: Qwen/Qwen2.5-7B-Instruct

# 复杂任务：使用更大模型
model: Qwen/Qwen3.5-4B

8.3 安全考虑

限制 Shell 命令范围：

java 复制代码

ShellTool2.builder(System.getProperty("user.dir"))  // 限制在项目目录
    .build()

审查技能内容：确保 SKILL.md 不包含恶意指令

API Key 管理：使用环境变量

yaml 复制代码

api-key: ${silicon-api-key}  # 从环境变量读取

9. 常见问题解答

Q1: 技能文件放在哪里？

A: 有两种方式：

Classpath ：src/main/resources/skills/（打包在 JAR 中）
文件系统：任意目录（支持热更新）

Q2: 如何调试技能调用过程？

A: 启用日志记录：

java 复制代码

.enableLogging(true)

查看控制台输出，了解模型的思考过程和工具调用详情。

Q3: 多个技能之间如何协作？

A: 模型可以依次调用多个技能：

先调用 read_skill("data-analysis") 分析数据
再调用 read_skill("blog_creator") 生成报告

Q4: 如何自定义技能的加载逻辑？

A : 实现自己的 SkillRegistry：

java 复制代码

public class CustomSkillRegistry implements SkillRegistry {
    // 自定义加载逻辑
}

10. 总结

Spring AI Alibaba 的 Skill 注册机制提供了一套优雅的方式来管理和使用 Agent 的能力。通过本文的学习，你应该掌握了：

✅ Skill 的概念和价值
✅ 如何定义和注册 Skill
✅ SkillsAgentHook 的工作原理
✅ 工具与技能绑定的渐进式披露
✅ 实际应用中的最佳实践

下一步学习建议

尝试创建自己的 Skill
实验不同的工具组合
探索更复杂的 Agent 编排模式
参考官方文档了解更多高级特性

参考资料

Spring AI Alibaba 官方文档
$ReAct Agent 思考框架详解\](https://www.ppai.top/ai-guides/tutorial/hello-agent/03.Agent 思考框架-ReAct.html)$

零基础入门：

实战

作者：一灰 https://ppai.top
创建日期 ：2026-03-11
最后更新：2026-03-11