Extend agents with skills changedagent-sdk/skills
Nearest release: v2.1.235, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+374added
Lines−182removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits15to this page, all time
# Extend agents with skills ## How skills work with the Agent SDK ## Use skills with the Agent SDK ### Set up skills in a session ### Confirm skills loaded ### Allow only specific skills ## Commands in Agent SDK sessions ### Discover available commands ### Dispatch commands by name ### Compact history with `/compact` ### Reset context with `/clear` ## Create skills ### Choose a discovery level ### Create and dispatch your first skill ## Pre-approve tools for skills ### Skills not found ### Skill not being used ### Invalid skill name error ### Additional troubleshooting ## Next steps ## Related resources # Agent Skills in the SDK ## Overview ## How Skills Work with the SDK ## Using Skills with the SDK ## Creating Skills ## Tool Restrictions ## Discovering Available Skills ## Testing Skills ### Skills Not Found ### Skill Not Being Used ### Additional Troubleshooting ## Related Documentation ### Skills Guides ### SDK Resources
The whole hunk
from line 1, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1# Agent Skills in the SDK
2
3> Extend Claude with specialized capabilities using Agent Skills in the Claude Agent SDK
4
5## Overview
6
7Agent 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.
8
9For comprehensive information about Skills, including benefits, architecture, and authoring guidelines, see the [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
10
11## How Skills Work with the SDK
12
13When using the Claude Agent SDK, Skills are:
14
151. **Defined as filesystem artifacts**: you create each Skill as a `SKILL.md` file in its own directory, such as `.claude/skills/<name>/SKILL.md`
162. **Loaded from filesystem**: the SDK loads Skills from the filesystem locations governed by `settingSources` (TypeScript) or `setting_sources` (Python)
173. **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
184. **Model-invoked**: Claude autonomously chooses when to use them based on context
195. **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
20
21Unlike subagents (which can be defined programmatically), Skills must be created as filesystem artifacts. The SDK does not provide a programmatic API for registering Skills.
1# Extend agents with skills
2
3> Control which skills Claude can invoke in Claude Agent SDK sessions, dispatch commands by name, and author skills your sessions discover
4
5Agent Skills extend Claude with specialized capabilities that Claude invokes when relevant. Skills are packaged as `SKILL.md` files containing instructions, descriptions, and optional supporting resources. This page also covers [commands in Agent SDK sessions](#commands-in-agent-sdk-sessions).
6
7For comprehensive information about skills, including benefits, architecture, and authoring guidelines, see the [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
8
9## How skills work with the Agent SDK
10
11When using the Claude Agent SDK, skills are:
12
13* **Defined as filesystem artifacts**: you create each skill as a `SKILL.md` file in its own directory, such as `.claude/skills/<name>/SKILL.md`
14* **Loaded from filesystem**: the SDK loads skills from the filesystem locations governed by `settingSources` (TypeScript) or `setting_sources` (Python)
15* **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
16* **Model-invoked**: Claude autonomously chooses when to use them based on context
17* **User-invoked**: you dispatch a skill directly by sending `/<name>` in a prompt. See [Commands in Agent SDK sessions](#commands-in-agent-sdk-sessions)
18* **Scoped via the `skills` option**: discovered skills are enabled by default. Pass a list of skill names, `"all"`, or `[]` to control which skills Claude can invoke
19
20Unlike subagents, which you can define in the [`agents` option](/docs/en/agent-sdk/subagents#programmatic-definition-recommended), you create skills as files on disk. The SDK doesn't provide a programmatic API for registering them.
2221
2322<Note>
2423 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](/docs/en/agent-sdk/plugins) to load skills from a specific path.
2524</Note>
2625
27## Using Skills with the SDK
28
29Set 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.
30
31Once configured, Claude automatically discovers Skills from the filesystem and invokes them when relevant to the user's request.
32
33The 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:
26## Use skills with the Agent SDK
27
28Set the `skills` option on `query()` to control which skills Claude can invoke in the session. When omitted, discovered skills are enabled and the Skill tool is available, matching CLI behavior. Pass `"all"` to let Claude invoke every discovered skill, a list of skill names to allow only those, or `[]` to let Claude invoke none.
29
30For example, to let Claude invoke only two named skills:
31
32<CodeGroup>
33 ```python Python theme={null}
34 options = ClaudeAgentOptions(skills=["pdf", "docx"])
35 ```
36
37 ```typescript TypeScript theme={null}
38 const options = { skills: ["pdf", "docx"] };
39 ```
40</CodeGroup>
41
42### Set up skills in a session
43
44When 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.
45
46Once configured, Claude automatically discovers skills from the filesystem and invokes them when relevant to the user's request.
47
48The following example enables every discovered skill in a session and pre-approves the tools that skills commonly need. The 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:
3449
3550<CodeGroup>
3651 ```python Python theme={null}
from line 58
4358 async def main():
4459 options = ClaudeAgentOptions(
4560 cwd=os.getcwd(), # .claude/skills/ here or in a parent directory
46 setting_sources=["user", "project"], # Load Skills from filesystem
47 skills="all", # Enable every discovered Skill
61 setting_sources=["user", "project"], # Load skills from filesystem
62 skills="all", # Let Claude invoke every discovered skill
4863 allowed_tools=["Read", "Write", "Bash"],
4964 )
5065
from line 79
6479 prompt: "Help me process this PDF document",
6580 options: {
6681 cwd: process.cwd(), // .claude/skills/ here or in a parent directory
67 settingSources: ["user", "project"], // Load Skills from filesystem
68 skills: "all", // Enable every discovered Skill
82 settingSources: ["user", "project"], // Load skills from filesystem
83 skills: "all", // Let Claude invoke every discovered skill
6984 allowedTools: ["Read", "Write", "Bash"]
7085 }
7186 })) {
from line 89
7489 ```
7590</CodeGroup>
7691
77Near 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`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter loads and remains available to Claude but doesn't appear in the array.
78
79To 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.
92### Confirm skills loaded
93
94Near 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 includes the user-invocable skills that you have defined, along with [bundled skills included with Claude Code](/docs/en/skills#bundled-skills).
95
96The array lists user-invocable skills only. A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter loads and remains available to Claude, but doesn't appear in the array. The array reflects what the session discovered and lists the same skills whether or not they're in your `skills` list.
97
98### Allow only specific skills
99
100To let Claude invoke only specific skills, pass their names in the `skills` list. Names match the `name` field in `SKILL.md` or the skill's directory name. Use `plugin:skill` for plugin-provided skills.
101
102The list takes exact skill names only. If an entry can't work as an exact name, `query()` rejects the list before the session starts. See [Invalid skill name error](#invalid-skill-name-error) for the name rules and the error each SDK raises.
103
104The model doesn't see unlisted skills and the Skill tool rejects them, while their files remain on disk and stay reachable through Read and Bash. Restricting the list doesn't restrict [dispatch by name](#dispatch-commands-by-name).
105
106To let Claude invoke every discovered skill, pass `skills: "all"` rather than a wildcard.
107
108## Commands in Agent SDK sessions
109
110This section is the SDK's command documentation. A command is anything you run by sending `/<name>` in a prompt. Entries on the command surface differ in what backs them:
111
112* **Built-in commands**: execute logic coded into the Claude Code process the SDK runs, for example `/compact`
113* **Bundled skills**: prompt artifacts included with Claude Code, for example `/code-review`
114* **Your skills**: prompt artifacts that you author, each a directory holding a `SKILL.md` file. A user-invocable skill's name joins the surface automatically, so dispatching your own `/security-check` and running a built-in work the same way
115* **Custom command files**: an older artifact form with the same behavior, flat Markdown files in `.claude/commands/` whose filenames become command names. Skills are their recommended successor
116
117By default, both you and Claude can invoke any skill. You can restrict either path through the skill's [frontmatter](/docs/en/skills#control-who-invokes-a-skill). For a definition of the two terms, see the glossary's [Command](/docs/en/glossary#command) and [Skill](/docs/en/glossary#skill) entries. See [Commands in Claude Code](/docs/en/commands) for every built-in and [Extend Claude with skills](/docs/en/skills) for the complete guide to both artifact forms.
118
119### Discover available commands
120
121You can dispatch commands that work without an interactive terminal through the SDK. The `system/init` message lists the ones available in your session in its `slash_commands` field. Commands that need an interactive terminal, such as `/theme` and `/terminal-setup`, don't appear in the list. Access the field when your session starts:
122
123<CodeGroup>
124 ```typescript TypeScript theme={null}
125 import { query } from "@anthropic-ai/claude-agent-sdk";
126
127 for await (const message of query({
128 prompt: "Hello Claude",
129 options: { maxTurns: 1 }
130 })) {
131 if (message.type === "system" && message.subtype === "init") {
132 console.log("Available commands:", message.slash_commands);
133 }
134 }
135 ```
136
137 ```python Python theme={null}
138 import asyncio
139 from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage
140
141
142 async def main():
143 async for message in query(prompt="Hello Claude", options=ClaudeAgentOptions(max_turns=1)):
144 if isinstance(message, SystemMessage) and message.subtype == "init":
145 print("Available commands:", message.data["slash_commands"])
146
147
148 asyncio.run(main())
149 ```
150</CodeGroup>
151
152The printed list mixes built-in commands, bundled skills, your user-invocable skills, and `.claude/commands/` files:
153
154```text theme={null}
155Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]
156```
157
158Your user-invocable skills appear in both this list and the `skills` array from [Confirm skills loaded](#confirm-skills-loaded). The `slash_commands` list adds the rest of the commands available in your session. A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter doesn't appear in either. Sessions that configure [MCP servers](/docs/en/agent-sdk/mcp) can also expose [MCP prompts as commands](/docs/en/mcp#use-mcp-prompts-as-commands).
159
160### Dispatch commands by name
161
162Send a command by including it in your prompt string, the same way you send regular text. Dispatch doesn't depend on the `skills` option. Sending `/<name>` runs a user-invocable skill even when your `skills` list omits it. Commands that act on conversation history, such as `/compact`, need prior messages to work with.
80163
81164<Note>
82 Import statements from the first example are assumed in the following code snippets.
165 A command can hit the `maxTurns` / `max_turns` limit like any other prompt, ending the query with an error result instead of `success`. For the error-result contract, see [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result). If your command might hit the limit, wrap the loop in a `try`/`catch` in TypeScript or `try`/`except` in Python, as shown in [Single Message Input](/docs/en/agent-sdk/streaming-vs-single-mode#single-message-input), or set `maxTurns` high enough for the work to complete.
83166</Note>
84167
85<CodeGroup>
86 ```python Python theme={null}
87 options = ClaudeAgentOptions(skills=["pdf", "docx"])
88 ```
89
90 ```typescript TypeScript theme={null}
91 const options = { skills: ["pdf", "docx"] };
92 ```
93</CodeGroup>
94
95The 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:
96
97* An empty name
98* A name containing parentheses, commas, or control characters
99* A name padded with whitespace
100* A wildcard form such as a bare `*` or a `:*` suffix
101
102To enable every discovered Skill, pass `skills: "all"` rather than a wildcard.
103
104The `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.
105
106## Creating Skills
107
108Create 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.
168### Compact history with `/compact`
169
170The `/compact` command reduces the size of your conversation history by summarizing older messages while preserving important context. Compaction needs an existing conversation with enough prior messages to summarize. This example has a conversation first, then compacts it and reads the `compact_boundary` system message that reports the result:
171
172<CodeGroup>
173 ```typescript TypeScript theme={null}
174 import { query } from "@anthropic-ai/claude-agent-sdk";
175
176 // Compaction needs existing history, so have a conversation first
177 try {
178 for await (const message of query({
179 prompt: "Explain what this project does",
180 options: { maxTurns: 2 }
181 })) {
182 if (message.type === "result" && message.subtype === "success") {
183 console.log(message.result);
184 }
185 }
186 } catch (error) {
187 // A single-shot query() throws after yielding an error result,
188 // so the follow-up query below still runs.
189 console.error(`Session ended with an error: ${error}`);
190 }
191
192 // Compact the same conversation
193 for await (const message of query({
194 prompt: "/compact",
195 options: { continue: true, maxTurns: 1 }
196 })) {
197 if (message.type === "system" && message.subtype === "compact_boundary") {
198 console.log("Compaction completed");
199 console.log("Pre-compaction tokens:", message.compact_metadata.pre_tokens);
200 console.log("Trigger:", message.compact_metadata.trigger);
201 // Example output:
202 // Compaction completed
203 // Pre-compaction tokens: 1842
204 // Trigger: manual
205 }
206 }
207 ```
208
209 ```python Python theme={null}
210 import asyncio
211 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage, SystemMessage
212
213
214 async def main():
215 # Compaction needs existing history, so have a conversation first
216 try:
217 async for message in query(
218 prompt="Explain what this project does",
219 options=ClaudeAgentOptions(max_turns=2),
220 ):
221 if isinstance(message, ResultMessage) and message.subtype == "success":
222 print(message.result)
223 except Exception as error:
224 # A single-shot query() raises after yielding an error result,
225 # so the follow-up query below still runs.
226 print(f"Session ended with an error: {error}")
227
228 # Compact the same conversation
229 async for message in query(
230 prompt="/compact",
231 options=ClaudeAgentOptions(continue_conversation=True, max_turns=1),
232 ):
233 if isinstance(message, SystemMessage) and message.subtype == "compact_boundary":
234 print("Compaction completed")
235 print("Pre-compaction tokens:", message.data["compact_metadata"]["pre_tokens"])
236 print("Trigger:", message.data["compact_metadata"]["trigger"])
237 # Example output:
238 # Compaction completed
239 # Pre-compaction tokens: 1842
240 # Trigger: manual
241
242
243 asyncio.run(main())
244 ```
245</CodeGroup>
246
247<Note>
248 A `compact_boundary` message only arrives when compaction ran. With nothing to summarize, `/compact` reports the reason instead of raising. The run still ends with a `success` result and no `compact_boundary` message, and the result text carries the reason, for example `Not enough messages to compact.` after a single short exchange. A fresh one-shot `query()` call starts with empty context, so use this pattern in a session with prior turns, for example in [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode) or when resuming a session.
249</Note>
250
251### Reset context with `/clear`
252
253The `/clear` command resets the conversation to an empty context, so subsequent prompts start with no prior conversation history. The previous conversation remains on disk. You can return to that conversation by passing its session ID to the [`resume` option](/docs/en/agent-sdk/sessions#resume-by-id).
254
255`/clear` is useful in [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode), where you send multiple prompts over a single connection. For one-shot `query()` calls, each call already starts with empty context, so sending `/clear` has no practical effect. Start a new `query()` instead.
256
257## Create skills
258
259Create 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.
109260
110261**Example directory structure**:
111262
112263```text theme={null}
113.claude/skills/processing-pdfs/
264.claude/skills/security-check/
114265└── SKILL.md
115266```
116267
117For complete guidance on creating Skills, including SKILL.md structure, multi-file Skills, and examples, see:
118
119* [Agent Skills in Claude Code](/docs/en/skills): complete guide with examples
120* [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): authoring guidelines and naming conventions
121
122## Tool Restrictions
268### Choose a discovery level
269
270Save skills at either of the two most common [discovery levels](/docs/en/skills#where-skills-live):
271
272* **Project skills**: `.claude/skills/`, available only in the current project
273* **Personal skills**: `~/.claude/skills/`, available across all your projects
274
275If you have existing custom command files in `.claude/commands/`, they keep working. A command file at `.claude/commands/deploy.md` creates `/deploy` and works the same way as a skill at `.claude/skills/deploy/SKILL.md` would. If a command file and a skill share a name, see [Where skills live](/docs/en/skills#where-skills-live) for which one runs. The SDK loads `.claude/commands/` and `~/.claude/commands/` files from the same two scopes as skills. See [Extend Claude with skills](/docs/en/skills) for the complete guide to both artifact forms.
276
277### Create and dispatch your first skill
278
279To see the full flow, create `.claude/skills/security-check/SKILL.md`:
280
281```markdown theme={null}
282---
283name: security-check
284description: Run a security vulnerability scan
285---
286
287Analyze the codebase for security vulnerabilities including:
288- SQL injection risks
289- XSS vulnerabilities
290- Exposed credentials
291- Insecure configurations
292```
293
294Once the file exists, the skill is available through the SDK. Claude invokes it when a request matches its description, and you can dispatch it directly:
295
296<CodeGroup>
297 ```typescript TypeScript theme={null}
298 import { query } from "@anthropic-ai/claude-agent-sdk";
299
300 for await (const message of query({
301 prompt: "/security-check",
302 options: { maxTurns: 10 }
303 })) {
304 if (message.type === "result" && message.subtype === "success") {
305 console.log(message.result);
306 }
307 }
308 ```
309
310 ```python Python theme={null}
311 import asyncio
312 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
313
314
315 async def main():
316 async for message in query(
317 prompt="/security-check", options=ClaudeAgentOptions(max_turns=10)
318 ):
319 if isinstance(message, ResultMessage) and message.subtype == "success":
320 print(message.result)
321
322
323 asyncio.run(main())
324 ```
325</CodeGroup>
326
327A successful run ends with a `success` result whose text carries the scan findings. Against a small Express app with seeded issues, the result text begins:
328
329```text theme={null}
330**Security scan of `app.js` — 4 findings (most severe first):**
331
3321. **SQL Injection** (line 8) — `req.query.name` is concatenated directly into the SQL string. Trivially exploitable (`' OR '1'='1`, `'; DROP TABLE users;--`). **Fix:** use parameterized queries, e.g. `db.query("SELECT * FROM users WHERE name = ?", [req.query.name], cb)`.
333...
334```
335
336The skill's name also appears in the init message's `slash_commands` array.
123337
124338<Note>
125 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**.
126
127 When using the SDK, control tool access through the main `allowedTools` option in your query configuration.
339 Claude Code includes bundled `code-review` and `verify` skills. If you name a `.claude/commands/` file after one of them, for example `.claude/commands/code-review.md`, the file's command shadows the bundled skill and `slash_commands` lists the name once.
128340</Note>
129341
130To 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:
131
132<CodeGroup>
133 ```python Python theme={null}
342## Pre-approve tools for skills
343
344<Note>
345 For project and personal skills, the `allowed-tools` frontmatter field applies only when you use the Claude Code CLI directly. In SDK sessions, manage tool approval for these skills through the `allowedTools` option (`allowed_tools` in Python) in your query configuration. Skills [synced from claude.ai](/docs/en/skills#how-claude-code-handles-the-frontmatter-of-a-synced-skill) follow their own frontmatter rules.
346</Note>
347
348Skills run with the session's tools. The example below pre-approves `Read`, `Grep`, and `Glob` with `allowedTools` (`allowed_tools` in Python), so Claude can inspect files while running the [security-check skill](#create-and-dispatch-your-first-skill) without stopping for approval:
349
350<CodeGroup>
351 ```python Python theme={null}
352 import asyncio
353
354 from claude_agent_sdk import query, ClaudeAgentOptions
355
134356 options = ClaudeAgentOptions(
135 setting_sources=["user", "project"], # Load Skills from filesystem
357 setting_sources=["user", "project"], # Load skills from filesystem
136358 skills="all",
137359 allowed_tools=["Read", "Grep", "Glob"],
138 permission_mode="dontAsk", # Deny anything not pre-approved instead of prompting
139360 )
140361
141362
142363 async def main():
143 async for message in query(prompt="Analyze the codebase structure", options=options):
364 async for message in query(prompt="Check this project for security issues", options=options):
144365 print(message)
145366
146367
from line 369
148369 ```
149370
150371 ```typescript TypeScript theme={null}
372 import { query } from "@anthropic-ai/claude-agent-sdk";
373
151374 for await (const message of query({
152 prompt: "Analyze the codebase structure",
375 prompt: "Check this project for security issues",
153376 options: {
154 settingSources: ["user", "project"], // Load Skills from filesystem
377 settingSources: ["user", "project"], // Load skills from filesystem
155378 skills: "all",
156 allowedTools: ["Read", "Grep", "Glob"],
157 permissionMode: "dontAsk" // Deny anything not pre-approved instead of prompting
379 allowedTools: ["Read", "Grep", "Glob"]
158380 }
159381 })) {
160382 console.log(message);
from line 384
162384 ```
163385</CodeGroup>
164386
165## Discovering Available Skills
166
167To 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.
168
169<CodeGroup>
170 ```python Python theme={null}
171 options = ClaudeAgentOptions(skills="all")
172
173
174 async def main():
175 async for message in query(prompt="What Skills are available?", options=options):
176 print(message)
177
178
179 asyncio.run(main())
180 ```
181
182 ```typescript TypeScript theme={null}
183 for await (const message of query({
184 prompt: "What Skills are available?",
185 options: {
186 skills: "all"
187 }
188 })) {
189 console.log(message);
190 }
191 ```
192</CodeGroup>
193
194Claude will list the available Skills based on your current working directory and installed plugins.
195
196## Testing Skills
197
198Test Skills by asking questions that match their descriptions:
199
200<CodeGroup>
201 ```python Python theme={null}
202 options = ClaudeAgentOptions(
203 cwd=os.getcwd(),
204 setting_sources=["user", "project"], # Load Skills from filesystem
205 skills="all",
206 allowed_tools=["Read", "Bash"],
207 )
208
209
210 async def main():
211 async for message in query(prompt="Extract text from invoice.pdf", options=options):
212 print(message)
213
214
215 asyncio.run(main())
216 ```
217
218 ```typescript TypeScript theme={null}
219 for await (const message of query({
220 prompt: "Extract text from invoice.pdf",
221 options: {
222 cwd: process.cwd(),
223 settingSources: ["user", "project"], // Load Skills from filesystem
224 skills: "all",
225 allowedTools: ["Read", "Bash"]
226 }
227 })) {
228 console.log(message);
229 }
230 ```
231</CodeGroup>
232
233Claude automatically invokes the relevant Skill if the description matches your request.
387In the stream, the skill invocation appears as a Skill tool use, followed by Read calls on the project files. The run ends with a `success` result whose text carries the findings.
388
389The list pre-approves the named tools rather than restricting the others. For the full permission flow, including permission modes and the `canUseTool` callback, see [Permissions](/docs/en/agent-sdk/permissions).
234390
235391## Troubleshooting
236392
237### Skills Not Found
238
239**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:
393### Skills not found
394
395**Check settingSources configuration**: the SDK discovers skills through the `user` and `project` setting sources. If you set `settingSources`/`setting_sources` explicitly and omit those sources, the SDK doesn't load skills:
240396
241397<CodeGroup>
242398 ```python Python theme={null}
from line 423
267423
268424For which skill directories each source loads, see the [filesystem sources table](/docs/en/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources). For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](/docs/en/agent-sdk/typescript#settingsource) or [Python SDK reference](/docs/en/agent-sdk/python#settingsource).
269425
270**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:
426**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:
271427
272428<CodeGroup>
273429 ```python Python theme={null}
from line 445
289445 ```
290446</CodeGroup>
291447
292See the "Using Skills with the SDK" section above for the complete pattern.
448See [Use skills with the Agent SDK](#use-skills-with-the-agent-sdk) for the complete pattern.
293449
294450**Verify filesystem location**:
295451
296452```bash theme={null}
297# Check project Skills
453# Check project skills
298454ls .claude/skills/*/SKILL.md
299455
300# Check personal Skills
456# Check personal skills
301457ls ~/.claude/skills/*/SKILL.md
302458```
303459
304### Skill Not Being Used
305
306**Check the `skills` option**: If you passed a `skills` list, confirm the skill's name is included. Passing `[]` disables all skills.
307
308**Check the description**: Ensure it's specific and includes relevant keywords. See [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions) for guidance on writing effective descriptions.
309
310### Additional Troubleshooting
311
312For general Skills troubleshooting (YAML syntax, debugging, etc.), see the [Claude Code Skills troubleshooting section](/docs/en/skills#troubleshooting).
313
314## Related Documentation
315
316### Skills Guides
317
318* [Agent Skills in Claude Code](/docs/en/skills): complete Skills guide with creation, examples, and troubleshooting
319* [Agent Skills Overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): conceptual overview, benefits, and architecture
320* [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): authoring guidelines for effective Skills
321* [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): example Skills and templates
322
323### SDK Resources
324
460### Skill not being used
461
462**Check the `skills` option**: if you passed a `skills` list, confirm the skill's name is included. When Claude tries to invoke an unlisted skill, the Skill tool returns `Skill <name> is not in this session's skills allowlist`. Add the name to your list, or dispatch the skill directly by sending `/<name>` in a prompt, which works without listing.
463
464**Check the description**: ensure it's specific and includes relevant keywords. See [Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#writing-effective-descriptions) for guidance on writing effective descriptions.
465
466### Invalid skill name error
467
468When a name in your `skills` list can't work as an exact skill name, `query()` rejects the list before starting the Claude Code process. Names that trigger the rejection include:
469
470* An empty name
471* A name containing parentheses, commas, or control characters
472* A name padded with whitespace
473* A wildcard form such as a bare `*` or a `:*` suffix
474
475Each SDK surfaces the rejection differently:
476
477<Tabs>
478 <Tab title="TypeScript">
479 The TypeScript SDK throws an `Error` stating the rule the entry broke. For example, `skills: ["docs:*"]` throws:
480
481 ```text theme={null}
482 Invalid skill name "docs:*": wildcard-suffix names are not allowed; list each skill by its exact name.
483 ```
484
485 An empty name reports `Skill names must be non-empty strings.`
486 </Tab>
487
488 <Tab title="Python">
489 The Python SDK raises `ValueError` stating the rule the entry broke. For example, `skills=["docs:*"]` raises:
490
491 ```text theme={null}
492 ValueError: Invalid skill name 'docs:*': wildcard-suffix names are not allowed; list each skill by its exact name.
493 ```
494
495 An empty name reports `Skill names must be non-empty strings`.
496 </Tab>
497</Tabs>
498
499### Additional troubleshooting
500
501For general skills troubleshooting, such as YAML syntax errors and debugging, see the [Claude Code skills troubleshooting section](/docs/en/skills#troubleshooting).
502
503## Next steps
504
505The [Claude Code skills guide](/docs/en/skills) covers authoring in depth. Its guidance applies to SDK sessions, with one exception: for project and personal skills, [Pre-approve tools for skills](#pre-approve-tools-for-skills) replaces the `allowed-tools` frontmatter field with the `allowedTools` option. Start with these sections:
506
507* [Frontmatter reference](/docs/en/skills#frontmatter-reference): every supported field
508* [Pass arguments to skills](/docs/en/skills#pass-arguments-to-skills): `$ARGUMENTS`, `$0`, `$1`, and skill stacking. The [full substitution table](/docs/en/skills#available-string-substitutions) adds named arguments and the `${CLAUDE_*}` variables
509* [Inject dynamic context](/docs/en/skills#inject-dynamic-context): `` !`command` `` lines that run before Claude sees the skill content
510* [Where skills live](/docs/en/skills#where-skills-live): all discovery levels, plugin namespacing, and what happens when a skill and a command file share a name
511
512## Related resources
513
514* [Commands in Claude Code](/docs/en/commands): the full command surface, including every built-in
515* [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): conceptual overview, benefits, and architecture
516* [Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): authoring guidelines for effective skills
517* [Agent Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): example skills and templates
325518* [Subagents in the SDK](/docs/en/agent-sdk/subagents): similar filesystem-based agents with programmatic options
326* [Commands in the SDK](/docs/en/agent-sdk/slash-commands): user-invoked commands
327* [SDK Overview](/docs/en/agent-sdk/overview): general SDK concepts
328* [TypeScript SDK Reference](/docs/en/agent-sdk/typescript): complete API documentation
329* [Python SDK Reference](/docs/en/agent-sdk/python): complete API documentation
519* [SDK overview](/docs/en/agent-sdk/overview): general SDK concepts
520* [TypeScript SDK reference](/docs/en/agent-sdk/typescript): complete API documentation
521* [Python SDK reference](/docs/en/agent-sdk/python): complete API documentation
330522
No line in this hunk matches that.