← Back to daily report

slash-commands.md

Changed on 2026-05-02 14:52:05 EST

+44 lines added
-43 lines removed
Visual Diff
> ## Documentation Index¶
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt¶
> Use this file to discover all available pages before exploring further.¶

# Extend Claude with skills¶

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

Skills 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`.¶

Create a skill when you keep pasting the same playbookinstructions, 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.¶

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

**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.¶
</Note>¶

Claude 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).¶

## Bundled skills¶

Claude 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 a detailed playbookinstructions 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.¶

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

## Getting started¶

### Create your first skill¶

This example creates a skill that teaches Claude to explain code ussummarizes the uncommitted changes in your git repository and flags anything vrisual diagrams and analogies. Since it uses default frontmky. It pulls the live diff into the prompt before Claude reads it, so the response is grounded in your actual working tree ratther, than what Claude can load itguess from open files. Claude loads the skill automatically when you ask how something workabout your changes, or you can invoke it directly with `/explain-codesummarize-changes`.¶

<Steps>¶
<Step title="Create the skill directory">¶
Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.¶

```bash theme={null}¶
mkdir -p ~/.claude/skills/explain-codesummarize-changes
```¶
</Step>¶

<Step title="Write SKILL.md">¶
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 is invokedruns. The directory name becomes the `/slash-command`command you type, and the `description` helps Claude decide when to load ithe skill automatically.¶

CreateSave this to `~/.claude/skills/explain-codesummarize-changes/SKILL.md`:¶

```yaml theme={null}¶
---¶
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaSummarizes uncommitted changes and flags anything risky. Use when the user asks what chiang about a codebase, or when the user asks "how does this work?"¶
---¶

When explaining code, always include:¶

1. **Start with an analogy**: Compare the code to something from everyday life¶
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships¶
3. **Walk through the code**: Explain step-by-step what happens¶
4. **Highlight a gotcha**: What's a common mistake or misconception?¶

Keep explanations conversational. For complex concepts, use multiple analogies.¶
```¶
</Step>¶

<Step title="Test the skill">¶
ed, wants a commit message, or asks to review their diff.¶
---¶

## Current changes¶

!`git diff HEAD`¶

## Instructions¶

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.¶
```¶

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.¶
</Step>¶

<Step title="Test the skill">¶
Open a git project, make a small edit to any file, and start Claude Code by running `claude`. You can test ithe skill two ways:.

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

```text theme={null}¶
How does this code workWhat did I change?¶
```¶

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

```text theme={null}¶
/explain-code src/auth/login.tsummarize-changes¶
```¶

Either way, Claude should include an analogy and ASCII diagram in its explanationrespond with a short summary of your edit and a list of risks.¶
</Step>¶
</Steps>¶

### Where skills live¶

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

| Location | Path | Applies to |¶
| :--------- | :-------------------------------------------------- | :----------------------------- |¶
| Enterprise | See [managed settings](/en/settings#settings-files) | All users in your organization |¶
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects |¶
| Project | `.claude/skills/<skill-name>/SKILL.md` | This project only |¶
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where plugin is enabled |¶

When 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.¶

#### Live change detection¶

Claude 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.¶

#### Automatic discovery from nested directories¶

When you work with files in subdirectories, Claude Code automatically discovers skills from nested `.claude/skills/` directories. 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.¶

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

```text theme={null}¶
my-skill/¶
├── SKILL.md # Main instructions (required)¶
├── template.md # Template for Claude to fill in¶
├── examples/¶
│ └── sample.md # Example output showing expected format¶
└── scripts/¶
└── validate.sh # Script Claude can execute¶
```¶

The `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.¶

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

#### Skills from additional directories¶

The `--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.¶

Other `.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.¶

<Note>¶
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).¶
</Note>¶

## Configure skills¶

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

### Types of skill content¶

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

**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.¶

```yaml theme={null}¶
---¶
name: api-conventions¶
description: API design patterns for this codebase¶
---¶

When writing API endpoints:¶
- Use RESTful naming conventions¶
- Return consistent error formats¶
- Include request validation¶
```¶

**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.¶

```yaml theme={null}¶
---¶
name: deploy¶
description: Deploy the application to production¶
context: fork¶
disable-model-invocation: true¶
---¶

Deploy the application:¶
1. Run the test suite¶
2. Build the application¶
3. Push to the deployment target¶
```¶

Your `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.¶

### Frontmatter reference¶

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

```yaml theme={null}¶
---¶
name: my-skill¶
description: What this skill does¶
disable-model-invocation: true¶
allowed-tools: Read Grep¶
---¶

Your skill instructions here...¶
```¶

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

| Field | Required | Description |¶
| :------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |¶
| `name` | No | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters). |¶
| `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. Front-loadPut 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. |¶
| `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. |¶
| `argument-hint` | No | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`. |¶
| `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. |¶
| `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`. |¶
| `user-invocable` | No | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`. |¶
| `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list. |¶
| `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. |¶
| `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. |¶
| `context` | No | Set to `fork` to run in a forked subagent context. |¶
| `agent` | No | Which subagent type to use when `context: fork` is set. |¶
| `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. |¶
| `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). |¶
| `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`. |¶

