Follow Discord
Sweep 06 Nov 2026 · 01:32Z Build v2.1.319 537 read Stable v2.1.311 Latest v2.1.319 Next v2.1.319 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Code CLI 23 Oct 2026
One change · claude-code

Extend agents with skills changedagent-sdk/skills

Nearest release: v2.1.309, published 4 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 23 Oct 2026 00:36 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.

Upstream edited
Recorded here
Lines+30added
Lines−30removed
From line 17 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits17to this page, all time

The whole hunk

from line 17, old and new numbered
/
lines
from line 17
1717* **User-invoked**: you dispatch a skill directly by sending `/<name>` in a prompt. See [Commands in Agent SDK sessions](#commands-in-agent-sdk-sessions)
1818* **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
1919 
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.
20Unlike subagents, which you can define in the [`agents` option](https://code.claude.com/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.
2121 
2222> [!NOTE]
2323>
24> 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. The project source also covers `<dir>/.claude/skills/` in each directory you pass through `additionalDirectories` (TypeScript) or `add_dirs` (Python), because the SDK passes those directories to Claude Code as [`--add-dir`](/docs/en/skills#skills-from-additional-directories). If you set `settingSources` explicitly, include `'project'` to keep project and added-directory skills and `'user'` to keep your personal skills, or use the [`plugins` option](/docs/en/agent-sdk/plugins) to load skills from a specific path.
24> 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. The project source also covers `<dir>/.claude/skills/` in each directory you pass through `additionalDirectories` (TypeScript) or `add_dirs` (Python), because the SDK passes those directories to Claude Code as [`--add-dir`](https://code.claude.com/docs/en/skills#skills-from-additional-directories). If you set `settingSources` explicitly, include `'project'` to keep project and added-directory skills and `'user'` to keep your personal skills, or use the [`plugins` option](https://code.claude.com/docs/en/agent-sdk/plugins) to load skills from a specific path.
2525 
2626## Use skills with the Agent SDK
2727 
from line 87
8787 
8888### Confirm skills loaded
8989 
90Near 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 with a `description` or `when_to_use` frontmatter field, along with [bundled skills included with Claude Code](/docs/en/skills.md#bundled-skills).
90Near 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 with a `description` or `when_to_use` frontmatter field, along with [bundled skills included with Claude Code](https://code.claude.com/docs/en/skills.md#bundled-skills).
9191 
92The 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 lists the same skills whether or not they're in your `skills` list.
92The array lists user-invocable skills only. A skill with [`user-invocable: false`](https://code.claude.com/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 lists the same skills whether or not they're in your `skills` list.
9393 
9494### Allow only specific skills
9595 
from line 97
9797 
9898* **Your own skills**: the skill's directory name
9999* **Plugin skills**: `plugin:skill`
100* **Name clashes in `additionalDirectories` or `add_dirs`**: a skill in one of those directories gets a [prefixed name](/docs/en/skills.md#how-a-skill-gets-its-command-name) when its name clashes with an enterprise, personal, or project skill, or one in a directory added earlier. List it by that name. With a `verify` skill in `../api` and `../web`, added in that order, and no other `verify` skill, list them as `verify` and `web:verify`. Requires Claude Code v2.1.309 or later
100* **Name clashes in `additionalDirectories` or `add_dirs`**: a skill in one of those directories gets a [prefixed name](https://code.claude.com/docs/en/skills.md#how-a-skill-gets-its-command-name) when its name clashes with an enterprise, personal, or project skill, or one in a directory added earlier. List it by that name. With a `verify` skill in `../api` and `../web`, added in that order, and no other `verify` skill, list them as `verify` and `web:verify`. Requires Claude Code v2.1.309 or later
101101 
102102The 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.
103103 
from line 114
114114* **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
115115* **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
116116 
117By default, both you and Claude can invoke any skill. You can restrict either path through the skill's [frontmatter](/docs/en/skills.md#control-who-invokes-a-skill). For definitions of command and skill, see the glossary's [Command](/docs/en/glossary.md#command) and [Skill](/docs/en/glossary.md#skill) entries. See [Commands in Claude Code](/docs/en/commands.md) for every built-in and [Extend Claude with skills](/docs/en/skills.md) for the complete guide to both artifact forms.
117By default, both you and Claude can invoke any skill. You can restrict either path through the skill's [frontmatter](https://code.claude.com/docs/en/skills.md#control-who-invokes-a-skill). For definitions of command and skill, see the glossary's [Command](https://code.claude.com/docs/en/glossary.md#command) and [Skill](https://code.claude.com/docs/en/glossary.md#skill) entries. See [Commands in Claude Code](https://code.claude.com/docs/en/commands.md) for every built-in and [Extend Claude with skills](https://code.claude.com/docs/en/skills.md) for the complete guide to both artifact forms.
118118 
119119### Discover available commands
120120 
from line 153
153153Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]
154154```
155155 
156A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter doesn't appear in this list or in the `skills` array from [Confirm skills loaded](#confirm-skills-loaded). Sessions that configure [MCP servers](/docs/en/agent-sdk/mcp.md) can also expose [MCP prompts as commands](/docs/en/mcp.md#use-mcp-prompts-as-commands).
156A skill with [`user-invocable: false`](https://code.claude.com/docs/en/skills#control-who-invokes-a-skill) in its frontmatter doesn't appear in this list or in the `skills` array from [Confirm skills loaded](#confirm-skills-loaded). Sessions that configure [MCP servers](https://code.claude.com/docs/en/agent-sdk/mcp.md) can also expose [MCP prompts as commands](https://code.claude.com/docs/en/mcp.md#use-mcp-prompts-as-commands).
157157 
158158### Dispatch commands by name
159159 
from line 165
165165 
166166> [!NOTE]
167167>
168> 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.md#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.md#single-message-input), or set `maxTurns` high enough for the work to complete.
168> 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](https://code.claude.com/docs/en/agent-sdk/agent-loop.md#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](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md#single-message-input), or set `maxTurns` high enough for the work to complete.
169169 
170170### Compact history with `/compact`
171171 
from line 246
246246 
247247> [!NOTE]
248248>
249> A `compact_boundary` message only arrives when compaction ran. When a continued session has messages but nothing `/compact` can summarize, the run still ends with a `success` result rather than an error, and no `compact_boundary` message arrives. The result text then carries the reason, for example `Not enough messages to compact.` when the session holds a prompt but no reply from Claude yet. 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.md) or when resuming a session.
249> A `compact_boundary` message only arrives when compaction ran. When a continued session has messages but nothing `/compact` can summarize, the run still ends with a `success` result rather than an error, and no `compact_boundary` message arrives. The result text then carries the reason, for example `Not enough messages to compact.` when the session holds a prompt but no reply from Claude yet. 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](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md) or when resuming a session.
250250 
251251### Reset context with `/clear`
252252 
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).
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](https://code.claude.com/docs/en/agent-sdk/sessions#resume-by-id).
254254 
255`/clear` is useful in [streaming input mode](/docs/en/agent-sdk/streaming-vs-single-mode.md), 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.
255`/clear` is useful in [streaming input mode](https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode.md), 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.
256256 
257257## Create skills
258258 
from line 267
267267 
268268### Choose a discovery level
269269 
270Save skills at either of the two most common [discovery levels](/docs/en/skills.md#where-skills-live):
270Save skills at either of the two most common [discovery levels](https://code.claude.com/docs/en/skills.md#where-skills-live):
271271 
272272* **Project skills**: `.claude/skills/`, available only in the current project
273273* **Personal skills**: `~/.claude/skills/`, available across all your projects
274274 
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 [Resolve skills that share a name](/docs/en/skills.md#resolve-skills-that-share-a-name) 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.md) for the complete guide to both artifact forms.
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 [Resolve skills that share a name](https://code.claude.com/docs/en/skills.md#resolve-skills-that-share-a-name) 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](https://code.claude.com/docs/en/skills.md) for the complete guide to both artifact forms.
276276 
277277### Create and dispatch your first skill
278278 
from line 341
341341 
342342> [!NOTE]
343343>
344> In SDK sessions, you can pre-approve tools for a project or personal skill with the skill's [`allowed-tools`](/docs/en/skills#pre-approve-tools-for-a-skill) frontmatter or with the `allowedTools` option (`allowed_tools` in Python) in your query configuration. If your organization sets [`allowManagedPermissionRulesOnly`](/docs/en/settings-reference#allowmanagedpermissionrulesonly) in managed settings, Claude Code ignores both. Skills [synced from claude.ai](/docs/en/skills.md#how-claude-code-handles-the-frontmatter-of-a-synced-skill) follow their own frontmatter rules.
344> In SDK sessions, you can pre-approve tools for a project or personal skill with the skill's [`allowed-tools`](https://code.claude.com/docs/en/skills#pre-approve-tools-for-a-skill) frontmatter or with the `allowedTools` option (`allowed_tools` in Python) in your query configuration. If your organization sets [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/en/settings-reference#allowmanagedpermissionrulesonly) in managed settings, Claude Code ignores both. Skills [synced from claude.ai](https://code.claude.com/docs/en/skills.md#how-claude-code-handles-the-frontmatter-of-a-synced-skill) follow their own frontmatter rules.
345345 
346346Skills 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:
347347 
from line 382
382382 
383383In 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.
384384 
385The 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.md).
385The 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](https://code.claude.com/docs/en/agent-sdk/permissions.md).
386386 
387387## Troubleshooting
388388 
from line 415
415415};
416416```
417417 
418For which skill directories each source loads, see the [filesystem sources table](/docs/en/agent-sdk/claude-code-features.md#control-filesystem-settings-with-settingsources). For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](/docs/en/agent-sdk/typescript.md#settingsource) or [Python SDK reference](/docs/en/agent-sdk/python.md#settingsource).
418For which skill directories each source loads, see the [filesystem sources table](https://code.claude.com/docs/en/agent-sdk/claude-code-features.md#control-filesystem-settings-with-settingsources). For more details on `settingSources`/`setting_sources`, see the [TypeScript SDK reference](https://code.claude.com/docs/en/agent-sdk/typescript.md#settingsource) or [Python SDK reference](https://code.claude.com/docs/en/agent-sdk/python.md#settingsource).
419419 
420420**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:
421421 
from line 492
492492 
493493### Additional troubleshooting
494494 
495For general skills troubleshooting, such as YAML syntax errors and debugging, see the [Claude Code skills troubleshooting section](/docs/en/skills.md#troubleshooting).
495For general skills troubleshooting, such as YAML syntax errors and debugging, see the [Claude Code skills troubleshooting section](https://code.claude.com/docs/en/skills.md#troubleshooting).
496496 
497497## Next steps
498498 
499The [Claude Code skills guide](/docs/en/skills.md) covers authoring in depth. Its guidance applies to SDK sessions. Start with these sections:
499The [Claude Code skills guide](https://code.claude.com/docs/en/skills.md) covers authoring in depth. Its guidance applies to SDK sessions. Start with these sections:
500500 
501* [Frontmatter reference](/docs/en/skills.md#frontmatter-reference): every supported field
502* [Pass arguments to skills](/docs/en/skills.md#pass-arguments-to-skills): `$ARGUMENTS`, `$0`, and `$1`. The [full substitution table](/docs/en/skills.md#available-string-substitutions) adds named arguments and the `${CLAUDE_*}` variables
503* [Inject dynamic context](/docs/en/skills.md#inject-dynamic-context): `` !`command` `` lines that run before Claude sees the skill content
504* [Choose where skills load](/docs/en/skills.md#where-skills-live): every skill location, plugin namespacing, and which skill runs when two share a name
501* [Frontmatter reference](https://code.claude.com/docs/en/skills.md#frontmatter-reference): every supported field
502* [Pass arguments to skills](https://code.claude.com/docs/en/skills.md#pass-arguments-to-skills): `$ARGUMENTS`, `$0`, and `$1`. The [full substitution table](https://code.claude.com/docs/en/skills.md#available-string-substitutions) adds named arguments and the `${CLAUDE_*}` variables
503* [Inject dynamic context](https://code.claude.com/docs/en/skills.md#inject-dynamic-context): `` !`command` `` lines that run before Claude sees the skill content
504* [Choose where skills load](https://code.claude.com/docs/en/skills.md#where-skills-live): every skill location, plugin namespacing, and which skill runs when two share a name
505505 
506506## Related resources
507507 
508* [Commands in Claude Code](/docs/en/commands.md): the full command surface, including every built-in
508* [Commands in Claude Code](https://code.claude.com/docs/en/commands.md): the full command surface, including every built-in
509509* [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview): conceptual overview, benefits, and architecture
510510* [Agent Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices): authoring guidelines for effective skills
511511* [Agent Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction): example skills and templates
512* [Subagents in the SDK](/docs/en/agent-sdk/subagents.md): similar filesystem-based agents with programmatic options
513* [SDK overview](/docs/en/agent-sdk/overview.md): general SDK concepts
514* [TypeScript SDK reference](/docs/en/agent-sdk/typescript.md): complete API documentation
515* [Python SDK reference](/docs/en/agent-sdk/python.md): complete API documentation
512* [Subagents in the SDK](https://code.claude.com/docs/en/agent-sdk/subagents.md): similar filesystem-based agents with programmatic options
513* [SDK overview](https://code.claude.com/docs/en/agent-sdk/overview.md): general SDK concepts
514* [TypeScript SDK reference](https://code.claude.com/docs/en/agent-sdk/typescript.md): complete API documentation
515* [Python SDK reference](https://code.claude.com/docs/en/agent-sdk/python.md): complete API documentation
516516 
Feedback