Add Skills API support with container parameter and bash code execution content types

[Copilot]

This PR adds comprehensive support for the Anthropic Skills API, enabling Claude to use built-in tools like PowerPoint, Excel, Word, and PDF generation through code execution in containerized environments.

What's New

Container and Skills Support

The SDK now supports the container parameter in message requests, allowing you to specify skills that Claude can use:

var container = new Container
{
    Skills = new List<Skill>
    {
        new Skill
        {
            Type = "anthropic",
            SkillId = "pptx",  // Built-in PowerPoint skill
            Version = "latest"
        }
    }
};

var parameters = new MessageParameters
{
    Model = AnthropicModels.Claude4Sonnet,
    MaxTokens = 4096,
    Container = container,
    Messages = new List<Message>
    {
        new Message(RoleType.User, "Create a presentation about renewable energy")
    }
};

var response = await client.Messages.GetClaudeMessageAsync(parameters);

Container Reuse

Containers can be reused across multiple requests to maintain state:

// First request creates the container
var response1 = await client.Messages.GetClaudeMessageAsync(parameters);

// Subsequent requests can reuse the same container
var containerWithId = new Container
{
    Id = response1.Container.Id,  // Reuse the container ID
    Skills = new List<Skill>
    {
        new Skill { Type = "anthropic", SkillId = "xlsx", Version = "latest" }
    }
};

Bash Code Execution Content Types

Added four new content types to handle skill execution results:

• BashCodeExecutionToolResultContent - Top-level wrapper containing tool_use_id and execution results
• BashCodeExecutionResultContent - Contains stdout, stderr, return_code, and file outputs
• BashCodeExecutionOutputContent - Represents individual file outputs with file IDs for downloading via Files API
• BashCodeExecutionToolResultErrorContent - Error responses with specific error codes

These types properly deserialize responses from the API and provide strongly-typed access to execution results.

Implementation Details

New Classes

• Container - Request parameter with Skills array and optional Id for reuse
• Skill - Defines individual skills with type ("anthropic" or "custom"), skill_id, and version
• ContainerResponse - Response property containing the container ID
• Four bash code execution content types with proper JSON serialization

Updated Classes

• MessageParameters - Added Container property
• MessageResponse - Added Container property
• ContentType enum - Added 4 new bash code execution types
• ContentConverter - Extended to deserialize new content types

Built-in Skills

The following Anthropic skills are available:

• pptx - Create and edit PowerPoint presentations
• xlsx - Create and analyze Excel spreadsheets
• docx - Create and edit Word documents
• pdf - Generate PDF documents

Custom skills are also supported by specifying Type = "custom".

Testing

Added comprehensive test suite with 8 unit tests covering:

• Container serialization with skills
• Container ID for reuse scenarios
• Multiple skills (up to 8 per request)
• Custom skills
• Bash code execution content types
• Serialization/deserialization validation

All tests pass successfully.

Documentation

Added detailed Skills section to README.md with:

• Basic usage examples
• Container reuse patterns
• Built-in and custom skills documentation
• Working with skill execution results
• Required beta headers information

Beta Headers Required

Skills functionality requires the following beta headers:

• code-execution-2025-08-25 - Enables code execution (required for Skills)
• skills-2025-10-02 - Enables Skills API
• files-api-2025-04-14 - For uploading/downloading files to/from containers

---

Note: File API support for downloading skill-generated files will be added in a subsequent PR.

Original prompt

Add skills support to response generation.

Prerequisites

To use Skills, you need:

• Anthropic API key from the Console
• Beta headers:

• code-execution-2025-08-25 - Enables code execution (required for Skills)
• skills-2025-10-02 - Enables Skills API
• files-api-2025-04-14 - For uploading/downloading files to/from container

• Code execution tool enabled in your requests

Implementation Notes

Skills are specified using the container parameter in the Messages API. You can include up to 8 Skills per request.
The structure is identical for both Anthropic and custom Skills—specify the required type and skill_id, and optionally include version to pin to a specific version:

