Add comprehensive Skills API support

[jamesrochabrun]

Overview

This PR adds full support for Anthropic's Skills API, enabling users to create, manage, and use skills in their SwiftAnthropic applications.

What's New

🎯 Core Features

Container Support

• Add Container parameter to MessageParameter for specifying skills to load
• Add Container response field to MessageResponse for reusing containers across conversations
• Add SkillReference type for referencing both Anthropic-managed and custom skills
• Support for version pinning (specific versions or "latest")

Skills Management

• ✅ Create skills with file uploads (multipart/form-data)
• ✅ List all available skills with filtering (source: custom/anthropic)
• ✅ Retrieve individual skill details
• ✅ Delete skills
• ✅ Full version management (create, list, retrieve, delete)
• ✅ Pagination support for large skill lists

📦 New API Types

Parameters:

• SkillCreateParameter - Create new skills with files
• SkillVersionCreateParameter - Create new skill versions
• SkillFile - File data with metadata for uploads
• ListSkillsParameter - Filter and paginate skill lists
• ListSkillVersionsParameter - Paginate version lists

Responses:

• SkillResponse - Individual skill metadata
• ListSkillsResponse - Paginated skill results
• SkillVersionResponse - Version-specific details
• ListSkillVersionsResponse - Paginated version results

🔧 Implementation

Service Methods (8 new):

func createSkill(_:) async throws -> SkillResponse
func listSkills(parameter:) async throws -> ListSkillsResponse
func retrieveSkill(skillId:) async throws -> SkillResponse
func deleteSkill(skillId:) async throws

func createSkillVersion(skillId:_:) async throws -> SkillVersionResponse
func listSkillVersions(skillId:parameter:) async throws -> ListSkillVersionsResponse
func retrieveSkillVersion(skillId:version:) async throws -> SkillVersionResponse
func deleteSkillVersion(skillId:version:) async throws

Infrastructure:

• Multipart/form-data encoding for file uploads
• New API endpoints: /v1/skills, /v1/skills/{id}, /v1/skills/{id}/versions
• Full AIProxy compatibility with device check support
• Platform support: iOS 15+, macOS 12+, Linux

📱 Example Application Updates

New Skills Demo:

• Interactive SkillsDemoView with UI for testing
• SkillsDemoObservable with example implementations
• Demonstrates listing available skills
• Shows using skills in messages (XLSX spreadsheet example)
• Demonstrates container reuse across multi-turn conversations
• Includes streaming support with skills

Updated Files:

• ApiKeyIntroView - Added Skills beta headers
• OptionsListView - Added "Skills API" option

Usage Example

// List available skills
let skills = try await service.listSkills(parameter: nil)
print("Found \(skills.data.count) skills")

// Create a message using a skill
let parameter = MessageParameter(
    model: .claude37Sonnet,
    messages: [.init(role: .user, content: .text("Create a budget spreadsheet"))],
    maxTokens: 4096,
    tools: [.hosted(type: "code_execution_20250825", name: "code_execution")],
    container: .init(
        skills: [
            .init(type: .anthropic, skillId: "xlsx", version: "latest")
        ]
    )
)

let response = try await service.createMessage(parameter)

// Reuse container in follow-up
let followUp = MessageParameter(
    model: .claude37Sonnet,
    messages: updatedMessages,
    maxTokens: 4096,
    container: .init(
        id: response.container?.id,  // Reuse for performance
        skills: [.init(type: .anthropic, skillId: "xlsx")]
    )
)

Testing

Automated

• ✅ Project builds successfully with no errors
• ✅ All existing tests pass
• ✅ Type-safe implementation with Swift enums

Manual Testing

Run the example app and:

1. Select "Default Anthropic Service"
2. Enter API key with Skills access
3. Choose "Skills API" from the menu
4. Test all three demo buttons

Technical Notes

• Follows existing codebase patterns and conventions
• Consistent documentation style with triple-slash comments
• Proper error handling for all operations
• Snake case conversion handled automatically
• Full backward compatibility maintained

Files Changed

• 10 modified files - Core API support
• 4 new files - Skills parameters, responses, and demos
• +1,242 lines added

Checklist

• Code builds without errors
• Follows existing code style
• Documentation added
• Example app updated
• AIProxy compatibility maintained
• Linux compatibility maintained