Skills

Skills are reusable, filesystem-based resources that give your agent domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist. Unlike prompts (conversation-level instructions for one-off tasks), skills load on demand, only impacting the context window when needed.

You can attach two types of skill. Both work the same way: your agent invokes them automatically when they are relevant to the task.

• Pre-built Anthropic skills: Common document tasks such as PowerPoint, Excel, Word, and PDF handling (pptx, xlsx, docx, pdf).
• Custom skills: Skills you author and upload to your workspace.

To learn how to author custom skills, see Agent Skills and Skill authoring best practices. To upload a custom skill to your workspace, see Create a custom skill.



Create a custom skill

A custom skill is a directory containing a SKILL.md file plus any supporting files, uploaded to your workspace as a zip archive or as individual files. Creating the skill returns the skill_* ID you reference when attaching it to an agent. Anthropic pre-built skills are already available in every workspace and don't require this step. To use only pre-built skills, skip to Attach skills to an agent.

When you call the Skills API directly with cURL or the CLI, pass the anthropic-beta: skills-2025-10-02 header explicitly. The SDKs send it automatically.

These examples omit the optional display_title field, so the skill's title is derived from SKILL.md. An explicitly passed display_title must be unique among the custom skills in your workspace.

ant beta:skills create \
  --file example_skill.zip \
  --beta skills-2025-10-02

To list, retrieve, delete, and version custom skills, see Managing custom skills. For the full request and response schemas, see the Create Skill API reference. Skill bundles upload directly to the Skills API rather than through the Files API.



Attach skills to an agent

Attach skills when creating an agent. Each session supports up to 20 skills total, counted across every agent in the session (see Multi-agent sessions).

Each entry in the skills array uses the following fields:

ant beta:agents create <<'YAML'
name: Financial Analyst
model: claude-opus-4-8
system: You are a financial analysis agent.
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_abc123
    version: latest
YAML



Next steps