Agent Skills是一种模块化能力，以包含YAML前置元数据的Markdown文件形式打包。每个技能都是一个文件夹,其中包含一个SKILL.md文件，该文件包含元数据（至少包括名称和描述）以及指导AI Agent如何执行特定任务的说明。
Agent Skills（AI Agent技能）正在成为构建智能应用的新范式。它将AI能力模块化为可发现、可加载的资源包，让开发者不再需要为每个任务硬编码知识或创建专用工具。
Spring A正式I将这一设计模式引入Java生态系统，并实现了跨LLM的可移植性——你只需定义一次技能，就能在OpenAI、Anthropic、Google Gemini等任何支持的模型上使用。
这是Spring AI Agentic Patterns系列的第一篇文章。本系列将深入探讨spring-ai-agent-utils工具包，一套受Claude Code启发的完整Agent模式集合。
我们将依次介绍Agent Skills（本文）、任务管理、AskUserQuestion交互式工作流，以及用于复杂多Agent系统的分层子Agent。
什么是Agent Skills
Agent Skills是一种模块化能力，以包含YAML前置元数据的Markdown文件形式打包。
每个技能都是一个文件夹,其中包含一个SKILL.md文件，该文件包含元数据（至少包括名称和描述）以及指导AI Agent如何执行特定任务的说明。
技能还可以捆绑脚本、模板和参考资料。前置元数据支持简单的字符串值和复杂的YAML结构（列表、嵌套对象），以应对高级使用场景。
技能使用渐进式加载来高效管理上下文：
• 发现阶段- 启动时，Agent仅加载每个可用技能的名称和描述，刚好足以知道何时可能相关
• 激活阶段- 当任务匹配技能描述时，Agent将完整的SKILL.md指令读入上下文
• 执行阶段- Agent遵循指令，根据需要加载引用的文件或执行捆绑的代码
这种方法允许你注册数百个技能，同时保持上下文窗口精简。想了解更多关于Agent Skills的信息，可以访问官方规范网站agentskills.io。
为什么在Spring AI中使用Agent Skills
无缝集成- 通过简单注册几个工具，即可将Agent Skills添加到现有Spring AI应用中，无需架构变更
可移植且模型无关- 与绑定到特定LLM平台的实现不同，Spring AI的实现跨多个LLM提供商工作，让你无需重写代码或技能即可切换模型
可重用和可组合- 技能可以跨项目共享、与代码版本控制、组合创建复杂工作流，并通过辅助脚本和参考资料进行扩展。Spring AI Skills无缝支持任何现有的Claude Code Skills
相关的Spring AI工具：Agent Skills与其他基于工具的Spring AI功能配合良好，例如用于高效工具选择的动态工具发现，以及用于在技能执行期间捕获LLM推理的工具参数增强。
Spring AI Skills的工作原理
Spring AI采用基于工具的集成方法，实现了允许任何LLM触发技能并访问捆绑资产的工具。该实现严格遵循Claude Code的Skills、Bash和Read工具规范。
核心工具集包括：SkillsTool（必需）、ShellTools（可选）和FileSystemTools（可选）。
SkillsTool提供一个Skill函数，使AI模型能够按需发现和加载指定的技能，与FileSystemTools（用于读取参考文件）和ShellTools（用于执行辅助脚本）配合使用。
技能通过三步流程运作：
1. 发现（启动时）- 初始化期间，SkillsTool扫描配置的技能目录（如.claude/skills/），并从每个SKILL.md文件解析YAML前置元数据。它提取名称和描述字段来构建轻量级技能注册表，该注册表直接嵌入Skill工具的描述中，使其对LLM可见而不消耗对话上下文
2. 语义匹配（对话期间）- 当用户提出请求时，LLM检查嵌入在工具定义中的技能描述。如果LLM确定用户请求在语义上与技能描述匹配，它将使用技能名称作为参数调用Skill工具
3. 执行（技能调用时）- 当调用Skill工具时，SkillsTool从磁盘加载完整的SKILL.md内容，并将其与技能的基本目录路径一起返回给LLM。然后LLM遵循技能内容中的指令。如果技能引用其他文件或辅助脚本，LLM使用FileSystemTools的Read函数或ShellTools的Bash函数按需访问它们
实战案例：带引用和脚本的技能
第三步的按需加载在技能捆绑额外资源时变得强大。技能可以包含带有补充指令的参考文件和用于数据处理的可执行脚本——全部仅在需要时加载。
以下是一个来自my-skill技能的示例，该技能包含YouTube转录提取辅助脚本和补充research_methodology.md指令。
当用户询问"解释这个视频中的概念：https://youtube.com/watch?v=abc123。遵循研究方法"时，AI会：
• 调用my-skill技能并加载其SKILL.md内容
• 识别研究方法需求并使用Read加载research_methodology.md
• 识别YouTube URL并通过ShellTools使用Bash执行辅助脚本
• 使用视频转录遵循研究方法指令解释概念
脚本代码从不进入上下文窗口——只有输出进入，使这种方法具有高度的token效率。
安全提示：脚本直接在本地机器上执行，没有沙箱。你需要预安装任何所需的运行时（Python、Node.js等）。为了更安全的操作，考虑在容器中运行Agent应用程序。
快速开始
准备将Agent Skills添加到Spring AI项目了吗？
第一步：添加依赖
在pom.xml中添加spring-ai-agent-utils依赖，版本0.3.0。
需要注意的是，你需要Spring-AI版本2.0.0-SNAPSHOT或2.0.0-M2（发布后）。最新稳定版本请查看GitHub发布页面。
第二步：配置Agent
在Spring Boot应用程序中，通过ChatClient.Builder配置你的Agent。
使用SkillsTool.builder()添加技能目录（如.claude/skills），并注册FileSystemTools和ShellTools。
生产环境提示：对于打包的应用程序，你可以使用Spring Resources从类路径加载技能。这在将技能作为JAR/WAR部署的一部分分发时特别有用。
第三步：创建第一个技能
创建一个代码审查技能示例。
在.claude/skills/code-reviewer目录下创建SKILL.md文件，定义技能名称、描述和指令。该技能将指导LLM检查安全漏洞、验证Spring Boot最佳实践、寻找潜在的空指针异常，并提供可读性和可维护性的改进建议。
第四步：使用技能
当你运行应用程序时，
LLM将会：匹配"审查这个控制器"与code-reviewer技能的描述；调用Skill工具从SKILL.md加载完整指令；使用Read工具（来自FileSystemTools）访问UserController.java文件；遵循审查指令并提供详细反馈。
技能的指令指导LLM的行为，而无需在提示中硬编码审查逻辑——只需更新技能文件即可更改审查的工作方式。
当前限制
虽然Spring AI Agent Skills实现功能强大且灵活，但需要注意一些当前的限制：
• 脚本执行安全性- 通过ShellTools执行的脚本直接在本地机器上运行，没有沙箱。这意味着潜在的不安全代码可能访问文件系统、网络或系统资源。始终在使用前审查技能脚本，特别是来自第三方的脚本。考虑在容器化环境（Docker、Kubernetes）中运行Agent应用程序以限制暴露
• 缺少人机协同机制- 目前没有内置机制要求在执行技能或脚本之前获得人工批准。LLM可以自动调用任何注册的技能并执行任何捆绑的脚本。对于处理敏感操作的生产环境，你可能需要使用Spring AI的工具回调机制实现自定义批准工作流
• 有限的技能版本控制- 目前没有内置的技能版本系统。如果你更新技能的行为，所有使用该技能的应用程序将立即使用新版本。对于生产部署，考虑通过目录结构实现自己的版本策略（例如，.claude/skills/v1/、.claude/skills/v2/）
总结与展望
Agent Skills为Spring AI应用带来了模块化、可重用的能力，而不会被供应商锁定。通过按需提供领域知识，你可以在不更改代码的情况下更新Agent行为，跨项目共享技能，并无缝切换LLM提供商。
spring-ai-agent-utils实现使Java开发人员能够以简单、基于工具的方法访问这种模式。无论是构建编码助手、文档生成器还是特定领域的Agent，技能都为组织Agent知识提供了可扩展的基础。
这仅仅是开始。本系列即将发布的文章将深入探讨高级Agent模式，这些模式将改变Agent处理复杂工作流的方式：
即将推出的系列内容：
• 任务管理- 学习TodoWriteTool如何通过状态跟踪管理多步骤任务，实现透明、可追踪的Agent工作流
• 使用AskUserQuestion的交互式工作流- 发现Agent如何在执行期间收集用户偏好并澄清需求
• 分层子Agent- 探索TaskTools构建多Agent架构，其中专业的子Agent使用专用上下文窗口处理复杂任务
在此过程中，我们将演示核心Agent工具——FileSystemTools、ShellTools、GrepTool、GlobTool和Web访问工具——如何与这些模式集成以实现复杂的Agent行为。
从示例项目开始探索，或深入了解Agent Skills规范以了解更多信息。相关资源包括Spring AI Agent Utils工具包GitHub仓库、完整文档、工具文档，以及skills-demo、code-agent-demo和subagent-demo等示例项目。
