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.

Skills reach your agent in two ways: attach them through the agent's skills array, or load them from a GitHub repository mounted on the session. Attached skills come in two types. All skills 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, counted as the deduplicated set 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



Load skills from a GitHub repository

Skills can also live in your codebase. When a session mounts a repository through the github_repository resource, the repository's root .claude/skills directory is scanned at session start, and each skill found there becomes available to the agent. No upload and no entry in the agent's skills array are required. The agent sees each discovered skill's name, description, and path in the sandbox, and reads the skill's SKILL.md when a task matches, including any scripts and resources the skill ships. Discovery relies on the agent's read tool from the agent toolset, which is enabled by default; an agent with read disabled doesn't load repository skills.

Discovery finds skills at exactly .claude/skills/<skill-name>/SKILL.md, one directory level deep at the repository root:

• your-repo/
  • .claude/
    • skills/
      • code-review/
        • SKILL.md
      • release-process/
        • SKILL.md
        • scripts/
          • run_checks.sh
  • src/

Locations that don't match this layout aren't discovered at session start:

• .claude/skills/SKILL.md: a SKILL.md with no skill directory around it
• .claude/skills/tools/code-review/SKILL.md: nested more than one directory level deep
• skills/code-review/SKILL.md: a skills directory outside .claude

A .claude/skills directory elsewhere in the repository, such as inside a package subdirectory, isn't announced at session start; those skills can still surface when the agent reads files under that subtree.

Repository skills use the same SKILL.md format as the custom skills you upload. For the format and authoring guidance, see Agent Skills and Skill authoring best practices.

To load skills from a repository, create a session that mounts it. This is the same request shown in Accessing GitHub; mount_path is optional and defaults to /workspace/<repo-name>:

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --transform id --raw-output <<'EOF'
resources:
  - type: github_repository
    url: https://github.com/org/repo
    mount_path: /workspace/repo
    authorization_token: ghp_your_github_token
EOF
)

For private repositories, the resource's authorization_token must have access to the repository. This is the same personal access token flow used for any repository mount; see Accessing GitHub.

Discovered skills follow the checked-out state of the repository: the checkout branch or commit when the resource sets one, otherwise the repository's default branch. The scan runs once, when the session starts. Commits pushed mid-session are not picked up; to load updated skills, start a new session.

Repository skills work alongside skills attached through the agent's skills array. If a repository skill shares a name with an attached skill, or with a skill from another mounted repository, both are available; each is announced with its own path.



Next steps