# Claude Code Skills Documentation Official Claude Code documentation on skills. Retrieved 2026-03-19. ## Overview 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`. 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. Existing `.claude/commands/` files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and the ability for Claude to load them automatically when relevant. Claude Code skills follow the Agent Skills open standard (agentskills.io). ## Where Skills Live | Location | Path | Applies to | | :--------- | :-------------------------------------------------- | :----------------------------- | | Enterprise | See managed settings | 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, higher-priority locations win: enterprise > personal > project. ## Frontmatter Reference | Field | Required | Description | | :------------------------- | :---------- | :-------------------------------------------------------------- | | `name` | No | Display name. If omitted, uses directory name. Lowercase, numbers, hyphens only (max 64 chars) | | `description` | Recommended | What it does and when to use it. Claude uses this to decide when to apply the skill | | `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` | | `disable-model-invocation` | No | Set to `true` to prevent automatic loading. Default: `false` | | `user-invocable` | No | Set to `false` to hide from `/` menu. Default: `true` | | `allowed-tools` | No | Tools Claude can use without asking permission | | `model` | No | Model to use when skill is active | | `context` | No | Set to `fork` to run in a forked subagent context | | `agent` | No | Which subagent type to use with `context: fork` | | `hooks` | No | Hooks scoped to this skill's lifecycle | ## String Substitutions | Variable | Description | | :--------------------- | :------------------------------------------------- | | `$ARGUMENTS` | All arguments passed when invoking the skill | | `$ARGUMENTS[N]` | Specific argument by 0-based index | | `$N` | Shorthand for `$ARGUMENTS[N]` | | `${CLAUDE_SESSION_ID}` | Current session ID | | `${CLAUDE_SKILL_DIR}` | Directory containing the skill's SKILL.md file | ## Invocation Control | 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 | ## Dynamic Context Injection The `` !`command` `` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder. ## Running Skills in a Subagent Add `context: fork` to 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 conversation history. `context: fork` only makes sense for skills with explicit instructions. If your skill contains guidelines without a task, the subagent receives guidelines but no actionable prompt. ## Troubleshooting - Skill not triggering: Check description includes keywords users would naturally say. Try rephrasing request. Invoke directly with `/skill-name`. - Skill triggers too often: Make description more specific. Add `disable-model-invocation: true`. - Claude doesn't see all skills: Descriptions may exceed character budget (2% of context window, fallback 16,000 chars). Run `/context` to check. Override with `SLASH_COMMAND_TOOL_CHAR_BUDGET` env var. ## Extended Thinking To enable extended thinking in a skill, include the word "ultrathink" anywhere in your skill content.