Spring AI 代理模式 Spring AI Agentic Patterns —— Spring AI (Part 1): Agent Skills-洪萨配资

Spring AI Agentic Patterns

Spring AI 代理模式

Agent Skills are modular folders of instructions, scripts, and resources that AI agents can discover and load on demand. Instead of hardcoding knowledge into prompts or creating specialized tools for every task, skills provide a flexible way to extend agent capabilities.

Spring AI's implementation brings Agent Skills to the Java ecosystem, ensuring LLM portability—define your skills once and use them with OpenAI, Anthropic, Google Gemini, or any other supported model.

This is the first post in our Spring AI Agentic Patterns series. This series explores the spring-ai-agent-utils toolkit—an extensive set of agentic patterns for Spring AI, inspired by Claude Code. We'll cover Agent Skills (this post), followed by Task Management, AskUserQuestion for interactive workflows, and Hierarchical Sub-Agents for complex multi-agent systems.

Agent Skills（智能体技能）是由指令集、脚本和资源组成的模块化文件夹，AI智能体可按需发现并加载这些内容。不同于将知识硬编码到提示词中或为每个任务创建专用工具，技能提供了一种灵活的方式来扩展智能体能力。

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

这是Spring AI智能体模式系列的首篇文章。本系列将探索spring-ai-agent-utils工具包——这套受Claude Code启发的Spring AI智能体模式集合包含丰富功能。我们将依次介绍：Agent Skills（本文）、任务管理、用于交互式工作流的AskUserQuestion功能，以及面向复杂多智能体系统的分层子智能体架构。

🚀Want to jump right in?Skip to the Getting Started section.

Let's start with Agent Skills - the foundation for organizing agent knowledge.

What Are Agent Skills?

