Documentation 2026-05-18 23:59 UTC to 2026-05-19 06:34 UTC

77 </Step>77 </Step>

78 78 

79 <Step title="Set your API key">79 <Step title="Set your API key">

80 Get an API key from the [Console](https://platform.claude.com/), then set it as an environment variable:80 Get an API key from the [Console](../../../../platform.claude.com/index.txt), then set it as an environment variable:

81 81 

82 ```bash theme={null}82 ```bash theme={null}

83 export ANTHROPIC_API_KEY=your-api-key83 export ANTHROPIC_API_KEY=your-api-key

17## Prerequisites17## Prerequisites

18 18 

19* **Node.js 18+** or **Python 3.10+**19* **Node.js 18+** or **Python 3.10+**

20* An **Anthropic account** ([sign up here](https://platform.claude.com/))20* An **Anthropic account** ([sign up here](../../../../platform.claude.com/index.txt))

21 21 

22## Setup22## Setup

23 23 

66 </Step>66 </Step>

67 67 

68 <Step title="Set your API key">68 <Step title="Set your API key">

69 Get an API key from the [Claude Console](https://platform.claude.com/), then create a `.env` file in your project directory:69 Get an API key from the [Claude Console](../../../../platform.claude.com/index.txt), then create a `.env` file in your project directory:

70 70 

71 ```bash theme={null}71 ```bash theme={null}

72 ANTHROPIC_API_KEY=your-api-key72 ANTHROPIC_API_KEY=your-api-key

492* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)492* [Bedrock inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html)

493* [Bedrock token burndown and quotas](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)493* [Bedrock token burndown and quotas](https://docs.aws.amazon.com/bedrock/latest/userguide/quotas-token-burndown.html)

494* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)494* [Claude Code on Amazon Bedrock: Quick Setup Guide](https://community.aws/content/2tXkZKrZzlrlu0KfH8gST5Dkppq/claude-code-on-amazon-bedrock-quick-setup-guide)

495* [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md)495* [Claude Code Monitoring Implementation (Bedrock)](../../../raw.githubusercontent.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/main/assets/docs/MONITORING.md)

19Match the message you see in your terminal to a section below.19Match the message you see in your terminal to a section below.

20 20 

21| Message | Section |21| Message | Section |

22| :----------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |22| :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- |

23| `API Error: 500 ... Internal server error` | [Server errors](#api-error-500-internal-server-error) |23| `API Error: 500 ... Internal server error` | [Server errors](#api-error-500-internal-server-error) |

24| `API Error: Repeated 529 Overloaded errors` | [Server errors](#api-error-repeated-529-overloaded-errors) |24| `API Error: Repeated 529 Overloaded errors` | [Server errors](#api-error-repeated-529-overloaded-errors) |

25| `Request timed out` | [Server errors](#request-timed-out), or [Network](#unable-to-connect-to-api) if the message mentions your internet connection |25| `Request timed out` | [Server errors](#request-timed-out), or [Network](#unable-to-connect-to-api) if the message mentions your internet connection |

33| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |33| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |

34| `Invalid API key` | [Authentication](#invalid-api-key) |34| `Invalid API key` | [Authentication](#invalid-api-key) |

35| `This organization has been disabled` | [Authentication](#this-organization-has-been-disabled) |35| `This organization has been disabled` | [Authentication](#this-organization-has-been-disabled) |

36| `Your organization has disabled Claude subscription access` | [Authentication](#your-organization-has-disabled-claude-subscription-access) |

36| `Routines are disabled by your organization's policy` | [Authentication](#routines-are-disabled-by-your-organizations-policy) |37| `Routines are disabled by your organization's policy` | [Authentication](#routines-are-disabled-by-your-organizations-policy) |

37| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |38| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |

38| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |39| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |

50| `thinking.type.enabled is not supported for this model` | [Request errors](#thinking-type-enabled-is-not-supported-for-this-model) |51| `thinking.type.enabled is not supported for this model` | [Request errors](#thinking-type-enabled-is-not-supported-for-this-model) |

51| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |52| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |

52| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |53| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |

54| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Request errors](#usage-policy-refusal) |

53| Responses seem lower quality than usual | [Response quality](#responses-seem-lower-quality-than-usual) |55| Responses seem lower quality than usual | [Response quality](#responses-seem-lower-quality-than-usual) |

54 56 

55## Automatic retries57## Automatic retries

283* Run `/status` afterward to confirm the active credential is your subscription285* Run `/status` afterward to confirm the active credential is your subscription

284* If no environment variable is set and the error persists, the disabled organization is the one tied to your `/login`. Contact support or sign in with a different account.286* If no environment variable is set and the error persists, the disabled organization is the one tied to your `/login`. Contact support or sign in with a different account.

285 287 

288### Your organization has disabled Claude subscription access

289 

290Your Claude organization does not allow signing in to Claude Code with a subscription login. Running `/login` again with the same account returns the same error.

291 

292```text theme={null}

293Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

294```

295 

296This is a server-side organization setting, so it cannot be overridden from local settings, environment variables, or CLI flags. The Agent SDK and `-p` non-interactive mode surface this as the `oauth_org_not_allowed` error code.

297 

298**What to do:**

299 

300* Ask your admin to enable Claude Code access for your organization

301* Authenticate with a Console API key instead of your subscription. See [Claude Console authentication](/en/authentication#claude-console-authentication) for setup.

302* If you are the admin and do not see an option to enable access, contact [Anthropic support](https://support.claude.com)

303 

286### Routines are disabled by your organization's policy304### Routines are disabled by your organization's policy

287 305 

288Your Team or Enterprise admin has turned off routines at the organization level. The error appears when you try to create or run a routine, including from `/schedule` and the [Routines](/en/routines) UI on claude.ai/code.306Your Team or Enterprise admin has turned off routines at the organization level. The error appears when you try to create or run a routine, including from `/schedule` and the [Routines](/en/routines) UI on claude.ai/code.

573 591 

574* Run `/rewind`, or press Esc twice, to step back to a checkpoint before the corrupted turn and continue from there. See [Checkpointing](/en/checkpointing) for how checkpoints are created and restored.592* Run `/rewind`, or press Esc twice, to step back to a checkpoint before the corrupted turn and continue from there. See [Checkpointing](/en/checkpointing) for how checkpoints are created and restored.

575 593 

594### Usage Policy refusal

595 

596The API declined to respond because content in the conversation triggered a [Usage Policy](https://www.anthropic.com/legal/aup) check. The message includes a Request ID you can quote to support if you believe the refusal is incorrect.

597 

598```text theme={null}

599API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.

600```

601 

602The check evaluates the full conversation, not only your latest prompt, so sending a new message in the same session usually re-triggers the same refusal. The same applies after exiting and reopening the session with `--continue` or `--resume`, since the transcript on disk still contains the triggering content.

603 

604**What to do:**

605 

606* Press Esc twice or run `/rewind` to step back to a checkpoint before the turn that triggered the refusal, then rephrase or take a different approach. See [Checkpointing](/en/checkpointing).

607* If you cannot identify which turn caused it, run `/clear` to start a fresh conversation in the same project. Your previous conversation is preserved on disk and remains available in `/resume`.

608* In [non-interactive mode](/en/headless) (`-p`), where rewind is unavailable, retry with a rephrased prompt or start a new session without `--continue`.

609 

576## Responses seem lower quality than usual610## Responses seem lower quality than usual

577 611 

578If Claude's answers seem less capable than you expect but no error is shown, the cause is usually conversation state rather than the model itself. Claude Code does not silently change model versions. It can switch to a fallback model in specific cases such as an Opus quota being reached or a Bedrock or Vertex AI region lacking your model; the Model selection check below catches both, and [Model configuration](/en/model-config) explains when fallback applies.612If Claude's answers seem less capable than you expect but no error is shown, the cause is usually conversation state rather than the model itself. Claude Code does not silently change model versions. It can switch to a fallback model in specific cases such as an Opus quota being reached or a Bedrock or Vertex AI region lacking your model; the Model selection check below catches both, and [Model configuration](/en/model-config) explains when fallback applies.

206 206 

207### Project trust207### Project trust

208 208 

209A one-time dialog accepting a directory before Claude Code loads its configuration. Trust gates auto-installation of marketplace plugins and execution of project-defined hooks. Trusting a directory means its `.claude/settings.json`, `.mcp.json`, and other config files take effect.209A dialog accepting a directory before Claude Code loads its configuration. Acceptance is saved per project directory, except your home directory, where trust is held for the current session only and the prompt reappears on each launch. Trust gates auto-installation of marketplace plugins and execution of project-defined hooks. Trusting a directory means its `.claude/settings.json`, `.mcp.json`, and other config files take effect.

210 210 

211Learn more: [The `.claude` directory](/en/claude-directory)211Learn more: [The `.claude` directory](/en/claude-directory)

212 212 

40Claude Code authenticates with Anthropic's servers using OAuth tokens or API keys. These authentication methods serve different purposes:40Claude Code authenticates with Anthropic's servers using OAuth tokens or API keys. These authentication methods serve different purposes:

41 41 

42* **OAuth authentication** is intended exclusively for purchasers of Claude Free, Pro, Max, Team, and Enterprise subscription plans and is designed to support ordinary use of Claude Code and other native Anthropic applications. More information about how users can authenticate with OAuth tokens can be found in [Logging in to your Claude account](https://support.claude.com/en/articles/13189465-logging-in-to-your-claude-account).42* **OAuth authentication** is intended exclusively for purchasers of Claude Free, Pro, Max, Team, and Enterprise subscription plans and is designed to support ordinary use of Claude Code and other native Anthropic applications. More information about how users can authenticate with OAuth tokens can be found in [Logging in to your Claude account](https://support.claude.com/en/articles/13189465-logging-in-to-your-claude-account).

43* **Developers** building products or services that interact with Claude's capabilities, including those using the [Agent SDK](/en/agent-sdk/overview), should use API key authentication through [Claude Console](https://platform.claude.com/) or a supported cloud provider. Anthropic does not permit third-party developers to offer Claude.ai login or to route requests through Free, Pro, or Max plan credentials on behalf of their users.43* **Developers** building products or services that interact with Claude's capabilities, including those using the [Agent SDK](/en/agent-sdk/overview), should use API key authentication through [Claude Console](../../../platform.claude.com/index.txt) or a supported cloud provider. Anthropic does not permit third-party developers to offer Claude.ai login or to route requests through Free, Pro, or Max plan credentials on behalf of their users.

44 44 

45Anthropic reserves the right to take measures to enforce these restrictions and may do so without prior notice.45Anthropic reserves the right to take measures to enforce these restrictions and may do so without prior notice.

46 46 

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Claude Code on Microsoft Foundry

6 

7> Learn about configuring Claude Code through Microsoft Foundry, including setup, configuration, and troubleshooting.

8 

9export const ContactSalesCard = ({surface}) => {

10 const utm = content => `utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}`;

11 const iconArrowRight = (size = 13) => <svg width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">

12 <line x1="5" y1="12" x2="19" y2="12" />

13 <polyline points="12 5 19 12 12 19" />

14 </svg>;

15 const STYLES = `

16.cc-cs {

17 --cs-slate: #141413;

18 --cs-clay: #d97757;

19 --cs-clay-deep: #c6613f;

20 --cs-gray-000: #ffffff;

21 --cs-gray-700: #3d3d3a;

22 --cs-border-default: rgba(31, 30, 29, 0.15);

23 font-family: inherit;

24}

25.dark .cc-cs {

26 --cs-slate: #f0eee6;

27 --cs-gray-000: #262624;

28 --cs-gray-700: #bfbdb4;

29 --cs-border-default: rgba(240, 238, 230, 0.14);

30}

31.cc-cs-card {

32 display: flex; align-items: center; justify-content: space-between;

33 gap: 16px; padding: 14px 16px; margin: 0;

34 background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default);

35 border-radius: 8px; flex-wrap: wrap;

36}

37.cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; }

38.cc-cs-text strong { font-weight: 550; color: var(--cs-slate); }

39.cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }

40.cc-cs-btn-clay {

41 display: inline-flex; align-items: center; gap: 8px;

42 background: var(--cs-clay-deep); color: #fff; border: none;

43 border-radius: 8px; padding: 8px 14px;

44 font-size: 13px; font-weight: 500;

45 transition: background-color 0.15s; white-space: nowrap;

46}

47.cc-cs-btn-clay:hover { background: var(--cs-clay); }

48.cc-cs-btn-ghost {

49 display: inline-flex; align-items: center; gap: 8px;

50 background: transparent; color: var(--cs-gray-700);

51 border: 0.5px solid var(--cs-border-default);

52 border-radius: 8px; padding: 8px 14px;

53 font-size: 13px; font-weight: 500;

54}

55.cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); }

56.dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); }

57@media (max-width: 720px) {

58 .cc-cs-actions { width: 100%; }

59}

60`;

61 return <div className="cc-cs not-prose">

62 <style>{STYLES}</style>

63 <div className="cc-cs-card">

64 <div className="cc-cs-text">

65 <strong>Deploying Claude Code across your organization?</strong> Talk to sales about enterprise plans, SSO, and centralized billing.

66 </div>

67 <div className="cc-cs-actions">

68 <a href={`https://claude.com/pricing?${utm('view_plans')}#plans-business`} className="cc-cs-btn-ghost">

69 View plans

70 </a>

71 <a href={`https://claude.com/contact-sales?${utm('contact_sales')}`} className="cc-cs-btn-clay">

72 Contact sales {iconArrowRight()}

73 </a>

74 </div>

75 </div>

76 </div>;

77};

78 

79<ContactSalesCard surface="foundry" />

80 

81## Prerequisites

82 

83Before configuring Claude Code with Microsoft Foundry, ensure you have:

84 

85* An Azure subscription with access to Microsoft Foundry

86* RBAC permissions to create Microsoft Foundry resources and deployments

87* Azure CLI installed and configured (optional - only needed if you don't have another mechanism for getting credentials)

88 

89<Note>

90 If you are deploying Claude Code to multiple users, [pin your model versions](#4-pin-model-versions) to prevent breakage when Anthropic releases new models.

91</Note>

92 

93## Setup

94 

95### 1. Provision Microsoft Foundry resource

96 

97First, create a Claude resource in Azure:

98 

991. Navigate to the [Microsoft Foundry portal](https://ai.azure.com/)

1002. Create a new resource, noting your resource name

1013. Create deployments for the Claude models:

102 * Claude Opus

103 * Claude Sonnet

104 * Claude Haiku

105 

106### 2. Configure Azure credentials

107 

108Claude Code supports two authentication methods for Microsoft Foundry. Choose the method that best fits your security requirements.

109 

110**Option A: API key authentication**

111 

1121. Navigate to your resource in the Microsoft Foundry portal

1132. Go to the **Endpoints and keys** section

1143. Copy **API Key**

1154. Set the environment variable:

116 

117```bash theme={null}

118export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

119```

120 

121**Option B: Microsoft Entra ID authentication**

122 

123When `ANTHROPIC_FOUNDRY_API_KEY` is not set, Claude Code automatically uses the Azure SDK [default credential chain](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview).

124This supports a variety of methods for authenticating local and remote workloads.

125 

126On local environments, you commonly may use the Azure CLI:

127 

128```bash theme={null}

129az login

130```

131 

132<Note>

133 When using Microsoft Foundry, the `/login` and `/logout` commands are disabled since authentication is handled through Azure credentials.

134</Note>

135 

136### 3. Configure Claude Code

137 

138Set the following environment variables to enable Microsoft Foundry:

139 

140```bash theme={null}

141# Enable Microsoft Foundry integration

142export CLAUDE_CODE_USE_FOUNDRY=1

143 

144# Azure resource name (replace {resource} with your resource name)

145export ANTHROPIC_FOUNDRY_RESOURCE={resource}

146# Or provide the full base URL:

147# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

148```

149 

150### 4. Pin model versions

151 

152<Warning>

153 Pin specific model versions for every deployment. If you use model aliases (`sonnet`, `opus`, `haiku`) without pinning, Claude Code may attempt to use a newer model version that isn't available in your Foundry account, breaking existing users when Anthropic releases updates. When you create Azure deployments, select a specific model version rather than "auto-update to latest."

154</Warning>

155 

156Set the model variables to match the deployment names you created in step 1.

157 

158Without `ANTHROPIC_DEFAULT_OPUS_MODEL`, the `opus` alias on Foundry resolves to Opus 4.6. Set it to the Opus 4.7 ID to use the latest model:

159 

160```bash theme={null}

161export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'

162export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'

163export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

164```

165 

166Background tasks such as session title generation use the small/fast model, normally a Haiku-class model. On Foundry, Claude Code defaults this to the primary model because not every account has a Haiku deployment. To use Haiku for background tasks, set `ANTHROPIC_DEFAULT_HAIKU_MODEL` to a Haiku deployment that is available in your account, as shown above.

167 

168For current and legacy model IDs, see [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview). See [Model configuration](/en/model-config#pin-models-for-third-party-deployments) for the full list of environment variables.

169 

170[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) is enabled automatically. To request a 1-hour cache TTL instead of the 5-minute default, set the following variable; cache writes with a 1-hour TTL are billed at a higher rate:

171 

172```bash theme={null}

173export ENABLE_PROMPT_CACHING_1H=1

174```

175 

176### 5. Run Claude Code

177 

178With the environment variables set, start Claude Code from your project directory:

179 

180```bash theme={null}

181claude

182```

183 

184Claude Code reads `CLAUDE_CODE_USE_FOUNDRY` and the other Foundry variables from the environment and connects to your Azure resource on the first prompt. Unlike Bedrock and Vertex AI, Foundry has no interactive setup wizard, so the environment variables in steps 3 and 4 are the only configuration path.

185 

186## Azure RBAC configuration

187 

188The `Azure AI User` and `Cognitive Services User` default roles include all required permissions for invoking Claude models.

189 

190For more restrictive permissions, create a custom role with the following:

191 

192```json theme={null}

193{

194 "permissions": [

195 {

196 "dataActions": [

197 "Microsoft.CognitiveServices/accounts/providers/*"

198 ]

199 }

200 ]

201}

202```

203 

204For details, see [Microsoft Foundry RBAC documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry).

205 

206## Troubleshooting

207 

208If you receive an error "Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed":

209 

210* Configure Entra ID on the environment, or set `ANTHROPIC_FOUNDRY_API_KEY`.

211 

212## Additional resources

213 

214* [Microsoft Foundry documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-azure-ai-foundry)

215* [Microsoft Foundry models](https://ai.azure.com/explore/models)

216* [Microsoft Foundry pricing](https://azure.microsoft.com/en-us/pricing/details/ai-foundry/)

1093 1093 

1094## Monitor Claude Code on Amazon Bedrock1094## Monitor Claude Code on Amazon Bedrock

1095 1095 

1096For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).1096For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](../../../raw.githubusercontent.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/main/assets/docs/MONITORING.md).

60* **Isolated context windows**: Web fetch uses a separate context window to avoid injecting potentially malicious prompts60* **Isolated context windows**: Web fetch uses a separate context window to avoid injecting potentially malicious prompts

61* **Trust verification**: First-time codebase runs and new MCP servers require trust verification61* **Trust verification**: First-time codebase runs and new MCP servers require trust verification

62 * Note: Trust verification is disabled when running non-interactively with the `-p` flag. The exception is [`--worktree`](/en/worktrees), which still requires that trust has been accepted for the directory62 * Note: Trust verification is disabled when running non-interactively with the `-p` flag. The exception is [`--worktree`](/en/worktrees), which still requires that trust has been accepted for the directory

63 * Note: When you start Claude Code directly in your home directory, trust acceptance is held for the current session only and is not written to disk, so the prompt reappears on each launch. There is no setting to persist it. Start Claude Code from a project subdirectory instead, where trust acceptance is saved per directory

63* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted64* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted

64* **Fail-closed matching**: Unmatched commands default to requiring manual approval65* **Fail-closed matching**: Unmatched commands default to requiring manual approval

65* **Natural language descriptions**: Complex bash commands include explanations for user understanding66* **Natural language descriptions**: Complex bash commands include explanations for user understanding

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Manage sessions

6 

7> Name, resume, branch, and switch between Claude Code conversations. Covers `--continue`, `--resume`, `--from-pr`, the `/resume` picker, session naming, and where transcripts are stored.

8 

9A session is a saved conversation tied to a project directory. Claude Code stores it locally as you work, so you can resume where you left off, branch to try a different approach, or switch between tasks.

10 

11The [desktop app](/en/desktop#work-in-parallel-with-sessions), [Claude Code on the web](/en/claude-code-on-the-web), and the [VS Code extension](/en/vs-code#resume-past-conversations) each maintain their own session history. This page covers the CLI:

12 

13* [Resume](#resume-a-session) a previous conversation by flag, name, or PR

14* [Name](#name-your-sessions) sessions so you can find them later

15* [Browse](#use-the-session-picker) sessions with the `/resume` picker

16* [Branch](#branch-a-session) a conversation to try a different approach

17* [Export](#export-and-locate-session-data) transcripts and find them on disk

18 

19## Resume a session

20 

21Sessions are saved continuously to [local transcript files](#export-and-locate-session-data) as you work, so you can return to one after exiting or running `/clear`. Use these entry points:

22 

23| Command | What it does |

24| :-------------------------- | :----------------------------------------------------------------- |

25| `claude --continue` | Resumes the most recent session in the current directory |

26| `claude --resume` | Opens the [session picker](#use-the-session-picker) |

27| `claude --resume <name>` | Resumes the named session directly |

28| `claude --from-pr <number>` | Resumes the session linked to that pull request |

29| `/resume` | Switches to a different conversation from inside an active session |

30 

31Sessions created with [`claude -p`](/en/headless) or the [Agent SDK](/en/agent-sdk/overview) do not appear in the session picker, but you can still resume one by passing its session ID to `claude --resume <session-id>`.

32 

33### Where the session picker looks

34 

35Sessions are stored per project directory. By default the session picker shows interactive sessions from the current worktree, plus sessions started elsewhere that added the current directory with `/add-dir`. Use `Ctrl+W` to widen to all worktrees of the repository or `Ctrl+A` to widen to every project on this machine.

36 

37Selecting a session from another worktree of the same repository resumes it in place. Selecting a session from an unrelated project copies a `cd` and resume command to your clipboard instead.

38 

39Resuming by name resolves across the current repository and its worktrees. Both forms look for an exact match and resume it directly even if it lives in a different worktree:

40 

41| Command | Exact match | Ambiguous name |

42| :----------------------- | :--------------- | :-------------------------------------------------------------------------- |

43| `claude --resume <name>` | Resumes directly | Opens the session picker with the name pre-filled as a search term |

44| `/resume <name>` | Resumes directly | Reports an error; run `/resume` with no argument to open the session picker |

45 

46## Name your sessions

47 

48Give sessions descriptive names so they're findable in the session picker and resumable by name. This matters most when you're working on several tasks in parallel.

49 

50| When | How to set the name |

51| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

52| At startup | `claude -n auth-refactor` |

53| During a session | `/rename auth-refactor`. The name also appears on the prompt bar |

54| From the session picker | Highlight a session and press `Ctrl+R` |

55| On plan accept | Accepting a plan in [plan mode](/en/permission-modes#analyze-before-you-edit-with-plan-mode) names the session from the plan content unless you've already set one |

56 

57Once a session is named, return to it with `claude --resume <name>` or `/resume <name>`. See [Resume a session](#resume-a-session) for how name resolution behaves across worktrees.

58 

59## Use the session picker

60 

61Run `/resume` inside a session, or `claude --resume` with no arguments, to open the interactive session picker. Use these keyboard shortcuts to navigate, search, and widen the list:

62 

63| Shortcut | Action |

64| :------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |

65| `↑` / `↓` | Navigate between sessions |

66| `→` / `←` | Expand or collapse grouped sessions |

67| `Enter` | Resume the highlighted session |

68| `Space` | Preview the session content. `Ctrl+V` also works on terminals that don't capture it as paste |

69| `Ctrl+R` | Rename the highlighted session |

70| `/` or any printable character other than `Space` | Enter search mode and filter sessions. Paste a GitHub, GitHub Enterprise, GitLab, or Bitbucket pull or merge request URL to find the session that created it |

71| `Ctrl+A` | Show sessions from all projects on this machine. Press again to return to the current repository |

72| `Ctrl+W` | Show sessions from all worktrees of the current repository. Press again to return to the current worktree. Only shown in multi-worktree repositories |

73| `Ctrl+B` | Filter to sessions from the current git branch. Press again to show all branches |

74| `Esc` | Exit the session picker or search mode |

75 

76Each row shows the session name if set, otherwise the conversation summary or first prompt, along with time since last activity, message count, and git branch. Project path appears after you widen to all projects with `Ctrl+A`.

77 

78Forked sessions created with `/branch`, `/rewind`, or `--fork-session` are grouped under their root session. Press `→` to expand a group.

79 

80## Branch a session

81 

82Branching creates a copy of the conversation so far and switches you into it, leaving the original intact. Use it to try a different approach without losing the path you were on.

83 

84From inside a session, run `/branch` with an optional name:

85 

86```text theme={null}

87/branch try-streaming-approach

88```

89 

90From the command line, combine `--continue` or `--resume` with `--fork-session`:

91 

92```bash theme={null}

93claude --continue --fork-session

94```

95 

96The original session is unchanged and remains available in the session picker. The `/branch` confirmation prints two session IDs: the new branch you are now in and the original. To return to the original, pass its ID to `/resume`, use the session picker, or run `/resume <original-name>`. Permissions you approved with "allow for this session" do not carry over to the new branch. If you resume the same session in two terminals without forking, messages from both interleave into one transcript.

97 

98For checkpoint-based rewind within a single session, see [Checkpointing](/en/checkpointing).

99 

100## Manage context within a session

101 

102These commands control what's in the context window without leaving the session:

103 

104* **`/clear`**: start fresh with an empty context. The previous conversation is saved and resumable

105* **`/compact [instructions]`**: replace history with a summary, optionally focused on what you specify

106* **`/context`**: show what is currently consuming context

107 

108For how compaction interacts with CLAUDE.md, skills, and rules, see the [context window guide](/en/context-window). For strategies on when to clear versus compact, see [Best practices](/en/best-practices#manage-your-session).

109 

110## Export and locate session data

111 

112Run `/export` to copy the current conversation to your clipboard or save it as a plain-text file, with messages and tool outputs rendered as readable text. Pass a filename to write directly to that file.

113 

114Transcripts are stored as JSONL at `~/.claude/projects/<project>/<session-id>.jsonl`, where `<project>` is derived from your working directory path. Each line is a JSON object for a message, tool use, or metadata entry. To store sessions somewhere other than `~/.claude`, set [`CLAUDE_CONFIG_DIR`](/en/env-vars). These local files are removed after 30 days by default; change this with [`cleanupPeriodDays`](/en/settings#available-settings).

115 

116To suppress transcript writes entirely, set [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/en/env-vars), or in non-interactive mode use `--no-session-persistence`.

117 

118## See also

119 

120These pages cover related session and parallelism mechanics:

121 

122* [Worktrees](/en/worktrees): run isolated parallel sessions on separate branches

123* [Checkpointing](/en/checkpointing): rewind code and conversation to an earlier point

124* [Context window](/en/context-window): what fills context and what survives compaction

125* [Non-interactive mode](/en/headless): session behavior under `claude -p`

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Extend Claude with skills

6 

7> Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom commands and bundled skills.

8 

9Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`.

10 

11Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.

12 

13<Note>

14 For built-in commands like `/help` and `/compact`, and bundled skills like `/debug` and `/simplify`, see the [commands reference](/en/commands).

15 

16 **Custom commands have been merged into skills.** A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way. Your existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to [control whether you or Claude invokes them](#control-who-invokes-a-skill), and the ability for Claude to load them automatically when relevant.

17</Note>

18 

19Claude Code skills follow the [Agent Skills](https://agentskills.io) open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like [invocation control](#control-who-invokes-a-skill), [subagent execution](#run-skills-in-a-subagent), and [dynamic context injection](#inject-dynamic-context).

20 

21## Bundled skills

22 

23Claude Code includes a set of bundled skills that are available in every session, including `/simplify`, `/batch`, `/debug`, `/loop`, and `/claude-api`. Unlike most built-in commands, which execute fixed logic directly, bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work using its tools. You invoke them the same way as any other skill, by typing `/` followed by the skill name.

24 

25Bundled skills are listed alongside built-in commands in the [commands reference](/en/commands), marked **Skill** in the Purpose column.

26 

27## Getting started

28 

29### Create your first skill

30 

31This example creates a skill that summarizes the uncommitted changes in your git repository and flags anything risky. It pulls the live diff into the prompt before Claude reads it, so the response is grounded in your actual working tree rather than what Claude can guess from open files. Claude loads the skill automatically when you ask about your changes, or you can invoke it directly with `/summarize-changes`.

32 

33<Steps>

34 <Step title="Create the skill directory">

35 Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.

36 

37 ```bash theme={null}

38 mkdir -p ~/.claude/skills/summarize-changes

39 ```

40 </Step>

41 

42 <Step title="Write SKILL.md">

43 Every skill needs a `SKILL.md` file with two parts: YAML frontmatter between `---` markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs. The directory name becomes the command you type, and the `description` helps Claude decide when to load the skill automatically.

44 

45 Save this to `~/.claude/skills/summarize-changes/SKILL.md`:

46 

47 ```yaml theme={null}

48 ---

49 description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.

50 ---

51 

52 ## Current changes

53 

54 !`git diff HEAD`

55 

56 ## Instructions

57 

58 Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

59 ```

60 

61 The `` !`git diff HEAD` `` line uses [dynamic context injection](#inject-dynamic-context): Claude Code runs the command and replaces the line with its output before Claude sees the skill content, so the instructions arrive with the current diff already inlined.

62 </Step>

63 

64 <Step title="Test the skill">

65 Open a git project, make a small edit to any file, and start Claude Code by running `claude`. You can test the skill two ways.

66 

67 **Let Claude invoke it automatically** by asking something that matches the description:

68 

69 ```text theme={null}

70 What did I change?

71 ```

72 

73 **Or invoke it directly** with the skill name:

74 

75 ```text theme={null}

76 /summarize-changes

77 ```

78 

79 Either way, Claude should respond with a short summary of your edit and a list of risks.

80 </Step>

81</Steps>

82 

83### Where skills live

84 

85Where you store a skill determines who can use it:

86 

87| Location | Path | Applies to |

88| :--------- | :-------------------------------------------------- | :----------------------------- |

89| Enterprise | See [managed settings](/en/settings#settings-files) | All users in your organization |

90| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects |

91| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |

92| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |

93 

94When skills share the same name across levels, enterprise overrides personal, and personal overrides project. Plugin skills use a `plugin-name:skill-name` namespace, so they cannot conflict with other levels. If you have files in `.claude/commands/`, those work the same way, but if a skill and a command share the same name, the skill takes precedence.

95 

96#### Live change detection

97 

98Claude Code watches skill directories for file changes. Adding, editing, or removing a skill under `~/.claude/skills/`, the project `.claude/skills/`, or a `.claude/skills/` inside an `--add-dir` directory takes effect within the current session without restarting. Creating a top-level skills directory that did not exist when the session started requires restarting Claude Code so the new directory can be watched.

99 

100#### Automatic discovery from parent and nested directories

101 

102Project skills load from `.claude/skills/` in your starting directory and in every parent directory up to the repository root, so starting Claude in a subdirectory still picks up skills defined at the root. When you work with files in subdirectories below your starting directory, Claude Code also discovers skills from nested `.claude/skills/` directories on demand. For example, if you're editing a file in `packages/frontend/`, Claude Code also looks for skills in `packages/frontend/.claude/skills/`. This supports monorepo setups where packages have their own skills.

103 

104Each skill is a directory with `SKILL.md` as the entrypoint:

105 

106```text theme={null}

107my-skill/

108├── SKILL.md # Main instructions (required)

109├── template.md # Template for Claude to fill in

110├── examples/

111│ └── sample.md # Example output showing expected format

112└── scripts/

113 └── validate.sh # Script Claude can execute

114```

115 

116The `SKILL.md` contains the main instructions and is required. Other files are optional and let you build more powerful skills: templates for Claude to fill in, example outputs showing the expected format, scripts Claude can execute, or detailed reference documentation. Reference these files from your `SKILL.md` so Claude knows what they contain and when to load them. See [Add supporting files](#add-supporting-files) for more details.

117 

118<Note>

119 Files in `.claude/commands/` still work and support the same [frontmatter](#frontmatter-reference). Skills are recommended since they support additional features like supporting files.

120</Note>

121 

122#### Skills from additional directories

123 

124The `--add-dir` flag [grants file access](/en/permissions#additional-directories-grant-file-access-not-configuration) rather than configuration discovery, but skills are an exception: `.claude/skills/` within an added directory is loaded automatically. See [Live change detection](#live-change-detection) for how edits are picked up during a session.

125 

126Other `.claude/` configuration such as subagents, commands, and output styles is not loaded from additional directories. See the [exceptions table](/en/permissions#additional-directories-grant-file-access-not-configuration) for the complete list of what is and isn't loaded, and the recommended ways to share configuration across projects.

127 

128<Note>

129 CLAUDE.md files from `--add-dir` directories are not loaded by default. To load them, set `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`. See [Load from additional directories](/en/memory#load-from-additional-directories).

130</Note>

131 

132## Configure skills

133 

134Skills are configured through YAML frontmatter at the top of `SKILL.md` and the markdown content that follows.

135 

136### Types of skill content

137 

138Skill files can contain any instructions, but thinking about how you want to invoke them helps guide what to include:

139 

140**Reference content** adds knowledge Claude applies to your current work. Conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context.

141 

142```yaml theme={null}

143---

144name: api-conventions

145description: API design patterns for this codebase

146---

147 

148When writing API endpoints:

149- Use RESTful naming conventions

150- Return consistent error formats

151- Include request validation

152```

153 

154**Task content** gives Claude step-by-step instructions for a specific action, like deployments, commits, or code generation. These are often actions you want to invoke directly with `/skill-name` rather than letting Claude decide when to run them. Add `disable-model-invocation: true` to prevent Claude from triggering it automatically.

155 

156```yaml theme={null}

157---

158name: deploy

159description: Deploy the application to production

160context: fork

161disable-model-invocation: true

162---

163 

164Deploy the application:

1651. Run the test suite

1662. Build the application

1673. Push to the deployment target

168```

169 

170Your `SKILL.md` can contain anything, but thinking through how you want the skill invoked (by you, by Claude, or both) and where you want it to run (inline or in a subagent) helps guide what to include. For complex skills, you can also [add supporting files](#add-supporting-files) to keep the main skill focused.

171 

172Keep the body itself concise. Once a skill loads, its content [stays in context across turns](#skill-content-lifecycle), so every line is a recurring token cost. State what to do rather than narrating how or why, and apply the same conciseness test you would for [CLAUDE.md content](/en/best-practices#write-an-effective-claude-md).

173 

174### Frontmatter reference

175 

176Beyond the markdown content, you can configure skill behavior using YAML frontmatter fields between `---` markers at the top of your `SKILL.md` file:

177 

178```yaml theme={null}

179---

180name: my-skill

181description: What this skill does

182disable-model-invocation: true

183allowed-tools: Read Grep

184---

185 

186Your skill instructions here...

187```

188 

189All fields are optional. Only `description` is recommended so Claude knows when to use the skill.

190 

191| Field | Required | Description |

192| :------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

193| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |

194| `description` | Recommended | What the skill does and when to use it. Claude uses this to decide when to apply the skill. If omitted, uses the first paragraph of markdown content. Put the key use case first: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing to reduce context usage. |

195| `when_to_use` | No | Additional context for when Claude should invoke the skill, such as trigger phrases or example requests. Appended to `description` in the skill listing and counts toward the 1,536-character cap. |

196| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |

197| `arguments` | No | Named positional arguments for [`$name` substitution](#available-string-substitutions) in the skill content. Accepts a space-separated string or a YAML list. Names map to argument positions in order. |

198| `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Use for workflows you want to trigger manually with `/name`. Also prevents the skill from being [preloaded into subagents](/en/sub-agents#preload-skills-into-subagents). Default: `false`. |

199| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |

200| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |

201| `model` | No | Model to use when this skill is active. The override applies for the rest of the current turn and is not saved to settings; the session model resumes on your next prompt. Accepts the same values as [`/model`](/en/model-config), or `inherit` to keep the active model. |

202| `effort` | No | [Effort level](/en/model-config#adjust-effort-level) when this skill is active. Overrides the session effort level. Default: inherits from session. Options: `low`, `medium`, `high`, `xhigh`, `max`; available levels depend on the model. |

203| `context` | No | Set to `fork` to run in a forked subagent context. |

204| `agent` | No | Which subagent type to use when `context: fork` is set. |

205| `hooks` | No | Hooks scoped to this skill's lifecycle. See [Hooks in skills and agents](/en/hooks#hooks-in-skills-and-agents) for configuration format. |

206| `paths` | No | Glob patterns that limit when this skill is activated. Accepts a comma-separated string or a YAML list. When set, Claude loads the skill automatically only when working with files matching the patterns. Uses the same format as [path-specific rules](/en/memory#path-specific-rules). |

207| `shell` | No | Shell to use for `` !`command` `` and ` ```! ` blocks in this skill. Accepts `bash` (default) or `powershell`. Setting `powershell` runs inline shell commands via PowerShell on Windows. Requires `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. |

208 

209#### Available string substitutions

210 

211Skills support string substitution for dynamic values in the skill content:

212 

213| Variable | Description |

214| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

215| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |

216| `$ARGUMENTS[N]` | Access a specific argument by 0-based index, such as `$ARGUMENTS[0]` for the first argument. |

217| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |

218| `$name` | Named argument declared in the [`arguments`](#frontmatter-reference) frontmatter list. Names map to positions in order, so with `arguments: [issue, branch]` the placeholder `$issue` expands to the first argument and `$branch` to the second. |

219| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |

220| `${CLAUDE_EFFORT}` | The current effort level: `low`, `medium`, `high`, `xhigh`, or `max`. Use this to adapt skill instructions to the active effort setting. |

221| `${CLAUDE_SKILL_DIR}` | The directory containing the skill's `SKILL.md` file. For plugin skills, this is the skill's subdirectory within the plugin, not the plugin root. Use this in bash injection commands to reference scripts or files bundled with the skill, regardless of the current working directory. |

222 

223Indexed arguments use shell-style quoting, so wrap multi-word values in quotes to pass them as a single argument. For example, `/my-skill "hello world" second` makes `$0` expand to `hello world` and `$1` to `second`. The `$ARGUMENTS` placeholder always expands to the full argument string as typed.

224 

225**Example using substitutions:**

226 

227```yaml theme={null}

228---

229name: session-logger

230description: Log activity for this session

231---

232 

233Log the following to logs/${CLAUDE_SESSION_ID}.log:

234 

235$ARGUMENTS

236```

237 

238### Add supporting files

239 

240Skills can include multiple files in their directory. This keeps `SKILL.md` focused on the essentials while letting Claude access detailed reference material only when needed. Large reference docs, API specifications, or example collections don't need to load into context every time the skill runs.

241 

242```text theme={null}

243my-skill/

244├── SKILL.md (required - overview and navigation)

245├── reference.md (detailed API docs - loaded when needed)

246├── examples.md (usage examples - loaded when needed)

247└── scripts/

248 └── helper.py (utility script - executed, not loaded)

249```

250 

251Reference supporting files from `SKILL.md` so Claude knows what each file contains and when to load it:

252 

253```markdown theme={null}

254## Additional resources

255 

256- For complete API details, see [reference.md](reference.md)

257- For usage examples, see [examples.md](examples.md)

258```

259 

260<Tip>Keep `SKILL.md` under 500 lines. Move detailed reference material to separate files.</Tip>

261 

262### Control who invokes a skill

263 

264By default, both you and Claude can invoke any skill. You can type `/skill-name` to invoke it directly, and Claude can load it automatically when relevant to your conversation. Two frontmatter fields let you restrict this:

265 

266* **`disable-model-invocation: true`**: Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing, like `/commit`, `/deploy`, or `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.

267 

268* **`user-invocable: false`**: Only Claude can invoke the skill. Use this for background knowledge that isn't actionable as a command. A `legacy-system-context` skill explains how an old system works. Claude should know this when relevant, but `/legacy-system-context` isn't a meaningful action for users to take.

269 

270This example creates a deploy skill that only you can trigger. The `disable-model-invocation: true` field prevents Claude from running it automatically:

271 

272```yaml theme={null}

273---

274name: deploy

275description: Deploy the application to production

276disable-model-invocation: true

277---

278 

279Deploy $ARGUMENTS to production:

280 

2811. Run the test suite

2822. Build the application

2833. Push to the deployment target

2844. Verify the deployment succeeded

285```

286 

287Here's how the two fields affect invocation and context loading:

288 

289| Frontmatter | You can invoke | Claude can invoke | When loaded into context |

290| :------------------------------- | :------------- | :---------------- | :----------------------------------------------------------- |

291| (default) | Yes | Yes | Description always in context, full skill loads when invoked |

292| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |

293| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |

294 

295<Note>

296 In a regular session, skill descriptions are loaded into context so Claude knows what's available, but full skill content only loads when invoked. [Subagents with preloaded skills](/en/sub-agents#preload-skills-into-subagents) work differently: the full skill content is injected at startup.

297</Note>

298 

299### Skill content lifecycle

300 

301When you or Claude invoke a skill, the rendered `SKILL.md` content enters the conversation as a single message and stays there for the rest of the session. Claude Code does not re-read the skill file on later turns, so write guidance that should apply throughout a task as standing instructions rather than one-time steps.

302 

303[Auto-compaction](/en/how-claude-code-works#when-context-fills-up) carries invoked skills forward within a token budget. When the conversation is summarized to free context, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens. Claude Code fills this budget starting from the most recently invoked skill, so older skills can be dropped entirely after compaction if you have invoked many in one session.

304 

305If a skill seems to stop influencing behavior after the first response, the content is usually still present and the model is choosing other tools or approaches. Strengthen the skill's `description` and instructions so the model keeps preferring it, or use [hooks](/en/hooks) to enforce behavior deterministically. If the skill is large or you invoked several others after it, re-invoke it after compaction to restore the full content.

306 

307### Pre-approve tools for a skill

308 

309The `allowed-tools` field grants permission for the listed tools while the skill is active, so Claude can use them without prompting you for approval. It does not restrict which tools are available: every tool remains callable, and your [permission settings](/en/permissions) still govern tools that are not listed.

310 

311For skills checked into a project's `.claude/skills/` directory, `allowed-tools` takes effect after you accept the workspace trust dialog for that folder, the same as permission rules in `.claude/settings.json`. Review project skills before trusting a repository, since a skill can grant itself broad tool access.

312 

313This skill lets Claude run git commands without per-use approval whenever you invoke it:

314 

315```yaml theme={null}

316---

317name: commit

318description: Stage and commit the current changes

319disable-model-invocation: true

320allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)

321---

322```

323 

324To block a skill from using certain tools, add deny rules in your [permission settings](/en/permissions) instead.

325 

326### Pass arguments to skills

327 

328Both you and Claude can pass arguments when invoking a skill. Arguments are available via the `$ARGUMENTS` placeholder.

329 

330This skill fixes a GitHub issue by number. The `$ARGUMENTS` placeholder gets replaced with whatever follows the skill name:

331 

332```yaml theme={null}

333---

334name: fix-issue

335description: Fix a GitHub issue

336disable-model-invocation: true

337---

338 

339Fix GitHub issue $ARGUMENTS following our coding standards.

340 

3411. Read the issue description

3422. Understand the requirements

3433. Implement the fix

3444. Write tests

3455. Create a commit

346```

347 

348When you run `/fix-issue 123`, Claude receives "Fix GitHub issue 123 following our coding standards..."

349 

350If you invoke a skill with arguments but the skill doesn't include `$ARGUMENTS`, Claude Code appends `ARGUMENTS: <your input>` to the end of the skill content so Claude still sees what you typed.

351 

352To access individual arguments by position, use `$ARGUMENTS[N]` or the shorter `$N`:

353 

354```yaml theme={null}

355---

356name: migrate-component

357description: Migrate a component from one framework to another

358---

359 

360Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].

361Preserve all existing behavior and tests.

362```

363 

364Running `/migrate-component SearchBar React Vue` replaces `$ARGUMENTS[0]` with `SearchBar`, `$ARGUMENTS[1]` with `React`, and `$ARGUMENTS[2]` with `Vue`. The same skill using the `$N` shorthand:

365 

366```yaml theme={null}

367---

368name: migrate-component

369description: Migrate a component from one framework to another

370---

371 

372Migrate the $0 component from $1 to $2.

373Preserve all existing behavior and tests.

374```

375 

376## Advanced patterns

377 

378### Inject dynamic context

379 

380The `` !`<command>` `` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder, so Claude receives actual data, not the command itself.

381 

382This skill summarizes a pull request by fetching live PR data with the GitHub CLI. The `` !`gh pr diff` `` and other commands run first, and their output gets inserted into the prompt:

383 

384```yaml theme={null}

385---

386name: pr-summary

387description: Summarize changes in a pull request

388context: fork

389agent: Explore

390allowed-tools: Bash(gh *)

391---

392 

393## Pull request context

394- PR diff: !`gh pr diff`

395- PR comments: !`gh pr view --comments`

396- Changed files: !`gh pr diff --name-only`

397 

398## Your task

399Summarize this pull request...

400```

401 

402When this skill runs:

403 

4041. Each `` !`<command>` `` executes immediately (before Claude sees anything)

4052. The output replaces the placeholder in the skill content

4063. Claude receives the fully-rendered prompt with actual PR data

407 

408This is preprocessing, not something Claude executes. Claude only sees the final result.

409 

410Substitution runs once over the original file. Command output is inserted as plain text and is not re-scanned for further `` !`<command>` `` placeholders, so a command cannot emit a placeholder for a later pass to expand.

411 

412For multi-line commands, use a fenced code block opened with ` ```! ` instead of the inline form:

413 

414````markdown theme={null}

415## Environment

416```!

417node --version

418npm --version

419git status --short

420```

421````

422 

423To disable this behavior for skills and custom commands from user, project, plugin, or [additional-directory](#skills-from-additional-directories) sources, set `"disableSkillShellExecution": true` in [settings](/en/settings). Each command is replaced with `[shell command execution disabled by policy]` instead of being run. Bundled and managed skills are not affected. This setting is most useful in [managed settings](/en/permissions#managed-settings), where users cannot override it.

424 

425<Tip>

426 To request deeper reasoning when a skill runs, include `ultrathink` anywhere in the skill content. See [Use ultrathink for one-off deep reasoning](/en/model-config#use-ultrathink-for-one-off-deep-reasoning).

427</Tip>

428 

429### Run skills in a subagent

430 

431Add `context: fork` to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history.

432 

433<Warning>

434 `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines like "use these API conventions" without a task, the subagent receives the guidelines but no actionable prompt, and returns without meaningful output.

435</Warning>

436 

437Skills and [subagents](/en/sub-agents) work together in two directions:

438 

439| Approach | System prompt | Task | Also loads |

440| :--------------------------- | :----------------------- | :-------------------------- | :-------------------------------------------------- |

441| Skill with `context: fork` | From agent type | SKILL.md content | CLAUDE.md, except when the agent is Explore or Plan |

442| Subagent with `skills` field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md |

443 

444With `context: fork`, you write the task in your skill and pick an agent type to execute it. The built-in Explore and Plan agents [skip CLAUDE.md and git status](/en/sub-agents#what-loads-at-startup) to keep their context small, so a forked skill using `agent: Explore` sees only the SKILL.md content and the agent's own system prompt. For the inverse, where you define a custom subagent that uses skills as reference material, see [Subagents](/en/sub-agents#preload-skills-into-subagents).

445 

446#### Example: Research skill using Explore agent

447 

448This skill runs research in a forked Explore agent. The skill content becomes the task, and the agent provides read-only tools optimized for codebase exploration:

449 

450```yaml theme={null}

451---

452name: deep-research

453description: Research a topic thoroughly

454context: fork

455agent: Explore

456---

457 

458Research $ARGUMENTS thoroughly:

459 

4601. Find relevant files using Glob and Grep

4612. Read and analyze the code

4623. Summarize findings with specific file references

463```

464 

465When this skill runs:

466 

4671. A new isolated context is created

4682. The subagent receives the skill content as its prompt ("Research \$ARGUMENTS thoroughly...")

4693. The `agent` field determines the execution environment (model, tools, and permissions)

4704. Results are summarized and returned to your main conversation

471 

472The `agent` field specifies which subagent configuration to use. Options include built-in agents (`Explore`, `Plan`, `general-purpose`) or any custom subagent from `.claude/agents/`. If omitted, uses `general-purpose`.

473 

474### Restrict Claude's skill access

475 

476By default, Claude can invoke any skill that doesn't have `disable-model-invocation: true` set. Skills that define `allowed-tools` grant Claude access to those tools without per-use approval when the skill is active. Your [permission settings](/en/permissions) still govern baseline approval behavior for all other tools. A few built-in commands are also available through the Skill tool, including `/init`, `/review`, and `/security-review`. Other built-in commands such as `/compact` are not.

477 

478Three ways to control which skills Claude can invoke:

479 

480**Disable all skills** by denying the Skill tool in `/permissions`:

481 

482```text theme={null}

483# Add to deny rules:

484Skill

485```

486 

487**Allow or deny specific skills** using [permission rules](/en/permissions):

488 

489```text theme={null}

490# Allow only specific skills

491Skill(commit)

492Skill(review-pr *)

493 

494# Deny specific skills

495Skill(deploy *)

496```

497 

498Permission syntax: `Skill(name)` for exact match, `Skill(name *)` for prefix match with any arguments.

499 

500**Hide individual skills** by adding `disable-model-invocation: true` to their frontmatter. This removes the skill from Claude's context entirely.

501 

502<Note>

503 The `user-invocable` field only controls menu visibility, not Skill tool access. Use `disable-model-invocation: true` to block programmatic invocation.

504</Note>

505 

506### Override skill visibility from settings

507 

508The `skillOverrides` setting controls skill visibility from your [settings](/en/settings) instead of the skill's own frontmatter. Use it for skills whose SKILL.md you don't want to edit, such as ones checked into a shared project repo or provided by an MCP server. The `/skills` menu writes it for you: highlight a skill and press `Space` to cycle states, then `Enter` to save to `.claude/settings.local.json`.

509 

510Each key is a skill name and each value is one of four states:

511 

512| Value | Listed to Claude | In `/` menu |

513| :---------------------- | :------------------- | :---------- |

514| `"on"` | Name and description | Yes |

515| `"name-only"` | Name only | Yes |

516| `"user-invocable-only"` | Hidden | Yes |

517| `"off"` | Hidden | Hidden |

518 

519A skill that is absent from `skillOverrides` is treated as `"on"`. The example below collapses one skill to its name and turns another off entirely:

520 

521```json theme={null}

522{

523 "skillOverrides": {

524 "legacy-context": "name-only",

525 "deploy": "off"

526 }

527}

528```

529 

530Plugin skills are not affected by `skillOverrides`. Manage those through `/plugin` instead.

531 

532## Share skills

533 

534Skills can be distributed at different scopes depending on your audience:

535 

536* **Project skills**: Commit `.claude/skills/` to version control

537* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)

538* **Managed**: Deploy organization-wide through [managed settings](/en/settings#settings-files)

539 

540### Generate visual output

541 

542Skills can bundle and run scripts in any language, giving Claude capabilities beyond what's possible in a single prompt. One powerful pattern is generating visual output: interactive HTML files that open in your browser for exploring data, debugging, or creating reports.

543 

544This example creates a codebase explorer: an interactive tree view where you can expand and collapse directories, see file sizes at a glance, and identify file types by color.

545 

546Create the Skill directory:

547 

548```bash theme={null}

549mkdir -p ~/.claude/skills/codebase-visualizer/scripts

550```

551 

552Save this to `~/.claude/skills/codebase-visualizer/SKILL.md`. The description tells Claude when to activate this Skill, and the instructions tell Claude to run the bundled script. The script path uses [`${CLAUDE_SKILL_DIR}`](#available-string-substitutions) so it resolves correctly whether the skill is installed at the personal, project, or plugin level:

553 

554````yaml theme={null}

555---

556name: codebase-visualizer

557description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.

558allowed-tools: Bash(python3 *)

559---

560 

561# Codebase Visualizer

562 

563Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.

564 

565## Usage

566 

567Run the visualization script from your project root:

568 

569```bash

570python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .

571```

572 

573This creates `codebase-map.html` in the current directory and opens it in your default browser.

574 

575## What the visualization shows

576 

577- **Collapsible directories**: Click folders to expand/collapse

578- **File sizes**: Displayed next to each file

579- **Colors**: Different colors for different file types

580- **Directory totals**: Shows aggregate size of each folder

581````

582 

583Save this to `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with:

584 

585* A **summary sidebar** showing file count, directory count, total size, and number of file types

586* A **bar chart** breaking down the codebase by file type (top 8 by size)

587* A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators

588 

589The script requires Python 3 but uses only built-in libraries, so there are no packages to install:

590 

591```python expandable theme={null}

592#!/usr/bin/env python3

593"""Generate an interactive collapsible tree visualization of a codebase."""

594 

595import json

596import sys

597import webbrowser

598from html import escape

599from pathlib import Path

600from collections import Counter

601 

602IGNORE = {'.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'}

603 

604def scan(path: Path, stats: dict) -> dict:

605 result = {"name": path.name, "children": [], "size": 0}

606 try:

607 for item in sorted(path.iterdir()):

608 if item.name in IGNORE or item.name.startswith('.'):

609 continue

610 if item.is_file():

611 size = item.stat().st_size

612 ext = item.suffix.lower() or '(no ext)'

613 result["children"].append({"name": item.name, "size": size, "ext": ext})

614 result["size"] += size

615 stats["files"] += 1

616 stats["extensions"][ext] += 1

617 stats["ext_sizes"][ext] += size

618 elif item.is_dir():

619 stats["dirs"] += 1

620 child = scan(item, stats)

621 if child["children"]:

622 result["children"].append(child)

623 result["size"] += child["size"]

624 except PermissionError:

625 pass

626 return result

627 

628def generate_html(data: dict, stats: dict, output: Path) -> None:

629 ext_sizes = stats["ext_sizes"]

630 total_size = sum(ext_sizes.values()) or 1

631 sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]

632 colors = {

633 '.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',

634 '.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',

635 '.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',

636 '.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',

637 }

638 lang_bars = "".join(

639 f'<div class="bar-row"><span class="bar-label">{ext}</span>'

640 f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'

641 f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'

642 for ext, size in sorted_exts

643 )

644 def fmt(b):

645 if b < 1024: return f"{b} B"

646 if b < 1048576: return f"{b/1024:.1f} KB"

647 return f"{b/1048576:.1f} MB"

648 

649 html = f'''<!DOCTYPE html>

650<html><head>

651 <meta charset="utf-8"><title>Codebase Explorer</title>

652 <style>

653 body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}

654 .container {{ display: flex; height: 100vh; }}

655 .sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}

656 .main {{ flex: 1; padding: 20px; overflow-y: auto; }}

657 h1 {{ margin: 0 0 10px 0; font-size: 18px; }}

658 h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}

659 .stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}

660 .stat-value {{ font-weight: bold; }}

661 .bar-row {{ display: flex; align-items: center; margin: 6px 0; }}

662 .bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}

663 .bar {{ height: 18px; border-radius: 3px; }}

664 .bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}

665 .tree {{ list-style: none; padding-left: 20px; }}

666 details {{ cursor: pointer; }}

667 summary {{ padding: 4px 8px; border-radius: 4px; }}

668 summary:hover {{ background: #2d2d44; }}

669 .folder {{ color: #ffd700; }}

670 .file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}

671 .file:hover {{ background: #2d2d44; }}

672 .size {{ color: #888; margin-left: auto; font-size: 12px; }}

673 .dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}

674 </style>

675</head><body>

676 <div class="container">

677 <div class="sidebar">

678 <h1>📊 Summary</h1>

679 <div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>

680 <div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>

681 <div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>

682 <div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>

683 <h2>By file type</h2>

684 {lang_bars}

685 </div>

686 <div class="main">

687 <h1>📁 {escape(data["name"])}</h1>

688 <ul class="tree" id="root"></ul>

689 </div>

690 </div>

691 <script>

692 const data = {json.dumps(data)};

693 const colors = {json.dumps(colors)};

694 function fmt(b) {{ if (b < 1024) return b + ' B'; if (b < 1048576) return (b/1024).toFixed(1) + ' KB'; return (b/1048576).toFixed(1) + ' MB'; }}

695 function esc(s) {{ return s.replace(/[&<>"']/g, c => ({{"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}}[c])); }}

696 function render(node, parent) {{

697 if (node.children) {{

698 const det = document.createElement('details');

699 det.open = parent === document.getElementById('root');

700 det.innerHTML = `<summary><span class="folder">📁 ${{esc(node.name)}}</span><span class="size">${{fmt(node.size)}}</span></summary>`;

701 const ul = document.createElement('ul'); ul.className = 'tree';

702 node.children.sort((a,b) => (b.children?1:0)-(a.children?1:0) || a.name.localeCompare(b.name));

703 node.children.forEach(c => render(c, ul));

704 det.appendChild(ul);

705 const li = document.createElement('li'); li.appendChild(det); parent.appendChild(li);

706 }} else {{

707 const li = document.createElement('li'); li.className = 'file';

708 li.innerHTML = `<span class="dot" style="background:${{colors[node.ext]||'#6b7280'}}"></span>${{esc(node.name)}}<span class="size">${{fmt(node.size)}}</span>`;

709 parent.appendChild(li);

710 }}

711 }}

712 data.children.forEach(c => render(c, document.getElementById('root')));

713 </script>

714</body></html>'''

715 output.write_text(html)

716 

717if __name__ == '__main__':

718 target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()

719 stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}

720 data = scan(target, stats)

721 out = Path('codebase-map.html')

722 generate_html(data, stats, out)

723 print(f'Generated {out.absolute()}')

724 webbrowser.open(f'file://{out.absolute()}')

725```

726 

727To test, open Claude Code in any project and ask "Visualize this codebase." Claude runs the script, generates `codebase-map.html`, and opens it in your browser.

728 

729This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the work while Claude handles orchestration.

730 

731## Troubleshooting

732 

733### Skill not triggering

734 

735If Claude doesn't use your skill when expected:

736 

7371. Check the description includes keywords users would naturally say

7382. Verify the skill appears in `What skills are available?`

7393. Try rephrasing your request to match the description more closely

7404. Invoke it directly with `/skill-name` if the skill is user-invocable

741 

742### Skill triggers too often

743 

744If Claude uses your skill when you don't want it:

745 

7461. Make the description more specific

7472. Add `disable-model-invocation: true` if you only want manual invocation

748 

749### Skill descriptions are cut short

750 

751Skill descriptions are loaded into context so Claude knows what's available. All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget, which can strip the keywords Claude needs to match your request. The budget scales at 1% of the model's context window. When it overflows, descriptions for the skills you invoke least are dropped first, so the skills you actually use keep their full text. Run `/doctor` to see whether the budget is overflowing and which skills are affected.

752 

753To raise the budget, set the [`skillListingBudgetFraction`](/en/settings#available-settings) setting (e.g. `0.02` = 2%) or the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable to a fixed character count. To free budget for other skills, set low-priority entries to `"name-only"` in [`skillOverrides`](#override-skill-visibility-from-settings) so they list without a description. You can also trim the `description` and `when_to_use` text at the source: put the key use case first, since each entry's combined text is capped at 1,536 characters regardless of budget. The cap is configurable with [`maxSkillDescriptionChars`](/en/settings#available-settings).

754 

755## Related resources

756 

757* **[Debug your configuration](/en/debug-your-config)**: diagnose why a skill isn't appearing or triggering

758* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents

759* **[Plugins](/en/plugins)**: package and distribute skills with other extensions

760* **[Hooks](/en/hooks)**: automate workflows around tool events

761* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context

762* **[Commands](/en/commands)**: reference for built-in commands and bundled skills

763* **[Permissions](/en/permissions)**: control tool and skill access

142}142}

143```143```

144 144 

145Setting `"space": null` removes the default binding. Omit it if you want both keys active.145The `voice:pushToTalk` action uses one key at a time. When you bind a custom key, it replaces the default `Space` binding rather than adding a second trigger, so the `"space": null` line in this example is for clarity and can be omitted without changing behavior.

146 146 

147In hold mode, avoid binding a bare letter key like `v` since hold detection relies on key-repeat and the letter types into the prompt during warmup. Use `Space`, or use a modifier combination like `meta+k` to start recording on the first keypress with no warmup. Tap mode has no warmup, so most keys work.147In hold mode, avoid binding a bare letter key like `v` since hold detection relies on key-repeat and the letter types into the prompt during warmup. Use `Space`, or use a modifier combination like `meta+k` to start recording on the first keypress with no warmup. Tap mode has no warmup, so most keys work.

148 148