#### Available string substitutions¶

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

| Variable | Description |¶
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |¶
| `$ARGUMENTS` | All arguments passed when invoking the skill. If `$ARGUMENTS` is not present in the content, arguments are appended as `ARGUMENTS: <value>`. |¶
| `$ARGUMENTS[N]` | Access a specific argument by 0-based index, such as `$ARGUMENTS[0]` for the first argument. |¶
| `$N` | Shorthand for `$ARGUMENTS[N]`, such as `$0` for the first argument or `$1` for the second. |¶
| `$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. |¶
| `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging, creating session-specific files, or correlating skill output with sessions. |¶
| `${CLAUDE_EFFORT}` | The current effort level: `low`, `medium`, `high`, `xhigh`, or `max`. Use this to adapt skill instructions to the active effort setting. |¶
| `${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. |¶

Indexed 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.¶

**Example using substitutions:**¶

```yaml theme={null}¶
---¶
name: session-logger¶
description: Log activity for this session¶
---¶

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

$ARGUMENTS¶
```¶

### Add supporting files¶

Skills 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.¶

```text theme={null}¶
my-skill/¶
├── SKILL.md (required - overview and navigation)¶
├── reference.md (detailed API docs - loaded when needed)¶
├── examples.md (usage examples - loaded when needed)¶
└── scripts/¶
└── helper.py (utility script - executed, not loaded)¶
```¶

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

```markdown theme={null}¶
## Additional resources¶

- For complete API details, see [reference.md](reference.md)¶
- For usage examples, see [examples.md](examples.md)¶
```¶

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

### Control who invokes a skill¶

By 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:¶

* **`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.¶

* **`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.¶

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

```yaml theme={null}¶
---¶
name: deploy¶
description: Deploy the application to production¶
disable-model-invocation: true¶
---¶

Deploy $ARGUMENTS to production:¶

1. Run the test suite¶
2. Build the application¶
3. Push to the deployment target¶
4. Verify the deployment succeeded¶
```¶

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

| Frontmatter | You can invoke | Claude can invoke | When loaded into context |¶
| :------------------------------- | :------------- | :---------------- | :----------------------------------------------------------- |¶
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |¶
| `disable-model-invocation: true` | Yes | No | Description not in context, full skill loads when you invoke |¶
| `user-invocable: false` | No | Yes | Description always in context, full skill loads when invoked |¶

<Note>¶
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.¶
</Note>¶

### Skill content lifecycle¶

When 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.¶

[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.¶

If 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.¶

### Pre-approve tools for a skill¶

The `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.¶

For 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.¶

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

```yaml theme={null}¶
---¶
name: commit¶
description: Stage and commit the current changes¶
disable-model-invocation: true¶
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)¶
---¶
```¶

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

### Pass arguments to skills¶

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

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

