原文链接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 SkillsAgent 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?vabc123。遵循研究方法论时AI调用my-skill技能并加载其 SKILL.md 内容识别出需要研究方法论使用 Read 加载research_methodology.md识别出 YouTube URL使用 Bash 通过 ShellTools 执行辅助脚本使用视频字幕按照研究方法论指令解释概念脚本代码永远不会进入上下文窗口——只有输出会这使得这种方法具有极高的令牌效率。演示查看实现此工作流的 Skills-Demo。⚠️安全提示脚本直接在本地机器上执行没有沙箱。你需要预装任何所需的运行时Python、Node.js 等。为了更安全的操作请考虑在容器中运行你的 Agentic 应用程序。入门指南准备好在 Spring AI 项目中添加 Agent Skills 了吗1. 添加依赖dependencygroupIdorg.springaicommunity/groupIdartifactIdspring-ai-agent-utils/artifactIdversion0.4.2/version/dependency注意对于最新的稳定版本请查看 GitHub releases 页面。注意你需要 Spring-AI 2.0.0-M2。2. 配置你的 AgentSpringBootApplicationpublicclassApplication{BeanCommandLineRunnerdemo(ChatClient.BuilderchatClientBuilder){returnargs-{ChatClientchatClientchatClientBuilder.defaultToolCallbacks(SkillsTool.builder().addSkillsDirectory(.claude/skills).build()).defaultTools(FileSystemTools.builder().build()).defaultTools(ShellTools.builder().build()).build();StringresponsechatClient.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.mdEOF --- name: code-reviewer description: 审查 Java 代码的最佳实践、安全问题和 Spring Framework 约定。当用户要求审查、分析或审计代码时使用。 --- # 代码审查器 ## 指令 审查代码时 1. 检查安全漏洞SQL 注入、XSS 等 2. 验证 Spring Boot 最佳实践正确使用 Service、Repository 等 3. 查找潜在的空指针异常 4. 提出可读性和可维护性的改进建议 5. 提供带有代码示例的具体行级反馈 EOF4. 使用带有技能配置的 AgentStringresponsechatClient.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/实现你自己的版本控制策略。相关Anthropic 的原生 Skills APISpring AI 还与 Anthropic 的原生 Skills API 集成它提供了一种不同的方法Skills 在 Anthropic 的沙箱云容器中运行无网络访问仅预装包预构建的文档生成Excel、PowerPoint、Word、PDFSkills 上传到 Anthropic 的服务器并在你的工作区中共享需要 Claude 模型Sonnet 4、Sonnet 4.5、Opus 4关键区别Anthropic Skills 在 Anthropic 的云基础设施中运行通用 Agent Skills 在你的环境中运行。当你需要安全的沙箱执行或预构建的文档生成能力时使用 Anthropic 的原生 Skills。当你需要 LLM 可移植性、本地资源访问或希望将技能与应用程序捆绑时使用通用 Agent Skills。可以同时使用两者吗可以。你可以在同一个应用程序中使用 Anthropic 的原生 Skills 进行文档生成同时使用通用 Agent Skills 处理其他可移植能力。它们服务于不同的目的可以相互补充。详见 Spring AI 中的 Anthropic Skills 文章。结论Agent Skills 为 Spring AI 应用程序带来了模块化、可复用的能力且没有供应商锁定。通过按需提供领域知识你可以在不更改代码的情况下更新 Agent 行为在项目间共享技能并在 LLM 提供商之间无缝切换。spring-ai-agent-utils 实现通过简单、基于工具的方法使 Java 开发者能够轻松使用这种模式。无论是构建编码助手、文档生成器还是领域特定的 AgentSkills 都为组织 Agent 知识提供了可扩展的基础。这仅仅是个开始。本系列的其他文章将深入探讨更高级的 Agentic 模式系列链接AskUserQuestionTool - Agent 在执行过程中收集用户偏好的交互式工作流TodoWriteTool - 透明、可追踪的 Agent 工作流支持多步骤任务管理Subagent Orchestration - 具有专用上下文窗口的分层多 Agent 架构A2A Integration - 使用 Agent2Agent 协议构建可互操作的 AgentSubagent Extension Framework即将推出- 协议无关的 Agent 编排A2A、MCP、自定义从示例项目开始探索或深入了解 Agent Skills 规范以了解更多信息。资源Spring AI Agent Utils 工具包GitHub 仓库spring-ai-agent-utils完整文档README.md工具文档 - 本文涉及的工具SkillsTool、FileSystemTools、ShellToolsSpring AI 文档docs.spring.io/spring-ai示例项目skills-demo - 专注的技能演示本文code-agent-demo - 完整的工具包集成第 2-3 部分subagent-demo - 分层 Agent 和 A2A 集成第 4-5 部分Agent Skills规范agentskills.ioClaude Code 文档code.claude.com/docs系列链接第 1 部分Agent Skills本文- 模块化、可复用的能力第 2 部分AskUserQuestionTool - 交互式工作流第 3 部分TodoWriteTool - 结构化规划第 4 部分Subagent Orchestration - 分层 Agent 架构第 5 部分A2A Integration - 使用 Agent2Agent 协议构建可互操作的 Agent即将推出Subagent Extension Framework即将推出- 协议无关的 Agent 编排相关的 Spring AI 博客Dynamic Tool Discovery - 实现 34-64% 的令牌节省Tool Argument Augmentation - 在工具执行期间捕获 LLM 推理