Agent Skills 是一种模块化能力，以包含 YAML 前置元数据的 Markdown 文件形式打包。每个技能都是一个文件夹，其中包含一个 SKILL.md 文件，该文件包含元数据（至少包括名称和描述）以及指导 AI Agent 如何执行特定任务的说明。
Agent Skills（AI Agent 技能）正在成为构建智能应用的新范式。它将 AI 能力模块化为可发现、可加载的资源包，让开发者不再需要为每个任务硬编码知识或创建专用工具。
Spring AI 将这一设计模式引入 Java 生态系统，并实现了跨 LLM 的可移植性——你只需定义一次技能，就能在 OpenAI、Anthropic、Google Gemini 等任何支持的模型上使用。
什么是 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 模式。相关资源包括 Spring AI Agent Utils 工具包 GitHub 仓库、完整文档、工具文档，以及 skills-demo、code-agent-demo 和 subagent-demo 等示例项目。
