Agent Skills in the SDK

Overview

Agent Skills extend Claude with specialized capabilities that Claude autonomously invokes when relevant. Skills are packaged as SKILL.md files containing instructions, descriptions, and optional supporting resources. For comprehensive information about Skills, including benefits, architecture, and authoring guidelines, see the Agent Skills overview.

How Skills Work with the 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
Filtered via the skills option: discovered skills are enabled by default. Pass a list of skill names, "all", or [] to control which are available in the session

Unlike subagents (which can be defined programmatically), Skills must be created as filesystem artifacts. The SDK does not provide a programmatic API for registering Skills.

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.

Using Skills with the SDK

Set the skills option on query() to control which Skills are available to the session. When omitted, discovered Skills are enabled and the Skill tool is available, matching CLI behavior. Pass "all" to enable every discovered Skill, a list of Skill names to enable only those, or [] to disable all. 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 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", "project"],  # Load Skills from filesystem
        skills="all",  # Enable every discovered Skill
        allowed_tools=["Read", "Write", "Bash"],
    )

    async for message in query(
        prompt="Help me process this PDF document", options=options
    ):
        print(message)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me process this PDF document",
  options: {
    cwd: process.cwd(), // .claude/skills/ here or in a parent directory
    settingSources: ["user", "project"], // Load Skills from filesystem
    skills: "all", // Enable every discovered Skill
    allowedTools: ["Read", "Write", "Bash"]
  }
})) {
  console.log(message);
}

Near the start of the stream, the SDK yields a system message with subtype init. Check its skills array to confirm your Skills loaded before Claude starts working. The array lists user-invocable Skills only. A Skill with user-invocable: false in its frontmatter loads and remains available to Claude but doesn’t appear in the array. To enable only specific Skills, pass their names. Names match the name field in SKILL.md or the Skill’s directory name. Use plugin:skill for plugin-provided Skills.

Import statements from the first example are assumed in the following code snippets.

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

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

The list takes exact Skill names only. In the TypeScript SDK, query() throws before starting the Claude Code process when a name can’t work as an exact Skill name. In the Python SDK, query() raises ValueError in the same cases, for example:

An empty name
A name containing parentheses, commas, or control characters
A name padded with whitespace
A wildcard form such as a bare * or a :* suffix

To enable every discovered Skill, pass skills: "all" rather than a wildcard. The skills option is a context filter, not a sandbox. Unlisted Skills are hidden from the model and rejected by the Skill tool, but their files remain on disk and are reachable through Read and Bash.

Skill Locations

Skills are loaded from filesystem directories based on your settingSources/setting_sources configuration:

Project Skills (.claude/skills/): Shared with your team via git - loaded when setting_sources includes "project"
User Skills (~/.claude/skills/): Personal Skills across all projects - loaded when setting_sources includes "user"
Plugin Skills: Bundled with installed Claude Code plugins

Creating Skills

Create each Skill as a directory containing a SKILL.md file with YAML frontmatter and Markdown content. The description field determines when Claude invokes your Skill. Example directory structure:

Agent SDK

Core concepts

Input and output

Extend with tools

Customize behavior

Control and observability

Deployment

SDK references

Overview

How Skills Work with the SDK

Using Skills with the SDK

Skill Locations

Creating Skills

​Overview

​How Skills Work with the SDK

​Using Skills with the SDK

​Skill Locations

​Creating Skills

Overview

How Skills Work with the SDK

Using Skills with the SDK

Skill Locations

Creating Skills