文章目录
独立于大模型，可在自有环境运行的 Skills。
Agent Skills 是由 指令、脚本和资源构成的模块化文件夹。 AI Agent 可以发现并按需加载 Skills。相较于将知识硬编码到 prompts 中 或者为每个任务开发专用工具，Skills 提供了一种灵活扩展智能体能力的实现方式。
Spring AI 的相关实现将 Agent Skills 引入到了 java 生态，实现了大模型的可移植性 — 只需定义一次 Agent Skills，即可在 OpenAI、Anthropic、Google Gemini 及其他所有得到支持的大模型中复用。
什么是 Agent Skills?
Agent Skills 是模块化的能力，表现为以 yaml 格式封装的 markdown 文件。 每个 Skill 对应一个文件夹，文件夹中需要包含一个 SKILL.md 文件。在 SKILL.md 中至少需要配置 名称 和 描述 两类元数据，同时还包含指导 Agent 完成特定任务的指令。此外 Skills 文件夹中还可以整合脚本(scripts)、模板(templates)和参考文档(references)等内容。 其中的前置元数据不仅支持简单的字符串值，还支持复杂的 yaml 结构（列表和嵌套对象等）以支持高级使用场景。
|
1 2 3 4 5 |
my-skill/ ├── SKILL.md # 必选：指令 + 元数据 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：参考文档 └── assets/ # 可选：模板、各类资源 |
- 发现阶段： Agent 启动时，仅加载所有可用 Skill 的名称和描述，保留能够判断 Skill 相关性的核心信息即可；
- 激活阶段： 当待执行任务与某一 Skill 的描述匹配时，Agent 才会将 Skill 的 SKILL.md 文件中的全部指令加载到上下文中；
- 执行阶段： Agent 按照指令完成任务，并根据具体情况按需加载引用文件或者执行内置代码
通过这个机制，即使注册上百个 Skill ， 也能保证上下文窗口的轻量化，避免资源冗余。
Tips: 关于 Agent Skills 的更多内容可以参考 Skill 官方指南
为什么要在 Spring AI 中使用 Agent Skills
无缝集成
只需要注册少量工具，即可将 Agent Skill 集成到现有 Spring AI 应用中 — 且无需对架构做任何修改。
可移植、独立于模型，无厂商锁定
与绑定特定大模型平台的实现方案不同，Spring AI 的 Agent Skill 可以适配多家大模型服务商，切换模型时无需重写代码或重构 Skill。
可复用、可组合
Skill 可以在不同的项目间共享，与业务代码一起进行版本控制。多个 Skill 可以组合实现复杂工作流，还能通过辅助脚本和参考文档进行功能扩展。同时，Spring AI 的 Skill 还可以无缝兼容已有的 Claude Code Skill。
Spring AI 配套工具
Agent Skill 可与 Spring AI 的其它基于工具的功能完美协同，例如用于高效工具选择的动态工具发现，以及在 Skill 执行过程中捕获大模型推理逻辑的工具参数增强功能。
Spring AI Skill 是怎么工作的
Spring AI 采用基于工具的集成方案，通过实现专属工具，让任意大模型都能触发 Skill 并访问其内置资源。该实现严格遵循 Claude Code 的针对 Skill、Base 脚本和文件读取的工具规范。
核心工具集包含：SkillsTool（必选）、ShellTools（可选）和 FileSystemTools（可选）。其中SkillsTool 提供 Skill 函数以支持 AI 模型按需发现并加载指定 Skill，同时也能与 FileSystemTools（用于读取参考文件）和 ShellTools（用于执行辅助脚本）协同工作。
Skill 的运行分为三个核心阶段：
-
发现阶段（启动时）： 初始化过程中，SkillsTool 会扫描配置好的 Skill 目录（如 .claude/skills/），解析每个 SKILL.md 文件的前置元数据，提取名称和描述字段，构建轻量级的 Skill 注册表。该注册表会直接嵌入 SKill 工具的描述信息中，让大模型能够识别所有 Skill，且不会占用对话 context 资源。
-
语义匹配阶段（对话中）： 用户发起请求后，大模型会检索嵌入在工具定义中的所有 Skill 描述；若模型判定用户请求与某个 Skill 的描述在语义上匹配，会以该Skill名称为参数，调用 Skill 工具。
-
执行阶段（Skill调用时）： Skill 工具被调用后，SkillsTool 会从磁盘加载对应 SKILL.md 的完整内容，并将内容与 Skill 的基础目录路径一并返回给大模型。大模型随后按照 SKILL.md 中的指令执行操作。若Skill 引用了其它文件或辅助脚本，大模型会通过 FileSystemTools的
Read函数或 ShellTools 的Bash函数按需访问。
Skill 应用实例
在这一节将通过一个实际场景示例演示 Skill 是如何工作的。
示例： 包含参考资料（References）和脚本（Scripts）的 Skill
当 Skills 整合了各类附加资源时，上述第三阶段的按需加载机制将发挥巨大作用。Skill 中可包含带有补充指令的参考文件，以及用于数据处理的可执行脚本 — 这些资源均在需要时才会加载。
以下是一个名为“my-skill“的 Skill 示例，该 skill 集成了 YouTube 视频字幕提取辅助脚本，以及一个补充指令文件 research_methodology.md 。
Skill 目录结构：
|
1 2 3 4 5 |
.claude/skills/my-skill/ ├── SKILL.md ├── scripts/ │ └── get_youtube_transcript.py └── research_methodology.md |
|
1 2 3 4 5 6 |
**遇到陌生概念或需要开展研究时:** 加载 `research_methodology.md` 文件，参考其中的详细指导 **在用户提供 YouTube 视频链接时:** 执行命令 `uv run scripts/get_youtube_transcript.py <video_url_or_id>` 提取视频字幕. |
当用户发起请求：“解释这个视频中的核心概念：https://www.youtube.com/watch?v=SGLjdkahoMk ，并遵循文档中的研究方法。“，AI 将按以下步骤执行：
- 调用 my-skill，加载其 SKILL.md 文件的完整内容；
- 识别到需要参考研究方法，调用
Read函数加载 research_methodology.md 文件的完整内容； - 识别到 YouTube 视频链接，通过 ShellTools 调用
Bash函数执行辅助脚本； - 基于提取的视频字幕，遵循研究方法中的指令，完成核心概念的解释。
脚本代码本身永远不会进入上下文窗口，只有脚本的输出结果会被加载，这一设计会让该方案的 token 使用效率大幅提升。
可以参考spring 官方提供的 Skills-Demo 项目，该项目完整实现了上述工作流。
安全提示： 示例脚本会直接在本地机器上执行，无沙箱隔离保护；使用前需要提前安装所有必要的运行时环境（Python、NodeJs 等）。为提升运行安全性，建议在容器环境中部署智能体应用。
快速开始
准备好在 Spring AI 项目中集成 Agent Skill 了么？按以下 4 个步骤即可实现：
步骤 1：引入依赖
在 pom 中添加如下依赖：
|
1 2 3 4 5 |
<dependency> <groupId>org.springaicommunity</groupId> <artifactId>spring-ai-agent-utils</artifactId> <version>0.4.2</version> </dependency> |
说明：如需获取最新稳定版本，请查看 GitHub release 页面。 环境要求：Spring-AI 版本需要为 2.0.0-M2+
步骤 2：配置智能体
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
@SpringBootApplication public class Application { @Bean CommandLineRunner demo(ChatClient.Builder chatClientBuilder) { return args -> { ChatClient chatClient = chatClientBuilder .defaultToolCallbacks(SkillsTool.builder() .addSkillsDirectory(".claude/skills") .build()) .defaultTools(FileSystemTools.builder().build()) .defaultTools(ShellTools.builder().build()) .build(); String response = chatClient.prompt() .user("Your task here") .call() .content(); }; } } |
生产环境建议： 对于打包后的应用，可通过 Spring 资源加载机制从类路径加载 Skill，示例如下：
该方式在将 Skill 作为 JAR/WAR 包部署的一部分进行分发时尤为实用。
步骤 3：创建首个 Skill
通过以下命令可以实现一个代码审查的 Skill：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
mkdir -p .claude/skills/code-reviewer cat > .claude/skills/code-reviewer/SKILL.md << 'EOF' --- name: code-reviewer description: 按照最佳实践、安全规范和Spring框架约定审查Java代码，当用户要求审查、分析或审计代码时调用。 --- # 代码审查工具 ## 审查指令 审查代码时，需完成以下检查： 1. 检查安全漏洞（SQL注入、跨站脚本攻击等）； 2. 验证Spring Boot最佳实践（@Service、@Repository等注解的正确使用）； 3. 排查潜在的空指针异常； 4. 针对代码的可读性和可维护性提出优化建议； 5. 结合代码示例，提供具体的逐行反馈。 EOF |
步骤 4：结合 Skill 使用智能体
代码如下：
|
1 2 3 4 5 6 7 8 9 |
// 调用智能体，使用代码审查Skill审查指定控制器类 String response = chatClient.prompt() .user("按照最佳实践审查这个Controller类：" + "src/main/java/com/example/UserController.java") .call() .content(); // 输出审查结果 System.out.println(response); |
运行上述代码后，大模型将按以下逻辑执行：
- 将“审查该 Controller 类“的请求与
code-reviewerSkill 的描述进行匹配； - 调用 SKill 工具，加载该 Skill 的 SKILL.md 文件中的全部指令；
- 调用 FileSystemTools 中的
Read工具，访问UserController.java文件； - 遵循审查指令对代码进行审查并输出详细反馈。
Skill 中的指令直接指导大模型的行为，无需将审查逻辑硬编码到 prompts 中。若要调整审查规则，只需要修改 Skill 文件即可，无需做代码改动。
当前局限性
尽管 Spring AI 智能体 Skill 的实现方案强大且灵活，但目前仍存在一些需要注意的局限性：
脚本执行的安全性问题
通过 ShellTools 执行的脚本会直接在本地机器运行，无沙箱隔离保护，这意味着存在安全风险的代码可能会访问本地文件系统、网络或系统资源。因此使用前务必审查所有 Skill 脚本，尤其是第三方提供的脚本；建议在容器化环境（Docker、Kubernetes）中部署智能体应用，降低安全风险。
无人工介入校验机制
目前暂无内置机制， 可在Skill或脚本执行前要求人工审批，大模型可自动调用所有已注册的 Skill 并执行其内置脚本。对于处理敏感操作的生产环境，建议采用基于 Spring AI 的工具回调机制实现自定义审批工作流，例如封装 ToolCallback 回调函数
Skill 版本控制能力有限
目前暂无内置的 Skill 版本控制系统。若修改某一 Skill 的行为，所有使用该 Skill 的应用都会自动加载新版本。对于生产环境，建议通过目录结构实现自定义的版本控制策略（如 .claude/skills/v1/、.claude/skills/v2/）。
相关拓展：Anthropic原生 Skill API
Spring AI 同时集成了 Anthropic 的原生 Skill API，该方案采用与通用智能体不同的实现思路：
- Skill 在 Anthropic 的沙箱化云容器中运行（无网络访问权限，仅支持预安装的软件包）；
- 提供预制的文档生成能力，支持 Excel、PowerPoint、Word、PDF 等格式；
- Skill 需上传至 Anthropic 服务器，可在企业工作空间内共享；
- 仅支持 Claude 系列模型（Sonnet 4、 Sonnet 4.5、 Opus 4）
核心差异： Anthropic 原生 Skill 运行在 Anthropic 的云基础设施中，而 Spring AI 通用智能体 Skill 运行在用户自有环境中。
方案选择建议
- 若需要安全的沙箱化执行环境，或依赖预制的文档生成能力，选择 Anthropic 原生Skill ；
- 若需要实现大模型可移植性、访问本地资源，或希望将 Skill 与应用打包部署，选择 Spring AI 通用智能体 Skill 。
能否同时使用两种方案？
可以。在同一应用中，可通过 Anthropic 原生 Skill 实现文档生成，同时通过 Spring AI 通用智能体 Skill 实现其他可移植的能力，二者定位不同，优势互补。
结论
智能体 Skill 为 Spring AI 带来了模块化、可复用的能力，且实现了无厂商锁定的特性。通过按需提供领域知识，无需修改代码即可更新智能体的行为，Skill可在不同项目间共享，还能无缝切换各大模型服务商。
spring-ai-agent-utils 工具包通过简单的、基于工具的实现方案，让 java 开发者能够轻松使用这一模式。无论是开发代码助手、文档生成工具，还是面向特定领域的智能体，Skill 都为梳理智能体的知识体系提供了可扩展的知识体系。
End ！！!
发表评论