Using Agent Skills via the Claude API: Office files, PDFs and your own skills

Skills aren't only for Claude Code. Through the Messages API, your application can attach skills to Claude too: use Anthropic's pre-built skills to create PowerPoint, Excel, Word and PDF files, or upload your own skills containing your company's workflows. Thanks to progressive disclosure, you can attach many skills without bloating each request's context.

What you need

• The code execution tool in tools: skills run in a code execution container.
• The container.skills parameter: a list of skills, up to 20 per request.
• Each skill has a type (anthropic or custom), a skill_id and an optional version (pinned, or latest).

{
  "model": "claude-opus-5-5",
  "max_tokens": 4096,
  "container": {
    "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
  },
  "messages": [{"role": "user", "content": "Create a 5-slide deck on Q3 results"}],
  "tools": [{"type": "code_execution_20250825", "name": "code_execution"}]
}

Pre-built vs custom skills

Uploading a custom skill

• Call POST /v1/skills (multipart); new versions go to POST /v1/skills/{skill_id}/versions.
• A zip or individual files with SKILL.md at the root; under 30 MB uncompressed.
• Frontmatter: name up to 64 characters, lowercase letters, numbers and hyphens only, no reserved words anthropic or claude; description up to 1,024 characters.
• Each version is a full snapshot: files you don't upload aren't carried over from the previous version.
• At runtime, skill files live at /skills/{skill-name}/ in the container.

Getting the output files

Files a skill creates appear as file_id values in the code execution results. Use the Files API: fetch the metadata for the filename, then download the content. For multi-turn conversations, reuse response.container.id to keep state; on stop_reason: "pause_turn", send the response back so Claude can continue.

Why it doesn't eat context

Initially Claude receives only each skill's name and description. The full content loads only when a skill is relevant to the request. That's why the description decides whether a skill gets used at the right moment.

Risks and caveats

• Workspace scope: custom skills belong to the whole workspace; any API key with workspace access can read, use or delete them. For multi-tenant apps, the docs recommend one workspace per tenant.
• Skills run code: only upload skills you've read and trust; check bundled scripts.
• Cost: code execution and generated files have costs beyond tokens; check current pricing.
• Pin versions in production: latest is convenient for experiments but can change behaviour unexpectedly.

How to apply it

• Dev: Replace home-grown Office file generation with the pre-built xlsx/pptx skills; store files via the Files API.
• Tech Lead: Package repeated business workflows (report formats, checklists) as versioned custom skills, reviewed like code.
• PM: An "export to slides/Excel" feature can now ship quickly without a team building file-handling libraries.