Agent Skills are modular capabilities packaged as Markdown files withYAML frontmatter. Each skill is a folder containing aSKILL.mdfile with metadata (nameanddescription, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials. The frontmatter supports both simple string values and complex YAML structures (lists, nested objects) for advanced use cases.

什么是智能体技能？
智能体技能是以带YAML前端元数据的Markdown文件封装的模块化能力。每个技能是一个文件夹，内含一个包含元数据（至少包括名称和描述）的SKILL.md文件，以及指导智能体执行特定任务的说明。技能还可捆绑脚本、模板和参考资料。其前端元数据既支持简单字符串值，也支持复杂YAML结构（列表、嵌套对象）以满足高阶需求。

my-skill/ ├── SKILL.md # Required: instructions + metadata ├── scripts/ # Optional: executable code ├── references/ # Optional: documentation └── assets/ # Optional: templates, resources

Skills useprogressive disclosureto manage context efficiently:

Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
Activation: When a task matches a skill's description, the agent reads the fullSKILL.mdinstructions into context.
Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.

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

发现阶段：启动时，智能体仅加载每个可用技能的名称和描述，仅需了解何时可能相关即可。

激活阶段：当任务与技能描述匹配时，智能体会将完整的SKILL.md指令读入上下文。

执行阶段：智能体遵循指令，根据需要可选地加载引用文件或执行捆绑代码。

This approach allows you to register hundreds of skills while keeping your context window lean.

💡Tip:Find out more about Agent Skills in the official specification.

Why Use Agent Skills in Spring AI

Seamless Integration- Add Agent Skills to your existing Spring AI application by simply registering a few tools—no architectural changes required.

Portability and Model Agnostic - No Vendor Lock-In- Unlike implementations tied to specific LLM platforms, this Spring AI implementation works across many LLM providers, letting you switch models without rewriting code or skills.

Reusable and Composable- Skills can be shared across projects, version-controlled with your code, combined to create complex workflows, and extended with helper scripts and reference materials. Spring AI Skills seamlessly supports any existing Claude Code Skills.

Related Spring AI Tools:Agent Skills work well with other Spring AI tool-based features like Dynamic Tool Discovery for efficient tool selection and Tool Argument Augmentation for capturing LLM reasoning during skill execution.

为何在Spring AI中使用智能体技能
无缝集成 - 只需注册少量工具即可将智能体技能添加到现有Spring AI应用中，无需更改架构设计。

可移植且模型无关 - 避免供应商锁定 - 与绑定特定大语言模型平台的实现不同，该Spring AI方案支持多模型供应商，无需重写代码或技能即可切换模型。

可复用与可组合 - 技能可跨项目共享，与代码版本控制协同，组合构建复杂工作流，并能通过辅助脚本和参考资料扩展。Spring AI技能无缝兼容现有Claude代码技能。

相关Spring AI工具：智能体技能与其他基于工具的Spring AI功能完美配合，例如用于高效工具选择的动态工具发现，以及在技能执行时捕获大语言模型推理过程的工具参数增强功能。

How Spring AI Skills Work

Spring AI uses the tool-based integration approach, implementing tools that allow any LLM to trigger skills and access bundled assets. The implementation closely follows Claude Code's tool specifications forSkills,Bash, andRead.

The core set of tools is: SkillsTool (required), ShellTools (optional), and FileSystemTools (optional). SkillsTool provides aSkillfunction that enables AI models to discover and load specified skills on demand, working in conjunction with FileSystemTools (for reading reference files) and ShellTools (for executing helper scripts).

Spring AI 的工作原理
Spring AI 采用基于工具的集成方案，通过实现各类工具使任意大语言模型都能触发技能并访问捆绑资源。该实现严格遵循Claude Code针对技能、命令行和文件读取的工具规范。

核心工具集包含：SkillsTool（必需）、ShellTools（可选）和FileSystemTools（可选）。其中SkillsTool提供Skill功能，使AI模型能按需发现并加载指定技能，该功能需与FileSystemTools（读取参考文件）及ShellTools（执行辅助脚本）协同工作。

Skills operate through a three-step process:

1. Discovery (at startup)- During initialization, SkillsTool scans configured skills directories (such as.claude/skills/) and parses the YAML frontmatter from eachSKILL.mdfile. It extracts thenameanddescriptionfields to build a lightweight skill registry that's embedded directly into theSkilltool's description, making it visible to the LLM without consuming conversation context.

2. Semantic Matching (during conversation)- When a user makes a request, the LLM examines the skill descriptions embedded in the tool definition. If the LLM determines a user request semantically matches a skill's description, it invokes theSkilltool with the skill name as a parameter.

3. Execution (on skill invocation)- When theSkilltool is called, SkillsTool loads the fullSKILL.mdcontent from disk and returns it to the LLM along with the skill's base directory path. The LLM then follows the instructions in the skill content. If the skill references additional files or helper scripts, the LLM uses FileSystemTools'Readfunction or ShellTools'Bashfunction to access them on demand.

发现（启动阶段） - 初始化期间，SkillsTool会扫描配置的技能目录（如.claude/skills/），并解析每个SKILL.md文件的YAML前置元数据。提取其中的name和description字段构建轻量级技能注册表，该注册表直接嵌入到Skill工具描述中，使大语言模型无需消耗对话上下文即可感知这些技能。
语义匹配（对话阶段） - 当用户发起请求时，大语言模型会检查工具定义中嵌入的技能描述。若模型判定用户请求与某技能描述语义匹配，则以技能名称为参数调用Skill工具。
执行（技能调用时） - 当Skill工具被调用时，SkillsTool从磁盘加载完整的SKILL.md内容，并将其与技能基础目录路径一同返回给大语言模型。随后大语言模型遵循技能内容中的指令执行操作。若技能涉及附加文件或辅助脚本，模型将通过FileSystemTools的Read功能或ShellTools的Bash功能按需访问。

Skills in Action

This section demonstrates how skills work in practice with real-world examples.

Example: Skills with References and Scripts

Step 3's on-demand loading becomes powerful when skills bundle additional resources. Skills can include reference files with supplementary instructions and executable scripts for data processing—all loaded only when needed.

Here's an example from the my-skill skill that includes a YouTube transcript extraction helper and supplementaryresearch_methodology.mdinstructions:

示例：带有参考文件和脚本的技能
当技能包附加资源时，步骤3的按需加载功能变得强大。技能可以包含带有补充说明的参考文件以及用于数据处理的可执行脚本——所有这些仅在需要时加载。

以下是来自my-skill技能的一个示例，其中包含YouTube转录提取助手和补充说明文件research_methodology.md：

Skill Directory Structure:

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

In SKILL.md:

... **If concept is unfamiliar or requires research:** Load `research_methodology.md` for detailed guidance. **If user provides YouTube video:** Call `uv run scripts/get_youtube_transcript.py <video_url_or_id>` for video's transcript. ...

When a user asks "Explain the concepts from this video: https://youtube.com/watch?v=abc123. Follow the research methodology", the AI:

Invokes the my-skill skill and loads its SKILL.md content
Recognizes the need for research methodology and usesReadto loadresearch_methodology.md
Recognizes the YouTube URL and usesBashto execute the helper script via ShellTools
Uses the video transcript to explain the concepts following the research methodology instructions

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

调用my-skill技能并加载其SKILL.md内容识别研究方法论需求并使用Read功能加载research_methodology.md文件识别YouTube链接并通过ShellTools调用Bash执行辅助脚本依据视频转录文本，按照研究方法论指南解释相关概念

The script code never enters the context window—only the output does, making this approach highly token-efficient.

💡DemoCheck out the Skills-Demo that implements this workflow.

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

💡演示查看实现此工作流程的技能演示。

⚠️Security Note:Scripts execute directly on your local machine without sandboxing. You'll need to pre-install any required runtimes (Python, Node.js, etc.). For safer operation, consider running your agentic application in a container.

Getting Started

Ready to add Agent Skills to your Spring AI project?

1. Add the dependency:

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

Note:For the latest stable release, check the GitHub releases page.

Note:You need Spring-AI2.0.0-M2+.

2. Configure your agent:

@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(); }; } }

