当前位置：首页 > news >正文

Spring AI Agentic 模式（第1部分）：Agent Skills——模块化、可复用的能力

news 2026/7/8 3:42:33

原文链接：https://spring.io/blog/2026/01/13/spring-ai-generic-agent-skills
这是一篇翻译的文章，其中部分内容可能不是非常准确，如果有提出来。或者直接对照原文

Agent Skills 是包含指令、脚本和资源的模块化文件夹，AI Agent 可以按需发现和加载它们。相比于将知识硬编码到提示词中或为每个任务创建专门的工具，Skills 提供了一种灵活的方式来扩展 Agent 的能力。

Spring AI 的实现将 Agent Skills 带到了 Java 生态系统中，确保了 LLM 的可移植性——只需定义一次技能，即可在 OpenAI、Anthropic、Google Gemini 或任何其他受支持的模型中使用。

这是我们 Spring AI Agentic 模式系列的第一篇文章。本系列探讨 spring-ai-agent-utils 工具包——这是一个受 Claude Code 启发、为 Spring AI 提供的大量 Agentic 模式集合。我们将涵盖 Agent Skills（本文）、Task Management、用于交互式工作流的 AskUserQuestion，以及用于复杂多 Agent 系统的 Hierarchical Sub-Agents。

🚀 想直接上手？跳到"入门指南"部分。

让我们从 Agent Skills 开始——它是组织 Agent 知识的基础。

什么是 Agent Skills？

Agent Skills 是打包为带有 YAML frontmatter 的 Markdown 文件的模块化能力。每个技能都是一个包含 SKILL.md 文件的文件夹，该文件包含元数据（至少包括名称和描述）以及告诉 Agent 如何执行特定任务的指令。Skills 还可以捆绑脚本、模板和参考资料。frontmatter 支持简单的字符串值和复杂的 YAML 结构（列表、嵌套对象），适用于高级用例。

my-skill/ ├── SKILL.md # 必需：指令 + 元数据 ├── scripts/ # 可选：可执行代码 ├── references/ # 可选：文档 └── assets/ # 可选：模板、资源

Skills 使用渐进式披露来高效管理上下文：

发现：启动时，Agent 只加载每个可用技能的名称和描述，刚好足够知道何时可能相关。
激活：当任务匹配技能的描述时，Agent 将完整的 SKILL.md 指令读入上下文。
执行：Agent 遵循指令，可选地按需加载引用的文件或执行捆绑的代码。

这种方法允许你注册数百个技能，同时保持上下文窗口的精简。

💡提示：在官方规范中了解更多关于 Agent Skills 的信息。

为什么在 Spring AI 中使用 Agent Skills

无缝集成- 只需注册几个工具，即可将 Agent Skills 添加到现有的 Spring AI 应用程序中——无需架构更改。

可移植性和模型无关性 - 无供应商锁定- 与绑定到特定 LLM 平台的实现不同，此 Spring AI 实现适用于许多 LLM 提供商，让你无需重写代码或技能即可切换模型。

可复用和可组合- Skills 可以在项目间共享，与代码一起进行版本控制，组合以创建复杂的工作流，并通过辅助脚本和参考资料进行扩展。Spring AI Skills 无缝支持任何现有的 Claude Code Skills。

相关的 Spring AI 工具：Agent Skills 与其他基于 Spring AI 工具的功能配合良好，如用于高效工具选择的 Dynamic Tool Discovery 和用于在技能执行期间捕获 LLM 推理的 Tool Argument Augmentation。

Spring AI Skills 如何工作

Spring AI 使用基于工具的集成方法，实现允许任何 LLM 触发技能和访问捆绑资产的工具。该实现紧密遵循 Claude Code 针对 Skills、Bash 和 Read 的工具规范。

核心工具集包括：SkillsTool（必需）、ShellTools（可选）和 FileSystemTools（可选）。SkillsTool 提供了一个 Skill 函数，使 AI 模型能够按需发现和加载指定的技能，与 FileSystemTools（用于读取参考文件）和 ShellTools（用于执行辅助脚本）协同工作。

Skills 通过三步流程运作：

1. 发现（启动时）

在初始化期间，SkillsTool 扫描配置的技能目录（如.claude/skills/），并解析每个 SKILL.md 文件中的 YAML frontmatter。它提取name和description字段，构建一个轻量级的技能注册表，直接嵌入到 Skill 工具的描述中，使其对 LLM 可见而不消耗对话上下文。

2. 语义匹配（对话期间）

当用户提出请求时，LLM 检查嵌入在工具定义中的技能描述。如果 LLM 确定用户请求在语义上与某个技能的描述匹配，它将以技能名称作为参数调用 Skill 工具。

3. 执行（技能调用时）

当 Skill 工具被调用时，SkillsTool 从磁盘加载完整的 SKILL.md 内容，并将其连同技能的基础目录路径一起返回给 LLM。然后 LLM 遵循技能内容中的指令。如果技能引用额外的文件或辅助脚本，LLM 按需使用 FileSystemTools 的 Read 函数或 ShellTools 的 Bash 函数来访问它们。

Skills 实战

本节通过实际示例演示技能如何工作。

示例：带有参考资料和脚本的 Skills