```yaml theme={null}¶
---¶
name: fix-issue¶
description: Fix a GitHub issue¶
disable-model-invocation: true¶
---¶

Fix GitHub issue $ARGUMENTS following our coding standards.¶

1. Read the issue description¶
2. Understand the requirements¶
3. Implement the fix¶
4. Write tests¶
5. Create a commit¶
```¶

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

If 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.¶

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

```yaml theme={null}¶
---¶
name: migrate-component¶
description: Migrate a component from one framework to another¶
---¶

Migrate the $ARGUMENTS[0] component from $ARGUMENTS[1] to $ARGUMENTS[2].¶
Preserve all existing behavior and tests.¶
```¶

Running `/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:¶

```yaml theme={null}¶
---¶
name: migrate-component¶
description: Migrate a component from one framework to another¶
---¶

Migrate the $0 component from $1 to $2.¶
Preserve all existing behavior and tests.¶
```¶

## Advanced patterns¶

### Inject dynamic context¶

The `` !`<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.¶

This 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:¶

```yaml theme={null}¶
---¶
name: pr-summary¶
description: Summarize changes in a pull request¶
context: fork¶
agent: Explore¶
allowed-tools: Bash(gh *)¶
---¶

## Pull request context¶
- PR diff: !`gh pr diff`¶
- PR comments: !`gh pr view --comments`¶
- Changed files: !`gh pr diff --name-only`¶

## Your task¶
Summarize this pull request...¶
```¶

When this skill runs:¶

1. Each `` !`<command>` `` executes immediately (before Claude sees anything)¶
2. The output replaces the placeholder in the skill content¶
3. Claude receives the fully-rendered prompt with actual PR data¶

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

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

````markdown theme={null}¶
## Environment¶
```!¶
node --version¶
npm --version¶
git status --short¶
```¶
````¶

To 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.¶

<Tip>¶
To enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) irequest deeper reasoning when a skill runs, include the word "`ultrathink"` anywhere in yourthe skill content. See [Use ultrathink for one-off deep reasoning](/en/model-config#use-ultrathink-for-one-off-deep-reasoning).
</Tip>¶

### Run skills in a subagent¶

Add `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.¶

<Warning>¶
`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.¶
</Warning>¶

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

| Approach | System prompt | Task | Also loads |¶
| :--------------------------- | :---------------------------------------- | :-------------------------- | :--------------------------- |¶
| Skill with `context: fork` | From agent type (`Explore`, `Plan`, etc.) | SKILL.md content | CLAUDE.md |¶
| Subagent with `skills` field | Subagent's markdown body | Claude's delegation message | Preloaded skills + CLAUDE.md |¶

With `context: fork`, you write the task in your skill and pick an agent type to execute it. For the inverse (defining a custom subagent that uses skills as reference material), see [Subagents](/en/sub-agents#preload-skills-into-subagents).¶

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

This 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:¶

```yaml theme={null}¶
---¶
name: deep-research¶
description: Research a topic thoroughly¶
context: fork¶
agent: Explore¶
---¶

Research $ARGUMENTS thoroughly:¶

1. Find relevant files using Glob and Grep¶
2. Read and analyze the code¶
3. Summarize findings with specific file references¶
```¶

When this skill runs:¶

1. A new isolated context is created¶
2. The subagent receives the skill content as its prompt ("Research \$ARGUMENTS thoroughly...")¶
3. The `agent` field determines the execution environment (model, tools, and permissions)¶
4. Results are summarized and returned to your main conversation¶

The `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`.¶

### Restrict Claude's skill access¶

By 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.¶

Three ways to control which skills Claude can invoke:¶

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

```text theme={null}¶
# Add to deny rules:¶
Skill¶
```¶

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

```text theme={null}¶
# Allow only specific skills¶
Skill(commit)¶
Skill(review-pr *)¶

