Spring AI 代理模式（第一部分）：代理技能 - 模块化、可复用的能力

副标题：“与LLM无关、在你的环境中运行的技能”

代理技能是包含指令、脚本和资源的模块化文件夹，AI代理能够按需发现并加载它们。代理技能并非将知识硬编码到提示中，或为每个任务创建专门的工具，而是提供了一种灵活的方式来扩展代理的能力。 Spring AI的实现将代理技能引入Java生态系统，确保了LLM的可移植性——只需定义一次你的技能，即可与OpenAI、Anthropic、Google Gemini或任何其他受支持的模型一起使用。 这是我们《Spring AI代理模式》系列的第一篇文章。本系列探讨了spring-ai-agent-utils工具包——受Claude Code启发，为Spring AI提供的一套广泛的代理模式。我们将涵盖：代理技能（本文）、任务管理、用于交互式工作流的AskUserQuestion，以及用于复杂多代理系统的分层子代理。 🚀 想直接上手？ 请跳转到入门指南部分。 让我们从代理技能开始——这是组织代理知识的基础。

什么是代理技能？

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

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

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

• 发现：启动时，代理仅加载每个可用技能的名称和描述，这足以让代理知道何时可能用到该技能。

• 激活：当任务与某个技能的描述匹配时，代理会将完整的SKILL.md指令读入上下文。

• 执行：代理遵循指令，并按需加载引用的文件或执行附带的代码。 这种方法允许你注册成百上千个技能，同时保持上下文窗口的精简。

  💡 提示：在官方规范中了解更多关于代理技能的信息。

  为什么在Spring AI中使用代理技能

  无缝集成 - 只需注册几个工具，即可将代理技能添加到现有的Spring AI应用程序中——无需更改架构。 可移植性与模型无关性 - 无供应商锁定 - 与绑定到特定LLM平台的实现不同，此Spring AI实现可跨多种LLM提供商工作，让你无需重写代码或技能即可切换模型。 可复用与可组合 - 技能可以在项目之间共享，与代码一起进行版本控制，组合起来创建复杂的工作流，并可通过辅助脚本和参考资料进行扩展。Spring AI Skills 无缝支持任何现有的 Claude Code Skills。 相关的Spring AI工具：代理技能可与其他基于Spring AI工具的特性很好地配合，例如用于高效工具选择的动态工具发现，以及在技能执行期间捕获LLM推理过程的工具参数增强。

  Spring AI Skills 的工作原理

  Spring AI 使用基于工具的集成方法，实现允许任何LLM触发技能并访问附带资产的工具。该实现紧密遵循 Claude Code 针对 Skills、Bash 和 Read 的工具规范。 核心工具集包括：SkillsTool（必需）、ShellTools（可选）和 FileSystemTools（可选）。SkillsTool 提供了一个技能函数，使AI模型能够按需发现并加载指定的技能，它与 FileSystemTools（用于读取参考文件）和 ShellTools（用于执行辅助脚本）协同工作。 技能通过三步流程运作：

  1. 发现（启动时）

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

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

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

  3. 执行（技能调用时）

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

  技能实战

  本节通过真实示例演示技能的实际工作方式。

  示例：带有参考文件和脚本的技能

  当技能附带额外资源时，第3步的按需加载会变得非常强大。技能可以包含带有补充指令的参考文件，以及用于数据处理的可执行脚本——所有这些都仅在需要时加载。 以下是一个来自 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会：

1. 调用 my-skill 技能并加载其 SKILL.md 内容

2. 识别出需要研究方法论，并使用 Read 加载 research_methodology.md

3. 识别出YouTube URL，并使用 Bash 通过 ShellTools 执行辅助脚本

4. 使用视频字幕，遵循研究方法论指令来解释概念 脚本代码永远不会进入上下文窗口——只有其输出会，这使得这种方法极具令牌效率。

   💡 演示：查看实现了此工作流的 Skills-Demo。 ⚠️ 安全须知：脚本将直接在您的本地机器上执行，没有沙箱环境。您需要预先安装任何所需的运行时（Python、Node.js等）。为了更安全地运行，请考虑在容器中运行您的代理应用程序。

   入门指南

   准备好将代理技能添加到您的Spring AI项目了吗？

   1. 添加依赖

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

   注意：要获取最新的稳定版本，请查看 GitHub发布页面。 注意：您需要 Spring-AI 2.0.0-M2+ 版本。

   2. 配置您的代理

   @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 的 Resource 从类路径加载技能：

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

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

3. 创建您的第一个技能

mkdir -p .claude/skills/code-reviewer
cat > .claude/skills/code-reviewer/SKILL.md << 'EOF'
---
name: code-reviewer
description: Reviews Java code for best practices, security issues, and Spring Framework conventions. Use when user asks to review, analyze, or audit code.
---
# Code Reviewer
## Instructions
When reviewing code:
1. Check for security vulnerabilities (SQL injection, XSS, etc.)
2. Verify Spring Boot best practices (proper use of @Service, @Repository, etc.)
3. Look for potential null pointer exceptions
4. Suggest improvements for readability and maintainability
5. Provide specific line-by-line feedback with code examples
EOF

4. 使用带有技能的代理

String response = chatClient.prompt()
    .user("Review this controller class for best practices: " +
          "src/main/java/com/example/UserController.java")
    .call()
    .content();
