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. Each skill you add incurs a modest cost on the session's context window, adding instructions and metadata that help the model use the skill. Learn more in the Agent Skills overview.

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, pass the anthropic-beta: skills-2025-10-02 header explicitly. The CLI and 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

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 500 skills total, counted across every agent in the session (see Multiagent orchestration).

Each entry in the skills array uses the following fields:

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



Next steps