Agent Skills in the SDK

Extend Claude with specialized capabilities using Agent Skills in the Claude Agent 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:

1. Defined as filesystem artifacts: you create each Skill as a SKILL.md file in its own directory, such as .claude/skills/<name>/SKILL.md
2. Loaded from filesystem: the SDK loads Skills from the filesystem locations governed by settingSources (TypeScript) or setting_sources (Python)
3. 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
4. Model-invoked: Claude autonomously chooses when to use them based on context
5. 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.

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.

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

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

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:

.claude/skills/processing-pdfs/
└── SKILL.md

For complete guidance on creating Skills, including SKILL.md structure, multi-file Skills, and examples, see:

• Agent Skills in Claude Code: Complete guide with examples
• Agent Skills Best Practices: Authoring guidelines and naming conventions

Tool Restrictions

To control tool access for Skills in SDK applications, use allowedTools to pre-approve specific tools. Without a canUseTool callback, anything not in the list is denied:

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
permission_mode="dontAsk",  # Deny anything not pre-approved instead of prompting
)


async def main():
async for message in query(prompt="Analyze the codebase structure", options=options):
print(message)


asyncio.run(main())

for await (const message of query({
prompt: "Analyze the codebase structure",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Grep", "Glob"],
permissionMode: "dontAsk" // Deny anything not pre-approved instead of prompting
}
})) {
console.log(message);
}

Discovering Available Skills

To see which Skills are available in your SDK application, ask Claude. The example below sets only the skills option and omits settingSources/setting_sources. When you leave settingSources/setting_sources unset, the SDK still loads Skills from the user and project sources, so the skills option set to "all" on its own makes them available to list.

options = ClaudeAgentOptions(skills="all")


async def main():
async for message in query(prompt="What Skills are available?", options=options):
print(message)


asyncio.run(main())

for await (const message of query({
prompt: "What Skills are available?",
options: {
skills: "all"
}
})) {
console.log(message);
}

Claude will list the available Skills based on your current working directory and installed plugins.

Testing Skills

Test Skills by asking questions that match their descriptions:

options = ClaudeAgentOptions(
cwd=os.getcwd(),
setting_sources=["user", "project"],  # Load Skills from filesystem
skills="all",
allowed_tools=["Read", "Bash"],
)


async def main():
async for message in query(prompt="Extract text from invoice.pdf", options=options):
print(message)


asyncio.run(main())

for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: process.cwd(),
settingSources: ["user", "project"], // Load Skills from filesystem
skills: "all",
allowedTools: ["Read", "Bash"]
}
})) {
console.log(message);
}

Claude automatically invokes the relevant Skill if the description matches your request.

Troubleshooting

Skills Not Found

Check settingSources configuration: Skills are discovered through the user and project setting sources. If you set settingSources/setting_sources explicitly and omit those sources, skills are not loaded:

# Skills not loaded: setting_sources excludes user and project
options = ClaudeAgentOptions(setting_sources=[], skills="all")

# Skills loaded: user and project sources included
options = ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
)

// Skills not loaded: settingSources excludes user and project
const optionsWithoutSkills = {
settingSources: [],
skills: "all"
};

// Skills loaded: user and project sources included
const optionsWithSkills = {
settingSources: ["user", "project"],
skills: "all"
};

For more details on settingSources/setting_sources, see the TypeScript SDK reference or Python SDK reference.

Check working directory: The SDK loads Skills from .claude/skills/ in the cwd option and in every parent directory up to the repository root. Ensure cwd points at or below the directory containing .claude/skills/, within the same repository:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project",  # .claude/skills/ here or in a parent directory
setting_sources=["user", "project"],  # Loads skills from these sources
skills="all",
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // .claude/skills/ here or in a parent directory
settingSources: ["user", "project"], // Loads skills from these sources
skills: "all"
};

See the "Using Skills with the SDK" section above for the complete pattern.

Verify filesystem location:

# Check project Skills
ls .claude/skills/*/SKILL.md

# Check personal Skills
ls ~/.claude/skills/*/SKILL.md

Skill Not Being Used

Check the skills option: If you passed a skills list, confirm the skill's name is included. Passing [] disables all skills.

Check the description: Ensure it's specific and includes relevant keywords. See Agent Skills Best Practices for guidance on writing effective descriptions.

Additional Troubleshooting

For general Skills troubleshooting (YAML syntax, debugging, etc.), see the Claude Code Skills troubleshooting section.

Related Documentation

Skills Guides

• Agent Skills in Claude Code: Complete Skills guide with creation, examples, and troubleshooting
• Agent Skills Overview: Conceptual overview, benefits, and architecture
• Agent Skills Best Practices: Authoring guidelines for effective Skills
• Agent Skills Cookbook: Example Skills and templates

SDK Resources

• Subagents in the SDK: Similar filesystem-based agents with programmatic options
• Slash Commands in the SDK: User-invoked commands
• SDK Overview: General SDK concepts
• TypeScript SDK Reference: Complete API documentation
• Python SDK Reference: Complete API documentation