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:

Defined as filesystem artifacts: Created as SKILL.md files in specific directories (.claude/skills/)
Loaded from filesystem: Skills are loaded from filesystem locations governed by settingSources (TypeScript) or setting_sources (Python)
Automatically discovered: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered
Model-invoked: Claude autonomously chooses when to use them based on context
Enabled via allowed_tools: Add "Skill" to your allowed_tools to enable Skills

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

To use Skills with the SDK, you need to:

Include "Skill" in your allowed_tools configuration
Configure settingSources/setting_sources to load Skills from the filesystem

Once configured, Claude automatically discovers Skills from the specified directories and invokes them when relevant to the user's request.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
options = ClaudeAgentOptions(
cwd="/path/to/project",  # Project with .claude/skills/
setting_sources=["user", "project"],  # Load Skills from filesystem
allowed_tools=["Skill", "Read", "Write", "Bash"],  # Enable Skill tool
)

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: "/path/to/project", // Project with .claude/skills/
settingSources: ["user", "project"], // Load Skills from filesystem
allowedTools: ["Skill", "Read", "Write", "Bash"] // Enable Skill tool
}
})) {
console.log(message);
}

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

Skills are defined as directories 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
allowed_tools=["Skill", "Read", "Grep", "Glob"],
)

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

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

Discovering Available Skills

To see which Skills are available in your SDK application, simply ask Claude:

options = ClaudeAgentOptions(
setting_sources=["user", "project"],  # Load Skills from filesystem
allowed_tools=["Skill"],
)

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

for await (const message of query({
prompt: "What Skills are available?",
options: {
settingSources: ["user", "project"], // Load Skills from filesystem
allowedTools: ["Skill"]
}
})) {
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="/path/to/project",
setting_sources=["user", "project"],  # Load Skills from filesystem
allowed_tools=["Skill", "Read", "Bash"],
)

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

