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 实现方式往往将所有工具和能力一次性暴露给大模型，这会导致：

1. Token 浪费

   ：大量工具描述占用上下文窗口

2. 决策困难

   ：过多的选择可能让模型难以做出最优决策

3. 维护困难

   ：缺乏模块化的组织结构

通过 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 为例：

---name: modern_poetrydescription: 创作优美的现代诗歌。使用富有想象力的语言，表达情感、意境和哲思。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 基础配置

首先配置必要的依赖：

<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 中配置模型信息：

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

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

说明：

• ClasspathSkillRegistry

  ：适合打包在 JAR 中的技能

• FileSystemSkillRegistry

  ：适合动态添加/修改的技能场景

步骤二：创建 SkillsAgentHook

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

工作原理：

1. SkillsAgentHook

   会自动向 Agent 注册一个 read_skill 工具

2. 该工具会将所有可用技能的元数据（名称、描述）注入到系统提示中

3. 当模型调用 read_skill(skill_name) 时，会返回对应技能的完整内容

4. 技能被激活后，其关联的工具也会在后续对话中可用

步骤三：添加其他工具 Hook

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

// Shell Hook：提供 Shell 命令执行能力ShellToolAgentHook shellHook = ShellToolAgentHook.builder()        .shellTool2(ShellTool2.builder(System.getProperty("user.dir")).build())        .build();// 如果需要 Python 脚本支持// ToolCallback pythonTool = PythonTool.createPythonToolCallback(PythonTool.DESCRIPTION);

步骤四：构建 ReactAgent

// 创建网络获取工具（可选，用于从网络搜索素材）varwebFetchTool= WebFetchTool.builder(ChatClient.builder(chatModel).build())        .withName("web-fetcher")        .withDescription("这是一个网络查询的工具，当你需要从网络上进行搜索相关信息时，使用这个工具")        .build();// 构建 AgentReactAgentagent= ReactAgent.builder()        .name("skills-agent")        .model(chatModel)        .systemPrompt("""            你是一个专业的协作助手，当需要进行创作、写文章、写诗歌，            你可以通过 read_skill 工具来获取技能            """)        .enableLogging(true)        .saver(newMemorySaver())  // 启用记忆保存        .tools(webFetchTool)        // 注册全局工具        .hooks(List.of(hook, shellHook))  // 注册 Hook        .build();

步骤五：调用 Agent 执行任务

// 场景 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 绑定，可以实现更精细的控制：

Map<String, List<ToolCallback>> groupedTools = Map.of(    "technical-writing",  // 与 SKILL.md 的 name 一致    List.of(webFetchTool));SkillsAgentHook hook = SkillsAgentHook.builder()        .skillRegistry(registry)        .groupedTools(groupedTools)  // 绑定工具到技能        .build();

工作流程：

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

6.2 优势分析

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

7. 执行流程图解

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

8. 最佳实践建议

8.1 技能设计原则

1. 单一职责：每个 Skill 专注于一个特定领域

• ✅ 好：blog_creator（博客创作）
• ❌ 差：everything_helper（什么都做）

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

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

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

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

8.2 性能优化

1. 使用 MemorySaver：保持对话上下文

   .saver(new MemorySaver())
   

2. 启用日志：便于调试和监控

   .enableLogging(true)
   

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

   # 简单任务：使用较小模型model: Qwen/Qwen2.5-7B-Instruct# 复杂任务：使用更大模型model: Qwen/Qwen3.5-4B
   

8.3 安全考虑

1. 限制 Shell 命令范围：

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

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

3. API Key 管理：使用环境变量

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

9. 常见问题解答

Q1: 技能文件放在哪里？

A: 有两种方式：

• Classpath

  ：src/main/resources/skills/（打包在 JAR 中）

• 文件系统

  ：任意目录（支持热更新）

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

A: 启用日志记录：

.enableLogging(true)

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

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

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

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

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

A: 实现自己的 SkillRegistry：

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

10. 总结

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

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

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】