Add Claude Skills integration with Files API support

Integrate Anthropic's pre-built Skills for document generation. Skills
enable Claude to create actual downloadable files rather than just
describing them.

Supported skills:
- XLSX: Generate Excel spreadsheets
- PPTX: Create PowerPoint presentations
- DOCX: Generate Word documents
- PDF: Create PDF files

Example usage:
  AnthropicChatOptions.builder()
    .anthropicSkill(AnthropicSkill.XLSX)
    .build()

Generated files can be downloaded via the Files API using
SkillsResponseHelper to extract file IDs from responses.

Breaking change:
- ContentBlock.content type changed from String to Object to support
  nested JSON structures in Skills responses

Signed-off-by: Mark Pollack <mark.pollack@broadcom.com>

Author: markpollack

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatModel.java

@@ -583,6 +583,14 @@ Prompt buildRequestPrompt(Prompt prompt) {
 			else if (this.defaultOptions.getCitationDocuments() != null) {
 				requestOptions.setCitationDocuments(this.defaultOptions.getCitationDocuments());
 			}
+
+			// Merge skillContainer that is Json-ignored
+			if (runtimeOptions.getSkillContainer() != null) {
+				requestOptions.setSkillContainer(runtimeOptions.getSkillContainer());
+			}
+			else if (this.defaultOptions.getSkillContainer() != null) {
+				requestOptions.setSkillContainer(this.defaultOptions.getSkillContainer());
+			}
 		}
 		else {
 			requestOptions.setHttpHeaders(this.defaultOptions.getHttpHeaders());
@@ -591,6 +599,7 @@ else if (this.defaultOptions.getCitationDocuments() != null) {
 			requestOptions.setToolCallbacks(this.defaultOptions.getToolCallbacks());
 			requestOptions.setToolContext(this.defaultOptions.getToolContext());
 			requestOptions.setCitationDocuments(this.defaultOptions.getCitationDocuments());
+			requestOptions.setSkillContainer(this.defaultOptions.getSkillContainer());
 		}
 
 		ToolCallingChatOptions.validateToolCallbacks(requestOptions.getToolCallbacks());
@@ -649,6 +658,56 @@ ChatCompletionRequest createRequest(Prompt prompt, boolean stream) {
 			requestOptions.setHttpHeaders(headers);
 		}
 
+		// Add Skills container from options if present
+		AnthropicApi.SkillContainer skillContainer = null;
+		if (requestOptions != null && requestOptions.getSkillContainer() != null) {
+			skillContainer = requestOptions.getSkillContainer();
+		}
+		else if (this.defaultOptions.getSkillContainer() != null) {
+			skillContainer = this.defaultOptions.getSkillContainer();
+		}
+
+		if (skillContainer != null) {
+			request = ChatCompletionRequest.from(request).container(skillContainer).build();
+
+			// Skills require the code_execution tool to be enabled
+			// Add it if not already present
+			List<AnthropicApi.Tool> existingTools = request.tools() != null ? new ArrayList<>(request.tools())
+					: new ArrayList<>();
+			boolean hasCodeExecution = existingTools.stream().anyMatch(tool -> "code_execution".equals(tool.name()));
+
+			if (!hasCodeExecution) {
+				existingTools.add(new AnthropicApi.Tool(AnthropicApi.CODE_EXECUTION_TOOL_TYPE, "code_execution", null,
+						null, null));
+				request = ChatCompletionRequest.from(request).tools(existingTools).build();
+			}
+
+			// Skills require three beta headers: skills, code-execution, and files-api
+			Map<String, String> headers = requestOptions != null ? new HashMap<>(requestOptions.getHttpHeaders())
+					: new HashMap<>();
+			String requiredBetas = AnthropicApi.BETA_SKILLS + "," + AnthropicApi.BETA_CODE_EXECUTION + ","
+					+ AnthropicApi.BETA_FILES_API;
+			String existingBeta = headers.get("anthropic-beta");
+			if (existingBeta != null) {
+				if (!existingBeta.contains(AnthropicApi.BETA_SKILLS)) {
+					existingBeta = existingBeta + "," + AnthropicApi.BETA_SKILLS;
+				}
+				if (!existingBeta.contains(AnthropicApi.BETA_CODE_EXECUTION)) {
+					existingBeta = existingBeta + "," + AnthropicApi.BETA_CODE_EXECUTION;
+				}
+				if (!existingBeta.contains(AnthropicApi.BETA_FILES_API)) {
+					existingBeta = existingBeta + "," + AnthropicApi.BETA_FILES_API;
+				}
+				headers.put("anthropic-beta", existingBeta);
+			}
+			else {
+				headers.put("anthropic-beta", requiredBetas);
+			}
+			if (requestOptions != null) {
+				requestOptions.setHttpHeaders(headers);
+			}
+		}
+
 		return request;
 	}
 