💡 Production Tip:For packaged applications, you can load skills from the classpath using Spring Resources:
.defaultToolCallbacks(SkillsTool.builder() .addSkillsResource(resourceLoader.getResource("classpath:.claude/skills")) .build())
This is particularly useful when distributing skills as part of your JAR/WAR deployment.

3. Create your first skill:

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. Use your agent with the skill:

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);

When you run this, the LLM will:

Match "Review this controller" with the code-reviewer skill's description
Invoke theSkilltool to load the full instructions fromSKILL.md
UseReadtool (from FileSystemTools) to access the UserController.java file
Follow the review instructions and provide detailed feedback

当你运行这个程序时，LLM（大型语言模型）将会：

将"Review this controller"与代码审查技能的描述进行匹配
调用技能工具从SKILL.md加载完整的指令
使用读取工具（来自FileSystemTools）访问UserController.java文件
按照审查指令提供详细的反馈

The skill's instructions guide the LLM's behavior without you hardcoding review logic into your prompts—just update the skill file to change how reviews work.

技能的说明引导大语言模型的行为，无需您在提示中硬编码审核逻辑——只需更新技能文件即可改变审核机制。

Current Limitations

While the Spring AI Agent Skills implementation is powerful and flexible, there are some current limitations to be aware of:

当前限制
尽管Spring AI代理技能实现功能强大且灵活，但目前仍存在一些需要注意的限制：

Script Execution Security- Scripts executed via ShellTools run directly on your local machine without sandboxing. This means potentially unsafe code could access your filesystem, network, or system resources. Always review skill scripts before use, especially from third-party sources. Consider running your agentic application in a containerized environment (Docker, Kubernetes) to limit exposure.

No Human-in-the-Loop- Currently, there's no built-in mechanism to require human approval before executing skills or scripts. The LLM can invoke any registered skill and execute any bundled script automatically. For production environments handling sensitive operations, you may need to implement custom approval workflows using Spring AI's tool callback mechanisms, for example, aToolCallbackwrapper.

Limited Skill Versioning- There's currently no built-in versioning system for skills. If you update a skill's behavior, all applications using that skill will immediately use the new version. For production deployments, consider implementing your own versioning strategy through directory structure (e.g.,.claude/skills/v1/,.claude/skills/v2/).

脚本执行安全性 - 通过ShellTools执行的脚本直接在本地机器上运行，不经过沙箱隔离。这意味着潜在不安全的代码可能访问您的文件系统、网络或系统资源。使用前请务必审查技能脚本，特别是来自第三方来源的脚本。建议在容器化环境（Docker、Kubernetes）中运行您的智能体应用以降低风险。

无人值守执行 - 当前系统没有内置机制要求在执技能或脚本前获得人工批准。大语言模型可以自动调用任何已注册技能并执行捆绑脚本。对于处理敏感操作的生产环境，您可能需要通过Spring AI的工具回调机制（例如ToolCallback包装器）实现自定义审批流程。

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

Related: Anthropic's Native Skills API

Spring AI also integrates with Anthropic's native Skills API, which provides a different approach:

