文章目录
Spring AI 新增了对 Anthropic 智能体 Skill 的支持 — 这类模块化能力可让 Claude 直接生成实际文件，而非单纯的文本描述。启用该 Skill 后，Claude 能生成可直接下载使用的 Excel 电子表格、PowerPoint 演示文稿、Word 文档和 PDF 文件。
局限性说明
Anthropic Skill 的实现方案仅适用于其自研的 Claude 系列模型，存在以下局限性：
- 无移植性： 该 Skill 依赖 Anthropic 的代码执行能力和 Files API 基础设施，无法在其他大模型平台（OpenAI、 Gemini 等）使用；
- 专属类依赖： 需使用
AnthropicChatOptions、AnthropicSkill、AnthropicSkillsResponseHelper等 Anthropic 专属类，而非 Spring AI 的通用接口； - 模型限制： 仅 Claude Sonnet 4、Sonnet 4.5 和 Opus 4 模型支持该 Skill ；
- 文件有效期： 通过 Anthropic Files API 生成的文件，24 小时后会自动过期；
- 公测功能属性： Skill API 需携带公测版本请求头，且接口规范仍可能持续迭代。
Anthropic Skill 与通用智能体 Skill 的选型建议
Spring AI 支持两种不同的智能体 Skill 实现方案，可根据业务需求选择：
选择 Anthropic 原生Skill API 的场景
- 需使用预构建的文档生成能力，支持 Excel、PowerPoint、Word、PDF 等格式；
- 希望 Skill 在沙箱化的安全云端环境中运行；
- 需实现团队共享的、工作空间级别的 Skill；
- 业务已确定基于 Claude 系列模型开发；
- 希望由 Anthropic 负责管理 Skill 的执行基础设施
选择通用智能体 Skill (spring-ai-agent-utils) 的场景
- 需要让 Skill 适配多款大模型（OpenAI、 Anthropic、 Gemini 等）；
- Skill 需要访问本地资源、网络或自定义软件包；
- 希望将 Skill 与应用代码一起打包，进行版本控制；
- 需要对 Skill 的执行环境拥有更高的控制权；
- 优先考虑方案的可移植性，避免厂商锁定。
能否同时使用两种方案？
可以。在同一应用中，可通过 Anthropic 原生 Skill 实现文档生成，同时借助通用智能体 Skill 完成其他可移植的业务能力开发。二者定位不同、功能互补，可协同使用。
为何基于 Spring AI 使用 Anthropic Skill ？
直接调用 Anthropic 原生 API 使用其 Skill ，需要手动完成多个繁琐步骤：
- 为每个请求添加
code_execution工具（Skill运行的必备依赖）； - 携带三个公测版本请求头：
skills-2025-10-02、code-execution-2025-08-25、files-api-2025-04-14； - 解析多层嵌套的 JSON 响应，提取文件 ID；
- 发起独立的 HTTP 请求，下载生成的文件。
而基于 Spring AI 开发时，上述操作均可由框架自动完成。当在请求中添加 Skill 后，Spring AI 会自动执行以下操作：
- 自动注入代码执行工具： Skill 在服务端运行 Python 脚本，框架会自动添加所需的工具配置；
- 统一管理公测请求头： 自动添加全部三个必备请求头，并与提示词缓存等其它功能实现无缝融合；
- 通过类型安全的枚举类： 通过
AnthropicSkill.XLSX调用预构建的 Skill ，替代无类型提示的魔法字符串； - 构建时校验规则： 会在构建配置时校验请求的 Skill 数量是否超出上限（8 个），而非在 API 调用失败后才抛出异常；
- 自动提取文件 ID： 通过
AnthropicSkillResponseHelper递归检索嵌套的响应结构，精准提取文件 ID； - 深度集成 Files API： 直接通过
anthropicApi.downloadFile()方法下载生成的文件。
预构建 Skill
Anthropic 提供了四种预构建的 Skill：
| Skill标识 | 输出结果 |
|---|---|
| XLSX | 包含数据、公式、图表的 Excel 电子表格 |
| PPTX | 包含幻灯片、版式设计的 PowerPoint 演示文稿 |
| DOCX | 带格式的 Word 文档 |
| PDF 格式的报告与文档 |
启用对应 Skill 后， Claude 会自动完成内容设计和技术实现，接口响应结果中会包含文件 ID，指向 Anthropic Files API 中生成的文档。
基础使用方法
通过 AnthropicChatOptions 类的统一 skill() 方法，即可快速启用 Anthropic Skill：
|
1 2 3 4 5 6 7 8 9 10 |
ChatResponse response = chatModel.call( new Prompt( "生成一份2025年第一季度的销售数据Excel表，包含产品名称、销量、营收三列。", AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skill(AnthropicSkill.XLSX) .maxTokens(4096) .build() ) ); |
底层实现中，Spring AI 会自动添加代码执行工具和必备的公测请求头。Claude 处理请求并生成电子表格后，会返回包含文件 ID 的响应结果。
启用多个Skill
针对复杂的业务流程，可同时启用多个 Skill：
|
1 2 3 4 5 6 |
AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skill(AnthropicSkill.XLSX) .skill(AnthropicSkill.PPTX) .maxTokens(8192) .build() |
也可使用便捷的 skills() 方法批量添加：
|
1 2 3 4 5 |
AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skills("xlsx", "pptx") .maxTokens(8192) .build() |
claude 会根据输出内容的不同部分，自动匹配合适的文档格式。
注意： 每个请求最多可启用 8 个 Skill ，该限制会在构建时校验，并抛出清晰的错误提示。
结合 ChatClient API 使用
Anthropic Skill 可与 Spring AI 流式 ChatClient API 无缝协同使用：
|
1 2 3 4 5 6 7 8 9 10 |
String content = ChatClient.create(chatModel) .prompt() .user("生成一份公司产品路线图的Word文档") .options(AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skill(AnthropicSkill.DOCX) .maxTokens(4096) .build()) .call() .content(); |
下载生成的文件
生成的文件会在 Anthropic Files API 中保留 24 小时。Spring AI 提供了 AnthropicSkillsResponseHelper 工具类用于提取文件 ID，同时通过 AnthropicApi 提供文件操作的相关方法。
claude 生成文件后，文件 ID 会嵌入多层嵌套的响应结构中（最深可达 4 层），AnthropicSkillsResponseHelper 可通过递归检索，从任意深度提取文件 ID。
单个文件提取与下载
代码如下：
|
1 2 3 4 5 6 7 8 |
List<String> fileIds = AnthropicSkillsResponseHelper.extractFileIds(response); for (String fileId : fileIds) { FileMetadata metadata = anthropicApi.getFileMetadata(fileId); byte[] content = anthropicApi.downloadFile(fileId); Files.write(Path.of(metadata.filename()), content); } |
多文件批量下载
针对返回多个文件的响应，可使用批量下载方法：
|
1 2 3 4 |
Path targetDir = Path.of("generated-docs"); List<Path> savedFiles = AnthropicSkillsResponseHelper.downloadAllFiles( response, anthropicApi, targetDir ); |
自定义 Skill
自定义 Skill 支持将企业自有业务规则封装为可复用的模块，让 Claude 在文档生成过程中自动应用，典型应用场景包括：
- 企业品牌规范（页眉、页脚、水印、企业 logo）；
- 合规要求（免责声明、保密通知）；
- 文档模板（标准结构、格式规范）；
- 领域专业知识（行业术语、专属计算公式）。
自定义 Skill 以 SKILL.md 文件的形式上传至 Anthropic 工作空间，上传后团队所有成员均可使用，且可与任意预构建 Skill 组合搭配。
Skill 文件结构
所有自定义 Skill 均需包含一个带 YAML 前置元数据的 SKILL.md 文件，示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
--- name: document-watermark description: 所有生成的文档均必须添加该强制品牌标识——为文档添加ACME公司页眉和Document Forge页脚 --- # 文档水印规范 ## 页眉要求 所有文档顶部需醒目显示「ACME CORPORATION」： - Excel：A1单元格，加粗，跨数据列合并； - PowerPoint：首页页眉显示，所有幻灯片添加页脚； - Word/PDF：添加至文档页眉区域。 ## 页脚要求 所有文档底部需添加「由Document Forge生成 | 机密」： - Excel：数据最后一行下方的行； - PowerPoint：所有幻灯片的页脚； - Word/PDF：添加至文档页脚区域。 ## 校验要求 完成文档生成前，必须执行以下校验： 1. 确认ACME公司页眉已添加； 2. 确认Document Forge页脚已添加； 3. 补充所有缺失的标识后，再保存文档。 本品牌标识为合规强制要求，必须严格执行。 |
元数据中的 description 字段用于告知 Claude 何时应用该Skill，建议表述明确，使用 “必须“ “强制“ 等词汇，确保 Skill 被稳定触发。
自定义 Skill 元数据字段的规范要求：
| 字段 | 要求 |
|---|---|
name |
最长 64 个字符，仅允许小写字母、数字、连字符 |
description |
最长 1024 个字符，不能为空 |
上传自定义Skill
使用 Anthropic API 上传自定义 Skill 文件，示例请求如下：
|
1 2 3 4 5 6 |
curl -X POST "https://api.anthropic.com/v1/skills" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: skills-2025-10-02" \ -F "display_title=Document Watermark" \ -F "files[]=@SKILL.md;filename=document-watermark/SKILL.md" |
注意请求格式： 文件参数需使用 files[]= 格式，且 filename 必须包含与 YAML 前置元数据中 name 字段一致的目录名。
接口响应示例：
|
1 2 3 4 5 6 |
{ "id": "skill_01WatermarkXyz123", "display_title": "Document Watermark", "source": "custom", "latest_version": "1765845644409101" } |
响应结果中的 id 即为该自定义 Skill 的唯一标识。在 Spring AI 中通过该 ID 调用 Skill 。
使用自定义Skill
通过统一的 skill() 方法，传入自定义 Skill ID 即可启用，支持与预构建 Skill 组合使用：
|
1 2 3 4 5 6 7 8 9 10 11 |
ChatResponse response = chatModel.call( new Prompt( "生成一份季度销售报告，包含每月的营收、支出和利润数据", AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skill(AnthropicSkill.XLSX) .skill("skill_01WatermarkXyz123") .maxTokens(8192) .build() ) ); |
上述代码中，Claude 会同时应用两款 Skill： XLSX 预构建 Skill 实现电子表格生成，自定义水印 Skill 自动添加企业品牌标识。
Skill 版本固定
生产环境部署时，建议将自定义 Skill 固定为指定版本，避免因为 Skill 更新引发业务异常：
|
1 2 3 4 5 6 7 |
AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skill(AnthropicSkill.XLSX) .skill("skill_01WatermarkXyz123") // 使用最新版本 .skill("skill_02LegalCompliance", "1765845644409101") // 固定指定版本 .maxTokens(8192) .build() |
建议生产环境使用固定版本，开发环境使用默认的最新版本。
示例：文档生成服务
以下是一个完整的服务示例，整合了 Anthropic 预构建 Skill 和 自定义 Skill ，实现可配置的文档生成能力：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
@Service public class DocumentGenerationService { private final AnthropicChatModel chatModel; private final AnthropicApi anthropicApi; @Value("${app.custom-skill-id:}") private String watermarkSkillId; public DocumentGenerationService(AnthropicChatModel chatModel, AnthropicApi anthropicApi) { this.chatModel = chatModel; this.anthropicApi = anthropicApi; } public byte[] generate(String prompt, AnthropicSkill documentType, boolean applyBranding) { AnthropicChatOptions.Builder builder = AnthropicChatOptions.builder() .model("claude-sonnet-4-5") .skill(documentType) .maxTokens(8192); // 可选启用自定义品牌水印 Skill if (applyBranding && StringUtils.hasText(watermarkSkillId)) { builder.skill(watermarkSkillId); } ChatResponse response = chatModel.call( new Prompt(prompt, builder.build()) ); List<String> fileIds = AnthropicSkillsResponseHelper.extractFileIds(response); if (fileIds.isEmpty()) { throw new DocumentGenerationException("未生成任何文件"); } return anthropicApi.downloadFile(fileIds.get(0)); } } |
该实现模式让自定义 Skill 成为可选能力 — 当未配置 Skill ID 时，应用仅通过预构建 Skill 完成文档生成，保证了业务的兼容性。
自定义 Skill 开发技巧
在开发水印 Skill 的实践中，总结了几个实用技巧，列在下面以供参考：
- 使用强语气表述： 希望 Claude 稳定执行某条规则时，使用“必须“、“强制“等词汇能提升执行效果，具体可根据 Skill 场景调整；
- 按格式拆分指令： 自定义 Skill 可与任意预构建 Skill 组合，建议为 Excel、PowerPoint、Word、PDF 分别编写专属执行指令；
- 添加校验清单： 在 Skill 中增加校验环节，要求 Claude 完成文档生成前检查规则执行情况，可有效避免指令遗漏。
快速开始
步骤一：引入 Spring AI Anthropic 启动依赖
将以下依赖添加到 pom 文件：
|
1 2 3 4 |
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-anthropic</artifactId> </dependency> |
步骤二：配置 Anthropic 密钥
在配置文件中添加如下配置：
|
1 2 |
spring.ai.anthropic.api-key=${ANTHROPIC_API_KEY} spring.ai.anthropic.chat.options.model=claude-sonnet-4-5 |
速查指南
关键参数
| 特性 | 取值 |
|---|---|
| 支持的模型 | Claude Sonnet 4、Sonnet 4.5、Opus 4 |
| 单请求最大Skill数 | 8 个 |
| 文件有效期 | 24 小时 |
| 推荐最大令牌数 | 生成复杂文档建议设置为 4096 及以上 |
核心方法
| 方法 | 描述 |
|---|---|
.skill(AnthropicSkill) |
添加预构建 Skill（XLSX、PPTX、DOCX、PDF） |
.skill(String) |
通过 ID 或名称添加Skill，自动识别预制 / 自定义类型 |
.skill(String, String) |
添加Skill并固定指定版本 |
.skills(String...) |
批量添加多个Skill |
.skills(List<String>) |
通过列表批量添加Skill |
示例应用
这里是Spring 提供的一个示例应用：document-forge。通过这个示例应用可体验上述介绍的所有 Anthropic Skill 功能，该应用提供可视化网页界面，支持：
- 选择文档格式（Excel、 PowerPoint、 Word、 PDF），通过自然语言描述生成需求；
- 上传源文件实现内容转换，例如将文本文件转为格式化的电子表格、将会议记录转为演示文稿；
- 启用自定义品牌标识，查看自定义 Skill 为生成文档添加页眉、页脚和水印的效果；
- 通过 Files API 集成，直接下载生成的文档；
- 针对演示文稿等耗时较长的请求，支持异步生成。
该示例应用底层实现了本文的核心设计模式：通过 AnthropicChatOptions 配置 Skill、使用 AnthropicSkillsResponseHelper 提取文件 ID、通过 AnthropicApi 下载文件。
相关拓展：Spring AI 通用智能体 Skill
上面介绍的 Anthropic Skill 是厂商专属的功能，核心能力为生成 Excel、PowerPoint 等实际文档文件；而 Spring AI 同时提供了通用智能体 Skill，可适配任意大模型平台。
Spring AI 智能体相关的模式都封装在 spring-ai-agent-utils 工具包中，可与这里介绍的 Anthropic 专属 Skill 互补使用。
核心选型原则： 需要生成实际文档时，使用 Anthropic Skill；需要可移植、独立于大模型的智能体能力时，使用通用智能体 Skill。
总结
Spring AI 为 Anthropic 智能体 Skill API 提供了简洁高效的集成方案，通过统一的 skill() 方法即可调用预构建 Skill 和 自定义 Skill ，框架自动处理代码执行工具、公测请求头、文件提取等复杂细节。
如需查看完整的 API 文档，可参考 Spring AI Anthropic Chat reference 。
关于自定义 Skill 的开发，可参考 Anthropic 官方的 Anthropic Skill文档 以及 Skill 开发指南 。
END！！！
发表评论