System.out.println(response);

当您运行此代码时，LLM将：

• 将“Review this controller”与 code-reviewer 技能的描述进行匹配

• 调用技能工具，从 SKILL.md 加载完整指令

• 使用 Read 工具（来自 FileSystemTools）访问 UserController.java 文件

• 遵循评审指令并提供详细的反馈 技能的指令指导LLM的行为，而无需您将评审逻辑硬编码到提示中——只需更新技能文件即可更改评审的工作方式。

  当前局限性

  尽管Spring AI Skills的实现强大且灵活，但当前存在一些需要注意的局限性： 脚本执行安全性 - 通过 ShellTools 执行的脚本直接在您的本地机器上运行，没有沙箱环境。这意味着可能不安全的代码可以访问您的文件系统、网络或系统资源。在使用前务必审查技能脚本，尤其是来自第三方的脚本。请考虑在容器化环境（Docker、Kubernetes）中运行您的代理应用程序以限制风险。 无人参与确认 - 目前，在执行技能或脚本之前，没有内置的机制需要人工批准。LLM可以自动调用任何已注册的技能并执行任何附带的脚本。对于处理敏感操作的生产环境，您可能需要使用Spring AI的工具回调机制（例如，一个 ToolCallback 包装器）来实现自定义的批准工作流。 有限的技能版本控制 - 目前没有内置的技能版本控制系统。如果您更新了技能的行为，所有使用该技能的应用程序将立即使用新版本。对于生产环境部署，请考虑通过目录结构（例如 .claude/skills/v1/，.claude/skills/v2/）来实现您自己的版本控制策略。

  相关：Anthropic 的原生 Skills API

  Spring AI 也集成了 Anthropic 的原生 Skills API，它提供了一种不同的方法：

• 技能在 Anthropic 的沙箱云容器中运行（无网络访问，仅预安装的包）

• 预构建的文档生成：Excel、PowerPoint、Word、PDF

• 技能上传到 Anthropic 的服务器，并在您的工作区中共享

• 需要 Claude 模型（Sonnet 4、Sonnet 4.5、Opus 4） 关键区别：Anthropic Skills 在 Anthropic 的云基础设施中运行；通用代理技能在您的环境中运行。 当您需要安全的、沙箱化的执行环境或预构建的文档生成能力时，请使用 Anthropic 的原生 Skills。当您需要LLM可移植性、本地资源访问，或者希望将技能与应用程序捆绑在一起时，请使用通用代理技能。 可以同时使用两者吗？ 是的。您可以在同一个应用程序中，将 Anthropic 的原生 Skills 用于文档生成，同时将通用代理 Skills 用于其他可移植的能力。它们服务于不同的目的，并且可以相互补充。 详细信息请参阅 Spring AI 中的 Anthropic Skills 一文。

  结论

  代理技能为 Spring AI 应用程序带来了模块化、可复用的能力，且没有供应商锁定。通过按需提供领域知识，您可以无需更改代码即可更新代理行为，在项目之间共享技能，并在不同的LLM提供商之间无缝切换。 spring-ai-agent-utils 实现通过简单、基于工具的方法，使这种模式对 Java 开发者变得易于使用。无论您是在构建编码助手、文档生成器还是特定领域的代理，技能都为组织代理知识提供了一个可扩展的基础。 这仅仅是个开始。本系列的其他文章将更深入地探讨高级代理模式： 系列链接：

• 第一部分：代理技能（本文） - 模块化、可复用的能力

• 第二部分：AskUserQuestionTool - 交互式工作流，代理在执行期间收集用户偏好

• 第三部分：TodoWriteTool - 透明、可追踪的代理工作流，带有多步骤任务管理

• 第四部分：子代理编排 - 具有专用上下文窗口的分层多代理架构

• 第五部分：A2A集成 - 使用 Agent2Agent 协议构建可互操作的代理

• 即将推出：子代理扩展框架 - 与协议无关的代理编排（A2A、MCP、自定义） 从示例项目开始探索，或深入了解 代理技能规范 以了解更多信息。

  资源

  Spring AI Agent Utils 工具包

• GitHub 仓库：spring-ai-agent-utils

• 完整文档：README.md

• 工具文档 - 本文涵盖的工具：SkillsTool、FileSystemTools、ShellTools

• Spring AI 文档：docs.spring.io/spring-ai 示例项目

• skills-demo - 重点演示技能（本文）

• code-agent-demo - 完整工具包集成（第2-3部分）

• subagent-demo - 分层代理和A2A集成（第4-5部分） 代理技能

• 规范：agentskills.io

• Claude Code 文档：code.claude.com/docs 系列链接

• 第一部分：代理技能（本文） - 模块化、可复用的能力

• 第二部分：AskUserQuestionTool - 交互式工作流

• 第三部分：TodoWriteTool - 结构化规划

• 第四部分：子代理编排 - 分层代理架构

• 第五部分：A2A集成 - 使用 Agent2Agent 协议构建可互操作的代理

• 即将推出：子代理扩展框架 - 与协议无关的代理编排 相关 Spring AI 博客文章

• 动态工具发现 - 实现34-64%的令牌节省

• 工具参数增强 - 在工具执行期间捕获LLM推理过程

---

【注】本文译自：Spring AI Agentic Patterns (Part 1): Agent Skills - Modular, Reusable Capabilities