Skills run in Anthropic's sandboxed cloud container (no network access, pre-installed packages only)
Pre-built document generation: Excel, PowerPoint, Word, PDF
Skills are uploaded to Anthropic's servers and shared across your workspace
Requires Claude models (Sonnet 4, Sonnet 4.5, Opus 4)

相关内容：Anthropic原生技能API Spring AI还集成了Anthropic的原生技能API，该API提供了一种不同的实现方式：

技能在Anthropic的沙盒云容器中运行（无网络访问权限，仅限预装软件包）预置文档生成功能：Excel、PowerPoint、Word、PDF 技能会上传至Anthropic服务器并在工作区内共享需使用Claude模型（Sonnet 4、Sonnet 4.5、Opus 4）

Key difference:Anthropic Skills run in Anthropic's cloud infrastructure; Generic Agent Skills run in your environment.

Use Anthropic's native Skills when you need secure, sandboxed execution or the pre-built document generation capabilities. Use Generic Agent Skills when you need LLM portability, local resource access, or want skills bundled with your application.

Can you use both?Yes. You can use Anthropic's native Skills for document generation while using Generic Agent Skills for other portable capabilities in the same application. They serve different purposes and can complement each other.

主要区别：Anthropic技能运行在Anthropic的云端基础设施上；通用代理技能则在您的本地环境中运行。

当您需要安全隔离的执行环境或预置文档生成功能时，请选用Anthropic原生技能。若需要大语言模型的可移植性、本地资源访问权限，或希望将技能与应用程序捆绑部署，则应选择通用代理技能。

能否同时使用？可以。您可以在同一应用程序中，使用Anthropic原生技能处理文档生成，同时采用通用代理技能实现其他可移植功能。二者服务不同场景，能够形成互补关系。

See the Anthropic Skills in Spring AI post for details.

Conclusion

Agent Skills bring modular, reusable capabilities to Spring AI applications without vendor lock-in. By providing domain knowledge on demand, you can update agent behavior without code changes, share skills across projects, and switch between LLM providers seamlessly.

The spring-ai-agent-utils implementation makes this pattern accessible to Java developers with a simple, tool-based approach. Whether building coding assistants, documentation generators, or domain-specific agents, skills provide a scalable foundation for organizing agent knowledge.

Agent Skills为Spring AI应用带来了模块化、可复用的能力，且无厂商锁定风险。通过按需提供领域知识，您无需修改代码即可更新智能体行为，跨项目共享技能，并无缝切换不同的大语言模型供应商。

spring-ai-agent-utils的实现让Java开发者能以简单的工具化方式运用这一模式。无论是构建代码助手、文档生成器，还是领域专用智能体，技能机制都为组织智能体知识提供了可扩展的基础架构。

This is just the beginning.The other posts in this series dive deeper into advanced agentic patterns:

Series links:

AskUserQuestionTool - Interactive workflows where agents gather user preferences during execution
TodoWriteTool - Transparent, trackable agent workflows with multi-step task management
Subagent Orchestration - Hierarchical multi-agent architectures with dedicated context windows
A2A Integration - Building interoperable agents with the Agent2Agent protocol
Subagent Extension Framework(coming soon) - Protocol-agnostic agent orchestration (A2A, MCP, custom)

Start exploring with the example projects or dive into the Agent Skills specification to learn more.

Resources

Spring AI Agent Utils Toolkit

GitHub Repository: spring-ai-agent-utils
Full Documentation: README.md
Tool Documentation- Tools covered in this post: SkillsTool, FileSystemTools, ShellTools
Spring AI Documentation: docs.spring.io/spring-ai

Example Projects

skills-demo - Focused skills demonstration (this post)
code-agent-demo - Full toolkit integration (Parts 2-3)
subagent-demo - Hierarchical agents and A2A integration (Parts 4-5)

Agent Skills

Specification: agentskills.io
Claude Code Documentation: code.claude.com/docs

Series Links

Part 1: Agent Skills (this post) - Modular, reusable capabilities
Part 2: AskUserQuestionTool - Interactive workflows
Part 3: TodoWriteTool - Structured planning
Part 4: Subagent Orchestration - Hierarchical agent architectures
Part 5: A2A Integration - Building interoperable agents with the Agent2Agent protocol
Part (soon): Subagent Extension Framework (coming soon) - Protocol-agnostic agent orchestration