@@ -845,7 +904,8 @@ private List<AnthropicApi.Tool> addCacheToLastTool(List<AnthropicApi.Tool> tools
 			AnthropicApi.Tool tool = tools.get(i);
 			if (i == tools.size() - 1) {
 				// Add cache control to last tool
-				tool = new AnthropicApi.Tool(tool.name(), tool.description(), tool.inputSchema(), cacheControl);
+				tool = new AnthropicApi.Tool(tool.type(), tool.name(), tool.description(), tool.inputSchema(),
+						cacheControl);
 				cacheEligibilityResolver.useCacheBlock();
 			}
 			modifiedTools.add(tool);

models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/AnthropicChatOptions.java

@@ -115,6 +115,15 @@ public void setCacheOptions(AnthropicCacheOptions cacheOptions) {
 	@JsonIgnore
 	private Map<String, String> httpHeaders = new HashMap<>();
 
+	/**
+	 * Container for Claude Skills to make available in this request.
+	 * Skills are collections of instructions, scripts, and resources that
+	 * extend Claude's capabilities for specific domains.
+	 * Maximum of 8 skills per request.
+	 */
+	@JsonIgnore
+	private AnthropicApi.SkillContainer skillContainer;
+
 	// @formatter:on
 
 	public static Builder builder() {
@@ -141,9 +150,18 @@ public static AnthropicChatOptions fromOptions(AnthropicChatOptions fromOptions)
 			.cacheOptions(fromOptions.getCacheOptions())
 			.citationDocuments(fromOptions.getCitationDocuments() != null
 					? new ArrayList<>(fromOptions.getCitationDocuments()) : null)
+			.skillContainer(fromOptions.getSkillContainer())
 			.build();
 	}
 
+	public AnthropicApi.SkillContainer getSkillContainer() {
+		return this.skillContainer;
+	}
+
+	public void setSkillContainer(AnthropicApi.SkillContainer skillContainer) {
+		this.skillContainer = skillContainer;
+	}
+
 	@Override
 	public String getModel() {
 		return this.model;
@@ -351,15 +369,16 @@ public boolean equals(Object o) {
 				&& Objects.equals(this.toolContext, that.toolContext)
 				&& Objects.equals(this.httpHeaders, that.httpHeaders)
 				&& Objects.equals(this.cacheOptions, that.cacheOptions)
-				&& Objects.equals(this.citationDocuments, that.citationDocuments);
+				&& Objects.equals(this.citationDocuments, that.citationDocuments)
+				&& Objects.equals(this.skillContainer, that.skillContainer);
 	}
 
 	@Override
 	public int hashCode() {
 		return Objects.hash(this.model, this.maxTokens, this.metadata, this.stopSequences, this.temperature, this.topP,
 				this.topK, this.toolChoice, this.thinking, this.toolCallbacks, this.toolNames,
 				this.internalToolExecutionEnabled, this.toolContext, this.httpHeaders, this.cacheOptions,
-				this.citationDocuments);
+				this.citationDocuments, this.skillContainer);
 	}
 
 	public static final class Builder {
@@ -501,6 +520,80 @@ public Builder addCitationDocument(CitationDocument document) {
 			return this;
 		}
 
+		/**
+		 * Set the Skills container for this request.
+		 * @param skillContainer Container with skills to make available
+		 * @return Builder for method chaining
+		 */
+		public Builder skillContainer(AnthropicApi.SkillContainer skillContainer) {
+			this.options.setSkillContainer(skillContainer);
+			return this;
+		}
+
+		/**
+		 * Add a single skill to the request. Creates a SkillContainer if one doesn't
+		 * exist.
+		 * @param skill Skill to add
+		 * @return Builder for method chaining
+		 */
+		public Builder skill(AnthropicApi.Skill skill) {
+			Assert.notNull(skill, "Skill cannot be null");
+			if (this.options.skillContainer == null) {
+				this.options.skillContainer = AnthropicApi.SkillContainer.builder().skill(skill).build();
+			}
+			else {
+				// Rebuild container with additional skill
+				List<AnthropicApi.Skill> existingSkills = new ArrayList<>(this.options.skillContainer.skills());
+				existingSkills.add(skill);
+				this.options.skillContainer = new AnthropicApi.SkillContainer(existingSkills);
+			}
+			return this;
+		}
+
+		/**
+		 * Add an Anthropic pre-built skill (xlsx, pptx, docx, pdf).
+		 * @param anthropicSkill Pre-built Anthropic skill to add
+		 * @return Builder for method chaining
+		 */
+		public Builder anthropicSkill(AnthropicApi.AnthropicSkill anthropicSkill) {
+			Assert.notNull(anthropicSkill, "AnthropicSkill cannot be null");
+			return skill(anthropicSkill.toSkill());
+		}
+
+		/**
+		 * Add an Anthropic pre-built skill with specific version.
+		 * @param anthropicSkill Pre-built Anthropic skill to add
+		 * @param version Version of the skill (e.g., "latest", "20251013")
+		 * @return Builder for method chaining
+		 */
+		public Builder anthropicSkill(AnthropicApi.AnthropicSkill anthropicSkill, String version) {
+			Assert.notNull(anthropicSkill, "AnthropicSkill cannot be null");
+			Assert.hasText(version, "Version cannot be empty");
+			return skill(anthropicSkill.toSkill(version));
+		}
+
+		/**
+		 * Add a custom skill by ID.
+		 * @param skillId Custom skill ID
+		 * @return Builder for method chaining
+		 */
+		public Builder customSkill(String skillId) {
+			Assert.hasText(skillId, "Skill ID cannot be empty");
+			return skill(new AnthropicApi.Skill(AnthropicApi.SkillType.CUSTOM, skillId));
+		}
+
+		/**
+		 * Add a custom skill with specific version.
+		 * @param skillId Custom skill ID
+		 * @param version Version of the skill
+		 * @return Builder for method chaining
+		 */
+		public Builder customSkill(String skillId, String version) {
+			Assert.hasText(skillId, "Skill ID cannot be empty");
+			Assert.hasText(version, "Version cannot be empty");
+			return skill(new AnthropicApi.Skill(AnthropicApi.SkillType.CUSTOM, skillId, version));
+		}
+
 		public AnthropicChatOptions build() {
 			this.options.validateCitationConsistency();
 			return this.options;