---
title: "Agent Skills in the SDK — Configuration & Discovery"
aliases: [sdk-skills, skills-setting-sources, skill-md-sdk]
tags: [agent-sdk, skills, python, typescript, configuration, filesystem]
sources: [raw/Agent Skills in the SDK.md]
created: 2026-04-17
updated: 2026-04-17
---

# Agent Skills in the SDK — Configuration & Discovery

Skills are model-invoked capabilities defined as `SKILL.md` files on the filesystem. The SDK discovers them at startup via `setting_sources` / `settingSources` — **not** through a programmatic registration API.

## How Skills Are Discovered

Skills are loaded from filesystem directories determined by `setting_sources`:

| Source value | Directory scanned |
|---|---|
| `"user"` | `~/.claude/skills/` |
| `"project"` | `<cwd>/.claude/skills/` |
| plugin | bundled inside the plugin directory |

Default `query()` options load both `user` and `project` sources automatically. If you set `setting_sources` explicitly, you must include `"user"` and/or `"project"` to keep skill discovery.

## Minimal Setup (Python)

```python
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    cwd="/path/to/project",           # must contain .claude/skills/
    setting_sources=["user", "project"],
    allowed_tools=["Skill", "Read", "Write", "Bash"],
)

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

Two requirements:
1. `"Skill"` in `allowed_tools`
2. `setting_sources` includes `"user"` or `"project"` (or both)

## Skill Directory Structure

```
.claude/skills/
└── processing-pdfs/
    └── SKILL.md       ← instructions + description in YAML frontmatter
```

The `description` field in `SKILL.md` frontmatter is what Claude reads to decide when to invoke the skill.

## Tool Restrictions — SDK vs CLI

| Context | `allowed-tools` in SKILL.md | Effect |
|---|---|---|
| Claude Code CLI | Supported | Restricts tools inside the skill |
| SDK (`query()`) | **Ignored** | Has no effect |

In the SDK, tool access is controlled exclusively via the top-level `allowed_tools` option:

```python
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    allowed_tools=["Skill", "Read", "Grep", "Glob"],
    # Without canUseTool callback, anything not listed is denied
)
```

## Discovering Available Skills at Runtime

```python
options = ClaudeAgentOptions(
    setting_sources=["user", "project"],
    allowed_tools=["Skill"],
)
async for message in query(prompt="What Skills are available?", options=options):
    print(message)
```

## Troubleshooting

**Skills not found**

```python
# Wrong — skills not loaded
ClaudeAgentOptions(setting_sources=[], allowed_tools=["Skill"])

# Correct
ClaudeAgentOptions(setting_sources=["user", "project"], allowed_tools=["Skill"])
```

Also verify:
```sh
ls .claude/skills/*/SKILL.md     # project skills
ls ~/.claude/skills/*/SKILL.md   # user skills
```

**Skill not being invoked**
- Confirm `"Skill"` is in `allowed_tools`
- Check the `description` field in `SKILL.md` — must be specific and keyword-rich

## Key Takeaways

- Skills **must** be filesystem artifacts (`SKILL.md`) — no programmatic registration API exists
- `setting_sources=["user", "project"]` is required for skill discovery; an empty list disables it
- `"Skill"` must appear in `allowed_tools` or Claude cannot invoke any skill
- `allowed-tools` frontmatter in `SKILL.md` is **CLI-only** — ignored by the SDK
- The `cwd` option determines which `.claude/skills/` project directory is scanned
- For plugin-bundled skills, see [[wiki/agent-sdk/agent-skills-plugins|Agent Skills & Plugins in the SDK]]

## Related

- [[wiki/agent-sdk/agent-skills-plugins|Agent Skills & Plugins in the SDK]] — loading skills bundled inside plugins
- [[wiki/agent-sdk/python-api-reference|Python API Reference]] — full `ClaudeAgentOptions` type reference
- [[wiki/agent-sdk/typescript-api-reference|TypeScript API Reference]] — `settingSources`, `allowedTools`, `canUseTool`
- [[wiki/agent-sdk/overview|Agent SDK Overview]] — full SDK feature set

---

*Source: raw/Agent Skills in the SDK.md*