# Deny specific skills¶
Skill(deploy *)¶
```¶

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

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

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

## Share skills¶

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

* **Project skills**: Commit `.claude/skills/` to version control¶
* **Plugins**: Create a `skills/` directory in your [plugin](/en/plugins)¶
* **Managed**: Deploy organization-wide through [managed settings](/en/settings#settings-files)¶

### Generate visual output¶

Skills 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.¶

This 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.¶

Create the Skill directory:¶

```bash theme={null}¶
mkdir -p ~/.claude/skills/codebase-visualizer/scripts¶
```¶

CreateSave 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:¶

````yaml theme={null}¶
---¶
name: codebase-visualizer¶
description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.¶
allowed-tools: Bash(python3 *)¶
---¶

# Codebase Visualizer¶

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

## Usage¶

Run the visualization script from your project root:¶

```bash¶
python ~/.claude/skills/codebase-visualizer3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .¶
```¶

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

## What the visualization shows¶

- **Collapsible directories**: Click folders to expand/collapse¶
- **File sizes**: Displayed next to each file¶
- **Colors**: Different colors for different file types¶
- **Directory totals**: Shows aggregate size of each folder¶
````¶

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

* A **summary sidebar** showing file count, directory count, total size, and number of file types¶
* A **bar chart** breaking down the codebase by file type (top 8 by size)¶
* A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators¶

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

```python expandable theme={null}¶
#!/usr/bin/env python3¶
"""Generate an interactive collapsible tree visualization of a codebase."""¶

import json¶
import sys¶
import webbrowser¶
from html import escape¶
from pathlib import Path¶
from collections import Counter¶

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

def scan(path: Path, stats: dict) -> dict:¶
result = {"name": path.name, "children": [], "size": 0}¶
try:¶
for item in sorted(path.iterdir()):¶
if item.name in IGNORE or item.name.startswith('.'):¶
continue¶
if item.is_file():¶
size = item.stat().st_size¶
ext = item.suffix.lower() or '(no ext)'¶
result["children"].append({"name": item.name, "size": size, "ext": ext})¶
result["size"] += size¶
stats["files"] += 1¶
stats["extensions"][ext] += 1¶
stats["ext_sizes"][ext] += size¶
elif item.is_dir():¶
stats["dirs"] += 1¶
child = scan(item, stats)¶
if child["children"]:¶
result["children"].append(child)¶
result["size"] += child["size"]¶
except PermissionError:¶
pass¶
return result¶

def generate_html(data: dict, stats: dict, output: Path) -> None:¶
ext_sizes = stats["ext_sizes"]¶
total_size = sum(ext_sizes.values()) or 1¶
sorted_exts = sorted(ext_sizes.items(), key=lambda x: -x[1])[:8]¶
colors = {¶
'.js': '#f7df1e', '.ts': '#3178c6', '.py': '#3776ab', '.go': '#00add8',¶
'.rs': '#dea584', '.rb': '#cc342d', '.css': '#264de4', '.html': '#e34c26',¶
'.json': '#6b7280', '.md': '#083fa1', '.yaml': '#cb171e', '.yml': '#cb171e',¶
'.mdx': '#083fa1', '.tsx': '#3178c6', '.jsx': '#61dafb', '.sh': '#4eaa25',¶
}¶
lang_bars = "".join(¶
f'<div class="bar-row"><span class="bar-label">{ext}</span>'¶
f'<div class="bar" style="width:{(size/total_size)*100}%;background:{colors.get(ext,"#6b7280")}"></div>'¶
f'<span class="bar-pct">{(size/total_size)*100:.1f}%</span></div>'¶
for ext, size in sorted_exts¶
)¶
def fmt(b):¶
if b < 1024: return f"{b} B"¶
if b < 1048576: return f"{b/1024:.1f} KB"¶
return f"{b/1048576:.1f} MB"¶

