Spring AI Alibaba 中的 Skills（技能）到底是个啥？（通俗易懂汇总版）

💡 核心结论：一句话先记住

如果说给 Agent 塞 System Prompt 是让大模型“死记硬背”，那么 Skills（技能）就是给 Agent 提供了一个“随身图书馆”。Agent 遇到什么类型的任务，就去翻对应的那本“技能书”（指令与上下文包），按需学习，绝不占脑容量！

---

🛑 核心概念：渐进式披露（Progressive Disclosure）

• 大白话：大模型也有“内存焦虑”。 如果你要在系统里给 AI 配置 50 个不同的专家能力（算账、写周报、查库等），一次性把这 50 个操作规范全塞进提示词（Prompt）里，会导致 Token 爆表，不仅特别烧钱，大模型还会犯迷糊抓不住重点。

• Skills 的绝招：只看目录，按需加载。

  一开始，系统只把“技能目录”（名字、简介）给大模型看。当大模型在聊天中判断：“哦，用户让我算账！”它就会自动调用一个内置的 read_skill(skill_name) 工具。这个工具会立刻把关于“怎么算账”的详细步骤、规范说明加载到当前对话上下文里。这就叫渐进式披露。

---

📁 Skill 目录结构与规范（技能库怎么建？）

在项目里，技能不能乱塞，必须像文件夹一样规规矩矩地整理好。每个技能必须是一个独立的文件夹，且里面必须要有一个 SKILL.md。

标准目录结构长这样：

Plaintext

skill-name/               # 这是你给技能起的名字（比如 text-fee-agent）
├── SKILL.md              # ⭐ 必需：这本技能书的核心！里面用 Markdown 写清楚第一步干嘛，第二步干嘛，输出什么格式。
├── references/           # 可选：参考资料库（比如公司的员工手册 pdf，丢里面）
├── examples/             # 可选：给大模型抄的满分作业示例
└── scripts/              # 可选：附带的执行脚本

---

🛠️ 在 Agent 中如何配置和使用 Skills？（抄作业区）

在 Spring AI Alibaba 中，我们通过 SkillRegistry（技能注册中心）来加载技能，并通过 SkillsAgentHook（技能钩子）把它挂载到智能体身上。

官方支持两种主流加载方式：

方式一：Classpath 资源加载（最常用，适合打包部署 ⭐⭐⭐⭐⭐）

• 大白话： 把上面的技能文件夹，直接丢到你 Spring Boot 项目的 src/main/resources/skills/ 目录下。项目启动时自动读取。
• 💻 代码展示：

import com.alibaba.cloud.ai.agent.hook.SkillsAgentHook;
import com.alibaba.cloud.ai.agent.skill.ClasspathSkillRegistry;
import com.alibaba.cloud.ai.agent.skill.SkillRegistry;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;

// 1. 告诉注册中心，去 resources 的 skills 目录下扫货
SkillRegistry cpRegistry = new ClasspathSkillRegistry("skills/");

// 2. 把注册中心包装成一个 Hook（钩子）
SkillsAgentHook skillsHook = new SkillsAgentHook(cpRegistry);

// 3. 把这个 Hook 挂载到你的 Agent 身上，大功告成！
ReactAgent agent = ReactAgent.builder()
        .chatModel(chatModel)
        .hooks(skillsHook) // ⭐ 注入灵魂
        .build();

方式二：FileSystem 本地硬盘加载（适合动态修改、热更新 ⭐⭐⭐⭐）

• 大白话： 如果你的技能文档是由非研发人员（比如产品经理）天天在服务器的某个磁盘目录里修改的，不想每次改完都重新发版，就选这个。读取本地绝对路径。
• 💻 代码展示：

import com.alibaba.cloud.ai.agent.hook.SkillsAgentHook;
import com.alibaba.cloud.ai.agent.skill.FileSystemSkillRegistry;
import com.alibaba.cloud.ai.agent.skill.SkillRegistry;
import com.alibaba.cloud.ai.graph.agent.ReactAgent;

// 1. 指定服务器硬盘上的绝对路径
SkillRegistry fileRegistry = new FileSystemSkillRegistry("/data/ai_skills_dir/");

// 2. 包装成 Hook 并挂载
SkillsAgentHook skillsHook = new SkillsAgentHook(fileRegistry);

ReactAgent agent = ReactAgent.builder()
        .chatModel(chatModel)
        .hooks(skillsHook) 
        .build();

---

🚀 高级用法与全家桶生态

除了上面最基础的“按需看文档”，Skills 还有几个非常硬核的进阶玩法：

1. 渐进式工具披露（Tool 披露）

• 大白话： 不仅动态给“知识”，还能动态给“工具”！当大模型调用 read_skill 激活某个技能时，系统不仅把 SKILL.md 塞给它，连带着把和这个技能绑定的 Java 方法（Tools）也一并加载给它。不用这个技能时，工具也藏着不露，防干扰极佳。

2. 在 Graph（图工作流）中使用

• 大白话： 如果你的系统特别庞大，是通过多个节点连接组成的“工作流”。你可以使用 ChatClient 配合 SkillPromptAugmentor，在工作流流转到某个特定节点时，硬核地把某个特定技能给注入进去，实现超复杂的业务编排。

3. 生产环境配置与最佳实践

• 大白话： 官方建议，为了保证模型在生产环境又快又准，写 SKILL.md 时一定要条理清晰（善用 Markdown 的一二三级标题），把格式规范（比如必须返回 JSON）在这个文件里死死拿捏住。

---

🎯 终极秒记口诀

提示词太长易翻车，Token 爆表真头壳；

用好 Skills 技能包，按需加载最洒脱！

目录规范建个档，Registry 里扫一波；

渐进披露防智障，Agent 变身老大哥！