Extend agents with skills

Agent Skills extend Claude with specialized capabilities that Claude invokes when relevant. Skills are packaged as SKILL.md files containing instructions, descriptions, and optional supporting resources. This page also covers commands in Agent SDK sessions. For comprehensive information about skills, including benefits, architecture, and authoring guidelines, see the Agent Skills overview.

How skills work with the Agent SDK

When using the Claude Agent SDK, skills are:

Defined as filesystem artifacts: you create each skill as a SKILL.md file in its own directory, such as .claude/skills/<name>/SKILL.md
Loaded from filesystem: the SDK loads skills from the filesystem locations governed by settingSources (TypeScript) or setting_sources (Python)
Automatically discovered: once filesystem settings load, the SDK discovers skill metadata at startup from user and project directories, and loads the full content when Claude invokes the skill
Model-invoked: Claude autonomously chooses when to use them based on context
User-invoked: you dispatch a skill directly by sending /<name> in a prompt. See Commands in Agent SDK sessions
Scoped via the skills option: discovered skills are enabled by default. Pass a list of skill names, "all", or [] to control which skills Claude can invoke

Unlike subagents, which you can define in the agents option, you create skills as files on disk. The SDK doesn’t provide a programmatic API for registering them.

Skills are discovered through the filesystem setting sources. With default query() options, the SDK loads user and project sources, so skills in ~/.claude/skills/, <cwd>/.claude/skills/, and .claude/skills/ in any parent directory of <cwd> up to the repository root are available. If you set settingSources explicitly, include 'user' or 'project' to keep skill discovery, or use the plugins option to load skills from a specific path.

Use skills with the Agent SDK

Set the skills option on query() to control which skills Claude can invoke in the session. When omitted, discovered skills are enabled and the Skill tool is available, matching CLI behavior. Pass "all" to let Claude invoke every discovered skill, a list of skill names to allow only those, or [] to let Claude invoke none. For example, to let Claude invoke only two named skills:

options = ClaudeAgentOptions(skills=["pdf", "docx"])

const options = { skills: ["pdf", "docx"] };

Set up skills in a session

When you set skills, the SDK adds the Skill tool to allowedTools automatically. If you also pass an explicit tools list, include "Skill" in that list so Claude can invoke skills. Once configured, Claude automatically discovers skills from the filesystem and invokes them when relevant to the user’s request. The following example enables every discovered skill in a session and pre-approves the tools that skills commonly need. The example sets cwd to the process’s current working directory, so run it from inside a project that has a .claude/skills/ directory in the current directory or any parent up to the repository root:

import asyncio
import os

from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(
        cwd=os.getcwd(),  # .claude/skills/ here or in a parent directory
        setting_sources=["user", 

Agent SDK

Build agents

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

How skills work with the Agent SDK

Use skills with the Agent SDK

Set up skills in a session

​How skills work with the Agent SDK

​Use skills with the Agent SDK

​Set up skills in a session

How skills work with the Agent SDK

Use skills with the Agent SDK

Set up skills in a session