Skills with Claude API

Claude API supports native skills integration.

You do not pass full SKILL.md text in every request.
Instead, you reference skills in the request container and let Claude load them on demand.

Official Integration Model

According to Anthropic docs, skill-enabled API requests require:

1. Code execution tool enabled
2. A container with skill references
3. Required beta headers for skills/code execution

Skills are passed under container.skills and selected by skill_id.

As of February 16, 2026, docs list these beta headers:

• code-execution-2025-08-25
• skills-2025-10-02
• files-api-2025-04-14

Skill Sources in API

You can use:

• Anthropic pre-built skills (for example document skills)
• Custom skills uploaded through the Skills API

For custom skills, package your skill directory (with SKILL.md) and register it via Skills API first, then reference its skill_id in Messages requests.

Minimal Request Shape

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "betas": ["code-execution-2025-08-25", "skills-2025-10-02"],
  "tools": [{ "type": "code_execution_20250825", "name": "code_execution" }],
  "container": {
    "skills": [{ "type": "custom", "skill_id": "sk_...", "version": "latest" }]
  },
  "messages": [{ "role": "user", "content": "Analyze this dataset and summarize trends." }]
}

Constraints and Practical Notes

• Skills are selected from metadata and loaded progressively.
• You can attach multiple skills in one container (currently up to 8 per request).
• If your skills are on local disk, API runtime will not auto-discover them; upload/register first.
• Keep a test harness for representative prompts and expected artifacts.

Best Practices

• Keep descriptions precise so skill routing is reliable.
• Log selected skills and tool calls for auditability.
• Validate downstream artifacts (tables/files/charts) before final output.
• Run cross-model checks if you deploy on multiple Claude models.