📄 claude/docs/agent-sdk/skills

File: skills.md | Updated: 11/15/2025

Source: https://docs.claude.com/en/docs/agent-sdk/skills

Agent Skills are now available! Learn more about extending Claude's capabilities with Agent Skills .

Claude Docs home pagelight logodark logo

US

English

Search...

Ctrl K

Search...

Navigation

Guides

Agent Skills in the SDK

Home Developer Guide API Reference Model Context Protocol (MCP) Resources Release Notes

On this page

​

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: Created as SKILL.md files in specific directories (.claude/skills/)
  2. 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
  3. Automatically discovered: Once filesystem settings are loaded, Skill metadata is discovered at startup from user and project directories; full content loaded when triggered
  4. Model-invoked: Claude autonomously chooses when to use them based on context
  5. 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.

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.

​

Using Skills with the SDK

To use Skills with the SDK, you need to:

  1. Include "Skill" in your allowed_tools configuration
  2. 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.

Python

TypeScript

Copy

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())

​

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:

Copy

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

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

​

Tool Restrictions

The allowed-tools frontmatter field in SKILL.md is only supported when using Claude Code CLI directly. It does not apply when using Skills through the SDK.When using the SDK, control tool access through the main allowedTools option in your query configuration.

To restrict tools for Skills in SDK applications, use the allowedTools option:

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

Python

TypeScript

Copy

options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Load Skills from filesystem
    allowed_tools=["Skill", "Read", "Grep", "Glob"]  # Restricted toolset
)

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

​

Discovering Available Skills

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

Python

TypeScript

Copy

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)

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:

Python

TypeScript

Copy

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)

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

​

Troubleshooting

​

Skills Not Found

Check settingSources configuration: Skills are only loaded when you explicitly configure settingSources/setting_sources. This is the most common issue:

Python

TypeScript

Copy

# Wrong - Skills won't be loaded
options = ClaudeAgentOptions(
    allowed_tools=["Skill"]
)

# Correct - Skills will be loaded
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],  # Required to load Skills
    allowed_tools=["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/:

Python

TypeScript

Copy

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

See the “Using Skills with the SDK” section above for the complete pattern. Verify filesystem location:

Copy

# 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 .

​

Related Documentation

​

Skills Guides

​

SDK Resources

Was this page helpful?

YesNo

Slash Commands in the SDK Tracking Costs and Usage

Assistant

Responses are generated using AI and may contain mistakes.