html = f'''<!DOCTYPE html>¶
<html><head>¶
<meta charset="utf-8"><title>Codebase Explorer</title>¶
<style>¶
body {{ font: 14px/1.5 system-ui, sans-serif; margin: 0; background: #1a1a2e; color: #eee; }}¶
.container {{ display: flex; height: 100vh; }}¶
.sidebar {{ width: 280px; background: #252542; padding: 20px; border-right: 1px solid #3d3d5c; overflow-y: auto; flex-shrink: 0; }}¶
.main {{ flex: 1; padding: 20px; overflow-y: auto; }}¶
h1 {{ margin: 0 0 10px 0; font-size: 18px; }}¶
h2 {{ margin: 20px 0 10px 0; font-size: 14px; color: #888; text-transform: uppercase; }}¶
.stat {{ display: flex; justify-content: space-between; padding: 8px 0; border-bottom: 1px solid #3d3d5c; }}¶
.stat-value {{ font-weight: bold; }}¶
.bar-row {{ display: flex; align-items: center; margin: 6px 0; }}¶
.bar-label {{ width: 55px; font-size: 12px; color: #aaa; }}¶
.bar {{ height: 18px; border-radius: 3px; }}¶
.bar-pct {{ margin-left: 8px; font-size: 12px; color: #666; }}¶
.tree {{ list-style: none; padding-left: 20px; }}¶
details {{ cursor: pointer; }}¶
summary {{ padding: 4px 8px; border-radius: 4px; }}¶
summary:hover {{ background: #2d2d44; }}¶
.folder {{ color: #ffd700; }}¶
.file {{ display: flex; align-items: center; padding: 4px 8px; border-radius: 4px; }}¶
.file:hover {{ background: #2d2d44; }}¶
.size {{ color: #888; margin-left: auto; font-size: 12px; }}¶
.dot {{ width: 8px; height: 8px; border-radius: 50%; margin-right: 8px; }}¶
</style>¶
</head><body>¶
<div class="container">¶
<div class="sidebar">¶
<h1>📊 Summary</h1>¶
<div class="stat"><span>Files</span><span class="stat-value">{stats["files"]:,}</span></div>¶
<div class="stat"><span>Directories</span><span class="stat-value">{stats["dirs"]:,}</span></div>¶
<div class="stat"><span>Total size</span><span class="stat-value">{fmt(data["size"])}</span></div>¶
<div class="stat"><span>File types</span><span class="stat-value">{len(stats["extensions"])}</span></div>¶
<h2>By file type</h2>¶
{lang_bars}¶
</div>¶
<div class="main">¶
<h1>📁 {escape(data["name"])}</h1>¶
<ul class="tree" id="root"></ul>¶
</div>¶
</div>¶

</body></html>'''¶
output.write_text(html)¶

if __name__ == '__main__':¶
target = Path(sys.argv[1] if len(sys.argv) > 1 else '.').resolve()¶
stats = {"files": 0, "dirs": 0, "extensions": Counter(), "ext_sizes": Counter()}¶
data = scan(target, stats)¶
out = Path('codebase-map.html')¶
generate_html(data, stats, out)¶
print(f'Generated {out.absolute()}')¶
webbrowser.open(f'file://{out.absolute()}')¶
```¶

To 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.¶

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

## Troubleshooting¶

### Skill not triggering¶

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

1. Check the description includes keywords users would naturally say¶
2. Verify the skill appears in `What skills are available?`¶
3. Try rephrasing your request to match the description more closely¶
4. Invoke it directly with `/skill-name` if the skill is user-invocable¶

### Skill triggers too often¶

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

1. Make the description more specific¶
2. Add `disable-model-invocation: true` if you only want manual invocation¶

### Skill descriptions are cut short¶

Skill 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 dynamically at 1% of the context window, with a fallback of 8,000 characters.¶

To raise the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. Or trim the `description` and `when_to_use` text at the source: front-loadput the key use case first, since each entry's combined text is capped at 1,536 characters regardless of budget.¶

## Related resources¶

* **[Debug your configuration](/en/debug-your-config)**: diagnose why a skill isn't appearing or triggering¶
* **[Subagents](/en/sub-agents)**: delegate tasks to specialized agents¶
* **[Plugins](/en/plugins)**: package and distribute skills with other extensions¶
* **[Hooks](/en/hooks)**: automate workflows around tool events¶
* **[Memory](/en/memory)**: manage CLAUDE.md files for persistent context¶
* **[Commands](/en/commands)**: reference for built-in commands and bundled skills¶
* **[Permissions](/en/permissions)**: control tool and skill access¶

Unified Diff

--- a/slash-commands.md
+++ b/slash-commands.md
@@ -8,7 +8,7 @@
 
 Skills 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`.
 