for await (const message of query({
prompt: "Extract text from invoice.pdf",
options: {
cwd: "/path/to/project",
settingSources: ["user", "project"], // Load Skills from filesystem
allowedTools: ["Skill", "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=[], allowed_tools=["Skill"])

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

// Skills not loaded: settingSources excludes user and project
const options = {
settingSources: [],
allowedTools: ["Skill"]
};

// Skills loaded: user and project sources included
const options = {
settingSources: ["user", "project"],
allowedTools: ["Skill"]
};

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

Check working directory: The SDK loads Skills relative to the cwd option. Ensure it points to a directory containing .claude/skills/:

# Ensure your cwd points to the directory containing .claude/skills/
options = ClaudeAgentOptions(
cwd="/path/to/project",  # Must contain .claude/skills/
setting_sources=["user", "project"],  # Loads skills from these sources
allowed_tools=["Skill"],
)

// Ensure your cwd points to the directory containing .claude/skills/
const options = {
cwd: "/path/to/project", // Must contain .claude/skills/
settingSources: ["user", "project"], // Loads skills from these sources
allowedTools: ["Skill"]
};

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 Skill tool is enabled: Confirm "Skill" is in your allowedTools.

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.

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

agent-sdk/skills.md +13 −12

17When using the Claude Agent SDK, Skills are:17When using the Claude Agent SDK, Skills are:

18 18

191. **Defined as filesystem artifacts**: Created as `SKILL.md` files in specific directories (`.claude/skills/`)191. **Defined as filesystem artifacts**: Created as `SKILL.md` files in specific directories (`.claude/skills/`)

~~202. **Loaded from filesystem**: Skills are loaded from configured filesystem locations. You must specify `settingSources` (TypeScript) or `setting_sources` (Python) to load Skills from the filesystem~~202. **Loaded from filesystem**: Skills are loaded from filesystem locations governed by `settingSources` (TypeScript) or `setting_sources` (Python)

213. **Automatically discovered**: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered213. **Automatically discovered**: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered

224. **Model-invoked**: Claude autonomously chooses when to use them based on context224. **Model-invoked**: Claude autonomously chooses when to use them based on context

235. **Enabled via allowed\_tools**: Add `"Skill"` to your `allowed_tools` to enable Skills235. **Enabled via allowed\_tools**: Add `"Skill"` to your `allowed_tools` to enable Skills

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

26 26

27<Note>27<Note>

28 **Default behavior**: By default, the SDK does not load any filesystem settings. To use Skills, you must explicitly configure `settingSources: ['user', 'project']` (TypeScript) or `setting_sources=["user", "project"]` (Python) in your options.28 Skills are discovered through the filesystem setting sources. With default `query()` options, the SDK loads user and project sources, so skills in `~/.claude/skills/` and `<cwd>/.claude/skills/` are available. If you set `settingSources` explicitly, include `'user'` or `'project'` to keep skill discovery, or use the [`plugins` option](/en/agent-sdk/plugins) to load skills from a specific path.

29</Note>29</Note>

30 30

31## Using Skills with the SDK31## Using Skills with the SDK

204 204

205### Skills Not Found205### Skills Not Found

206 206

207**Check settingSources configuration**: Skills are only loaded when you explicitly configure `settingSources`/`setting_sources`. This is the most common issue:207**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:

208 208

209<CodeGroup>209<CodeGroup>

210 ```python Python theme={null}210 ```python Python theme={null}

211 # Wrong - Skills won't be loaded211 # Skills not loaded: setting_sources excludes user and project

212 options = ClaudeAgentOptions(allowed_tools=["Skill"])212 options = ClaudeAgentOptions(setting_sources=[], allowed_tools=["Skill"])

213 213

214 # Correct - Skills will be loaded214 # Skills loaded: user and project sources included

215 options = ClaudeAgentOptions(215 options = ClaudeAgentOptions(

216 setting_sources=["user", "project"], # Required to load Skills216 setting_sources=["user", "project"],

217 allowed_tools=["Skill"],217 allowed_tools=["Skill"],

218 )218 )

219 ```219 ```

220 220

221 ```typescript TypeScript theme={null}221 ```typescript TypeScript theme={null}

222 // Wrong - Skills won't be loaded222 // Skills not loaded: settingSources excludes user and project

223 const options = {223 const options = {

224 settingSources: [],

224 allowedTools: ["Skill"]225 allowedTools: ["Skill"]

225 };226 };

226 227

227 // Correct - Skills will be loaded228 // Skills loaded: user and project sources included

228 const options = {229 const options = {

229 settingSources: ["user", "project"], // Required to load Skills230 settingSources: ["user", "project"],

230 allowedTools: ["Skill"]231 allowedTools: ["Skill"]

231 };232 };

232 ```233 ```

241 # Ensure your cwd points to the directory containing .claude/skills/242 # Ensure your cwd points to the directory containing .claude/skills/

242 options = ClaudeAgentOptions(243 options = ClaudeAgentOptions(

243 cwd="/path/to/project", # Must contain .claude/skills/244 cwd="/path/to/project", # Must contain .claude/skills/

244 setting_sources=["user", "project"], # Required to load Skills245 setting_sources=["user", "project"], # Loads skills from these sources

245 allowed_tools=["Skill"],246 allowed_tools=["Skill"],

246 )247 )

247 ```248 ```

250 // Ensure your cwd points to the directory containing .claude/skills/251 // Ensure your cwd points to the directory containing .claude/skills/

251 const options = {252 const options = {

252 cwd: "/path/to/project", // Must contain .claude/skills/253 cwd: "/path/to/project", // Must contain .claude/skills/

253 settingSources: ["user", "project"], // Required to load Skills254 settingSources: ["user", "project"], // Loads skills from these sources

254 allowedTools: ["Skill"]255 allowedTools: ["Skill"]

255 };256 };

256 ```257 ```