# Skills > Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom slash commands. 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`. **Note**: Custom slash commands have been merged into skills. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. ## Getting Started ### Create Your First Skill This example creates a skill that teaches Claude to explain code using visual diagrams and analogies. #### 1. Create the Skill Directory ```bash mkdir -p ~/.claude/skills/explain-code ``` #### 2. Write SKILL.md Create `~/.claude/skills/explain-code/SKILL.md`: ```yaml --- name: explain-code description: Explains code with visual diagrams and analogies. Use when explaining how code works 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. ``` #### 3. Test the Skill Let Claude invoke it automatically: ``` How does this code work? ``` Or invoke directly: ``` /explain-code src/auth/login.ts ``` ## Where Skills Live | Location | Path | Applies to | | :--------- | :----------------------------------------------- | :----------------------------- | | Enterprise | See managed settings | All users in your organization | | Personal | `~/.claude/skills//SKILL.md` | All your projects | | Project | `.claude/skills//SKILL.md` | This project only | | Plugin | `/skills//SKILL.md` | Where plugin is enabled | Higher-priority locations win when skills share the same name: enterprise > personal > project. ### Skill Directory Structure ``` 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 ``` ## Configuring Skills ### Types of Skill Content **Reference content** adds knowledge Claude applies to your current work: ```yaml --- 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: ```yaml --- 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 ``` ### Frontmatter Reference ```yaml --- name: my-skill description: What this skill does disable-model-invocation: true allowed-tools: Read, Grep --- Your skill instructions here... ``` | Field | Required | Description | | :------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | No | Display name. If omitted, uses directory name. Lowercase letters, numbers, and hyphens only. | | `description` | Recommended | What the skill 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]` or `[filename] [format]`. | | `disable-model-invocation` | No | Set to `true` to prevent Claude from automatically loading this skill. Default: `false`. | | `user-invocable` | No | Set to `false` to hide from the `/` menu. Default: `true`. | | `allowed-tools` | No | Tools Claude can use without asking permission when this skill is active. | | `model` | No | Model to use when this skill is active. | | `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. | ### String Substitutions | Variable | Description | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- | | `$ARGUMENTS` | All arguments passed when invoking the skill. If not present, arguments are appended as `ARGUMENTS: `. | | `${CLAUDE_SESSION_ID}` | The current session ID. Useful for logging or creating session-specific files. | Example: ```yaml --- name: session-logger description: Log activity for this session --- Log the following to logs/${CLAUDE_SESSION_ID}.log: $ARGUMENTS ``` ## Control Who Invokes a Skill | 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 | ## Passing Arguments to Skills ```yaml --- 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..." ## Advanced Patterns ### Inject Dynamic Context The `` !`command` `` syntax runs shell commands before the skill content is sent to Claude: ```yaml --- 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... ``` ### Run Skills in a Subagent Add `context: fork` when you want a skill to run in isolation: ```yaml --- 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 ``` The `agent` field specifies which subagent configuration to use: - Built-in agents: `Explore`, `Plan`, `general-purpose` - Custom subagents from `.claude/agents/` ### Restrict Tool Access ```yaml --- name: safe-reader description: Read files without making changes allowed-tools: Read, Grep, Glob --- ``` ### Restrict Claude's Skill Access **Disable all skills** by denying the Skill tool in `/permissions`: ``` Skill ``` **Allow or deny specific skills**: ``` # Allow only specific skills Skill(commit) Skill(review-pr:*) # Deny specific skills Skill(deploy:*) ``` ## Generating Visual Output Skills can bundle and run scripts in any language. Example codebase visualizer: Create `~/.claude/skills/codebase-visualizer/SKILL.md`: ```yaml --- name: codebase-visualizer description: Generate an interactive collapsible tree visualization of your codebase. allowed-tools: Bash(python:*) --- # Codebase Visualizer Generate an interactive HTML tree view that shows your project's file structure. ## Usage Run the visualization script from your project root: ```bash python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . ``` ``` ## Troubleshooting ### Skill Not Triggering 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 4. Invoke it directly with `/skill-name` ### Skill Triggers Too Often 1. Make the description more specific 2. Add `disable-model-invocation: true` for manual invocation only ### Claude Doesn't See All Skills Skill descriptions are loaded into context with a character budget (default 15,000). Run `/context` to check for excluded skills. To increase the limit: ``` export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 ``` ## Grid Integration Opportunities