-Create a skill when you keep pasting the same playbook, 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.
+Create 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.
 
 <Note>
   For built-in commands like `/help` and `/compact`, and bundled skills like `/debug` and `/simplify`, see the [commands reference](/en/commands).
@@ -20,7 +20,7 @@
 
 ## Bundled skills
 
-Claude 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 a detailed playbook 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.
+Claude 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.
 
 Bundled skills are listed alongside built-in commands in the [commands reference](/en/commands), marked **Skill** in the Purpose column.
 
@@ -28,54 +28,55 @@
 
 ### Create your first skill
 
-This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. Since it uses default frontmatter, Claude can load it automatically when you ask how something works, or you can invoke it directly with `/explain-code`.
+This 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`.
 
 <Steps>
   <Step title="Create the skill directory">
     Create a directory for the skill in your personal skills folder. Personal skills are available across all your projects.
 
     ```bash theme={null}
-    mkdir -p ~/.claude/skills/explain-code
+    mkdir -p ~/.claude/skills/summarize-changes
     ```
   </Step>
 
   <Step title="Write SKILL.md">
-    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 instructions Claude follows when the skill is invoked. The directory name becomes the `/slash-command`, and the `description` helps Claude decide when to load it automatically.
-
-    Create `~/.claude/skills/explain-code/SKILL.md`:
+    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.
+
+    Save this to `~/.claude/skills/summarize-changes/SKILL.md`:
 
     ```yaml theme={null}
     ---
-    description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
+    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.
     ---
 
-    When explaining code, always include:
-
-    1. **Start with an analogy**: Compare the code to something from everyday life
-    2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
-    3. **Walk through the code**: Explain step-by-step what happens
-    4. **Highlight a gotcha**: What's a common mistake or misconception?
-
-    Keep explanations conversational. For complex concepts, use multiple analogies.
+    ## Current changes
+
+    !`git diff HEAD`
+
+    ## Instructions
+
+    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.
     ```
+
+    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.
   </Step>
 
   <Step title="Test the skill">
-    You can test it two ways:
+    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.
 
     **Let Claude invoke it automatically** by asking something that matches the description:
 
     ```text theme={null}
-    How does this code work?
+    What did I change?
     ```
 
     **Or invoke it directly** with the skill name:
 
     ```text theme={null}
-    /explain-code src/auth/login.ts
+    /summarize-changes
     ```
 
-    Either way, Claude should include an analogy and ASCII diagram in its explanation.
+    Either way, Claude should respond with a short summary of your edit and a list of risks.
   </Step>
 </Steps>
 
@@ -185,23 +186,23 @@
 
 All fields are optional. Only `description` is recommended so Claude knows when to use the skill.
 
-| Field                      | Required    | Description                                                                                                                                                                                                                                                                                                         |
-| :------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `name`                     | No          | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters).                                                                                                                                                                                  |
-| `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. Front-load the key use case: the combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing to reduce context usage. |
-| `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.                                                                                                                  |
-| `argument-hint`            | No          | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`.                                                                                                                                                                                                  |
-| `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.                                                                                                             |
-| `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`.                                                  |
-| `user-invocable`           | No          | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`.                                                                                                                                                                                            |
-| `allowed-tools`            | No          | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list.                                                                                                                                                                                          |
-| `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.                                          |
-| `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.                                                                         |
-| `context`                  | No          | Set to `fork` to run in a forked subagent context.                                                                                                                                                                                                                                                                  |
-| `agent`                    | No          | Which subagent type to use when `context: fork` is set.                                                                                                                                                                                                                                                             |
-| `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.                                                                                                                                                                            |
-| `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).                           |
-| `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`.                                                                             |
+| Field                      | Required    | Description                                                                                                                                                                                                                                                                                                        |
+| :------------------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`                     | No          | Display name for the skill. If omitted, uses the directory name. Lowercase letters, numbers, and hyphens only (max 64 characters).                                                                                                                                                                                 |
+| `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. |
+| `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.                                                                                                                 |
+| `argument-hint`            | No          | Hint shown during autocomplete to indicate expected arguments. Example: `[issue-number]` or `[filename] [format]`.                                                                                                                                                                                                 |
+| `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.                                                                                                            |
+| `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`.                                                 |
+| `user-invocable`           | No          | Set to `false` to hide from the `/` menu. Use for background knowledge users shouldn't invoke directly. Default: `true`.                                                                                                                                                                                           |
+| `allowed-tools`            | No          | Tools Claude can use without asking permission when this skill is active. Accepts a space-separated string or a YAML list.                                                                                                                                                                                         |
+| `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.                                         |
+| `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.                                                                        |
+| `context`                  | No          | Set to `fork` to run in a forked subagent context.                                                                                                                                                                                                                                                                 |
+| `agent`                    | No          | Which subagent type to use when `context: fork` is set.                                                                                                                                                                                                                                                            |
+| `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.                                                                                                                                                                           |
+| `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).                          |
+| `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`.                                                                            |
 
 #### Available string substitutions
 