Here's an example of a raw request passing skills:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: code-execution-2025-08-25,skills-2025-10-02" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 4096,
    "container": {
      "skills": [
        {
          "type": "anthropic",
          "skill_id": "pptx",
          "version": "latest"
        }
      ]
    },
    "messages": [{
      "role": "user",
      "content": "Create a presentation about renewable energy"
    }],
    "tools": [{
      "type": "code_execution_20250825",
      "name": "code_execution"
    }]
  }'

These are the built-in anthropic skills:

PowerPoint (pptx): Create and edit presentations
Excel (xlsx): Create and analyze spreadsheets
Word (docx): Create and edit documents
PDF (pdf): Generate PDF documents

For type custom skills the skill_id is a string (gotten elsewhere).

Response content blocks can now have type bash_code_execution_tool_result. Here are the relevant new types in TypeScript for reference:

export interface BetaBashCodeExecutionOutputBlock {
  file_id: string;

  type: 'bash_code_execution_output';
}

export interface BetaBashCodeExecutionOutputBlockParam {
  file_id: string;

  type: 'bash_code_execution_output';
}

export interface BetaBashCodeExecutionResultBlock {
  content: Array<BetaBashCodeExecutionOutputBlock>;

  return_code: number;

  stderr: string;

  stdout: string;

  type: 'bash_code_execution_result';
}

export interface BetaBashCodeExecutionResultBlockParam {
  content: Array<BetaBashCodeExecutionOutputBlockParam>;

  return_code: number;

  stderr: string;

  stdout: string;

  type: 'bash_code_execution_result';
}

export interface BetaBashCodeExecutionToolResultBlock {
  content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock;

  tool_use_id: string;

  type: 'bash_code_execution_tool_result';
}

export interface BetaBashCodeExecutionToolResultBlockParam {
  content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam;

  tool_use_id: string;

  type: 'bash_code_execution_tool_result';

  /**
   * Create a cache control breakpoint at this content block.
   */
  cache_control?: BetaCacheControlEphemeral | null;
}

export interface BetaBashCodeExecutionToolResultError {
  error_code:
    | 'invalid_tool_input'
    | 'unavailable'
    | 'too_many_requests'
    | 'execution_time_exceeded'
    | 'output_file_too_large';

  type: 'bash_code_execution_tool_result_error';
}

export interface BetaBashCodeExecutionToolResultErrorParam {
  error_code:
    | 'invalid_tool_input'
    | 'unavailable'
    | 'too_many_requests'
    | 'execution_time_exceeded'
    | 'output_file_too_large';

  type: 'bash_code_execution_tool_result_error';
}

Example type script code to get files from a skill use result:

// Step 2: Extract file IDs from the response
function extractFileIds(response: any): string[] {
  const fileIds: string[] = [];
  for (const item of response.content) {
    if (item.type === 'bash_code_execution_tool_result') {
      const contentItem = item.content;
      if (contentItem.type === 'bash_code_execution_result') {
        for (const file of contentItem.content) {
          if ('file_id' in file) {
            fileIds.push(file.file_id);
          }
        }
      }
    }
  }
  return fileIds;
}

We'll add the file endpoint support in a subsequent change. But for context this is how it looks in typescript:

// Step 3: Download the file using Files API
const fs = require('fs');
for (const fileId of extractFileIds(response)) {
  const fileMetadata = await client.beta.files.retrieve_metadata(fileId, {
    betas: ['files-api-2025-04-14']
  });
  const fileContent = await client.beta.files.download(fileId, {
    betas: ['files-api-2025-04-14']
  });

  // Step 4: Save to disk
  fs.writeFileSync(fileMetadata.filename, Buffer.from(await fileContent.arrayBuffer()));
  console.log(`Downloaded: ${fileMetadata.filename}`);
}

Containers and Container Ids

Responses can now have a container id. These can be used to reuse containers across request as per this example (in t...

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.