第 3 步的按需加载在技能捆绑额外资源时变得强大。Skills 可以包含带有补充指令的参考文件和用于数据处理的可执行脚本——所有这些仅在需要时加载。

以下来自my-skill技能的示例，包含一个 YouTube 字幕提取助手和补充的research_methodology.md指令：

技能目录结构：

.claude/skills/my-skill/ ├── SKILL.md ├── scripts/ │ └── get_youtube_transcript.py └── research_methodology.md

在 SKILL.md 中：

... **如果概念不熟悉或需要研究：** 加载 `research_methodology.md` 获取详细指导。 **如果用户提供 YouTube 视频：** 调用 `uv run scripts/get_youtube_transcript.py <video_url_or_id>` 获取视频字幕。 ...

当用户问"解释这个视频中的概念：https://youtube.com/watch?v=abc123。遵循研究方法论"时，AI：

调用my-skill技能并加载其 SKILL.md 内容
识别出需要研究方法论，使用 Read 加载research_methodology.md
识别出 YouTube URL，使用 Bash 通过 ShellTools 执行辅助脚本
使用视频字幕按照研究方法论指令解释概念

脚本代码永远不会进入上下文窗口——只有输出会，这使得这种方法具有极高的令牌效率。

💡演示：查看实现此工作流的 Skills-Demo。

⚠️安全提示：脚本直接在本地机器上执行，没有沙箱。你需要预装任何所需的运行时（Python、Node.js 等）。为了更安全的操作，请考虑在容器中运行你的 Agentic 应用程序。

入门指南

准备好在 Spring AI 项目中添加 Agent Skills 了吗？

1. 添加依赖：

<dependency><groupId>org.springaicommunity</groupId><artifactId>spring-ai-agent-utils</artifactId><version>0.4.2</version></dependency>

注意：对于最新的稳定版本，请查看 GitHub releases 页面。

注意：你需要 Spring-AI 2.0.0-M2+。

2. 配置你的 Agent：

@SpringBootApplicationpublicclassApplication{@BeanCommandLineRunnerdemo(ChatClient.BuilderchatClientBuilder){returnargs->{ChatClientchatClient=chatClientBuilder.defaultToolCallbacks(SkillsTool.builder().addSkillsDirectory(".claude/skills").build()).defaultTools(FileSystemTools.builder().build()).defaultTools(ShellTools.builder().build()).build();Stringresponse=chatClient.prompt().user("你的任务在这里").call().content();};}}

💡生产环境提示：对于打包的应用程序，你可以使用 Spring Resources 从 classpath 加载技能：

.defaultToolCallbacks(SkillsTool.builder().addSkillsResource(resourceLoader.getResource("classpath:.claude/skills")).build())

这在将技能作为 JAR/WAR 部署的一部分分发时特别有用。

3. 创建你的第一个技能：

mkdir-p.claude/skills/code-reviewercat>.claude/skills/code-reviewer/SKILL.md<<'EOF' --- name: code-reviewer description: 审查 Java 代码的最佳实践、安全问题和 Spring Framework 约定。当用户要求审查、分析或审计代码时使用。 --- # 代码审查器 ## 指令 审查代码时： 1. 检查安全漏洞（SQL 注入、XSS 等） 2. 验证 Spring Boot 最佳实践（正确使用 @Service、@Repository 等） 3. 查找潜在的空指针异常 4. 提出可读性和可维护性的改进建议 5. 提供带有代码示例的具体行级反馈 EOF

4. 使用带有技能配置的 Agent：

Stringresponse=chatClient.prompt().user("审查这个控制器类的最佳实践："+"src/main/java/com/example/UserController.java").call().content();System.out.println(response);

当你运行这段代码时，LLM 将：

将"Review this controller"与code-reviewer技能的描述匹配
调用 Skill 工具从 SKILL.md 加载完整指令
使用 Read 工具（来自 FileSystemTools）访问UserController.java文件
遵循审查指令并提供详细反馈

技能的指令指导 LLM 的行为，而无需你将审查逻辑硬编码到提示词中——只需更新技能文件即可改变审查的工作方式。

当前限制

虽然 Spring AI Agent Skills 实现功能强大且灵活，但需要注意一些当前限制：

脚本执行安全- 通过 ShellTools 执行的脚本直接在本地机器上运行，没有沙箱。这意味着可能不安全的代码可以访问你的文件系统、网络或系统资源。使用前务必审查技能脚本，尤其是来自第三方的脚本。考虑在容器化环境（Docker、Kubernetes）中运行你的 Agentic 应用程序以限制风险暴露。

无人参与审批- 目前没有内置机制在执行技能或脚本前要求人工批准。LLM 可以自动调用任何注册的技能并执行任何捆绑的脚本。对于处理敏感操作的生产环境，你可能需要使用 Spring AI 的工具回调机制实现自定义审批工作流，例如，一个 ToolCallback 包装器。

有限的技能版本控制- 目前没有内置的技能版本控制系统。如果你更新了技能的行为，所有使用该技能的应用程序将立即使用新版本。对于生产部署，考虑通过目录结构（如.claude/skills/v1/、.claude/skills/v2/）实现你自己的版本控制策略。