@@ -305,6 +306,8 @@
 
 The `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.
 
+For 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.
+
 This skill lets Claude run git commands without per-use approval whenever you invoke it:
 
 ```yaml theme={null}
@@ -416,7 +419,7 @@
 To 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.
 
 <Tip>
-  To enable [extended thinking](/en/common-workflows#use-extended-thinking-thinking-mode) in a skill, include the word "ultrathink" anywhere in your skill content.
+  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).
 </Tip>
 
 ### Run skills in a subagent
@@ -516,13 +519,13 @@
 mkdir -p ~/.claude/skills/codebase-visualizer/scripts
 ```
 
-Create `~/.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:
+Save 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:
 
 ````yaml theme={null}
 ---
 name: codebase-visualizer
 description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
-allowed-tools: Bash(python *)
+allowed-tools: Bash(python3 *)
 ---
 
 # Codebase Visualizer
@@ -534,7 +537,7 @@
 Run the visualization script from your project root:
 
 ```bash
-python ~/.claude/skills/codebase-visualizer/scripts/visualize.py .
+python3 ${CLAUDE_SKILL_DIR}/scripts/visualize.py .
 ```
 
 This creates `codebase-map.html` in the current directory and opens it in your default browser.
@@ -547,13 +550,13 @@
 - **Directory totals**: Shows aggregate size of each folder
 ````
 
-Create `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with:
+Save this to `~/.claude/skills/codebase-visualizer/scripts/visualize.py`. This script scans a directory tree and generates a self-contained HTML file with:
 
 * A **summary sidebar** showing file count, directory count, total size, and number of file types
 * A **bar chart** breaking down the codebase by file type (top 8 by size)
 * A **collapsible tree** where you can expand and collapse directories, with color-coded file type indicators
 
-The script requires Python but uses only built-in libraries, so there are no packages to install:
+The script requires Python 3 but uses only built-in libraries, so there are no packages to install:
 
 ```python expandable theme={null}
 #!/usr/bin/env python3
@@ -562,6 +565,7 @@
 import json
 import sys
 import webbrowser
+from html import escape
 from pathlib import Path
 from collections import Counter
 
@@ -650,7 +654,7 @@
       {lang_bars}
     </div>
     <div class="main">
-      <h1>📁 {data["name"]}</h1>
+      <h1>📁 {escape(data["name"])}</h1>
       <ul class="tree" id="root"></ul>
     </div>
   </div>
@@ -670,7 +674,7 @@
 
 To 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.
 
-This pattern works for any visual output: dependency graphs, test coverage reports, API documentation, or database schema visualizations. The bundled script does the heavy lifting while Claude handles orchestration.
+This 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.
 
 ## Troubleshooting
 
@@ -694,7 +698,7 @@
 
 Skill 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 dynamically at 1% of the context window, with a fallback of 8,000 characters.
 
-To raise the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. Or trim the `description` and `when_to_use` text at the source: front-load the key use case, since each entry's combined text is capped at 1,536 characters regardless of budget.
+To raise the limit, set the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable. Or 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.
 
 ## Related resources