---
title: "Claude Code Skills"
aliases: [skills, custom-skills, slash-commands, claude-skills]
tags: [claude-code, skills, customization, automation, slash-commands]
sources: [raw/Extend Claude with skills.md]
created: 2026-04-17
updated: 2026-04-17
---

# Claude Code Skills

Skills extend Claude's capabilities via a `SKILL.md` file. Claude loads them automatically when relevant, or you invoke directly with `/skill-name`. They supersede the old `.claude/commands/` system — commands still work, but skills add more features.

## When to Create a Skill

- You keep pasting the same playbook or checklist into chat
- A section of `CLAUDE.md` has grown into a procedure rather than a fact
- Skill body only loads when used → long reference material costs nothing at rest

## Where Skills Live

| Scope | Path | Applies to |
|-------|------|------------|
| Enterprise | Managed settings | All org users |
| Personal | `~/.claude/skills/<name>/SKILL.md` | All your projects |
| Project | `.claude/skills/<name>/SKILL.md` | This project only |
| Plugin | `<plugin>/skills/<name>/SKILL.md` | Where plugin is enabled |

- Priority order: **enterprise > personal > project**; plugin skills use `plugin-name:skill-name` namespace
- Live reload: edits take effect within the session (no restart needed unless adding a brand-new directory)
- Monorepo: nested `.claude/skills/` in subdirectories are auto-discovered

## File Structure

```
my-skill/
├── SKILL.md           # Main instructions (required, keep < 500 lines)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output
└── scripts/
    └── helper.py      # Script Claude can execute
```

Reference supporting files from `SKILL.md` so Claude knows when to load them.

## Frontmatter Reference

All fields optional; `description` is strongly recommended.

| Field | Description |
|-------|-------------|
| `name` | Display name (lowercase, hyphens, max 64 chars). Defaults to directory name. |
| `description` | What the skill does; Claude uses this to decide when to apply it. Front-load key use case. |
| `when_to_use` | Extra trigger phrases; appended to `description` in skill listing. |
| `argument-hint` | Autocomplete hint, e.g. `[issue-number]`. |
| `disable-model-invocation` | `true` = only you can invoke (not auto-triggered by Claude). |
| `user-invocable` | `false` = hidden from `/` menu; Claude-only. |
| `allowed-tools` | Tools pre-approved for this skill (no per-use prompt). Space-separated or YAML list. |
| `model` | Override model for this skill. |
| `effort` | Override effort level: `low`, `medium`, `high`, `xhigh`, `max`. |
| `context` | `fork` = run in isolated subagent. |
| `agent` | Which subagent to use when `context: fork` (e.g. `Explore`, `Plan`, `general-purpose`). |
| `hooks` | Lifecycle hooks scoped to this skill. |
| `paths` | Glob patterns; skill auto-activates only when working with matching files. |
| `shell` | Shell for inline `!` commands: `bash` (default) or `powershell`. |

## Invocation Control

| Frontmatter | You invoke | Claude invokes | In context |
|-------------|-----------|----------------|------------|
| (default) | Yes | Yes | Description always; full body on invoke |
| `disable-model-invocation: true` | Yes | No | Not in context; full body on your invoke |
| `user-invocable: false` | No | Yes | Description always; full body on invoke |

Use `disable-model-invocation: true` for side-effect workflows (`/deploy`, `/commit`, `/send-slack-message`).

## Passing Arguments

- `$ARGUMENTS` — full argument string
- `$ARGUMENTS[N]` or `$N` — positional (0-based); wrap multi-word in quotes
- If `$ARGUMENTS` absent in content, appended as `ARGUMENTS: <value>`

```yaml
---
name: fix-issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.
```

## Dynamic Context Injection

`` !`command` `` runs shell commands *before* Claude sees the prompt — output replaces the placeholder.

```yaml
---
name: pr-summary
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---
- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`
```

Multi-line variant: fenced block opened with ` ```! `.

Disable globally: `"disableSkillShellExecution": true` in settings.

## Running in a Subagent

`context: fork` isolates the skill in a subagent — no access to conversation history.

```yaml
---
name: deep-research
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...
```

| Approach | System prompt | Task |
|----------|--------------|------|
| Skill + `context: fork` | From agent type | SKILL.md content |
| Subagent + `skills` field | Subagent markdown | Claude's delegation message |

## Bundled Skills

Available in every session: `/simplify`, `/batch`, `/debug`, `/loop`, `/claude-api`. Prompt-based (not fixed logic). Invoke with `/skill-name`.

## Skill Content Lifecycle

- On invocation: rendered `SKILL.md` enters conversation as a message, persists for the session
- Auto-compaction: most recent invocation re-attached after summary (first 5,000 tokens per skill, 25,000 combined budget across all skills)
- If a skill stops influencing behavior → re-invoke after compaction, or strengthen `description`

## Pre-Approving Tools

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

This grants those tools without per-use approval. It does NOT restrict other tools.

## Controlling Claude's Skill Access

```
# Deny all skills
Skill

# Allow specific skills
Skill(commit)
Skill(review-pr *)

# Deny specific skill
Skill(deploy *)
```

Syntax: `Skill(name)` exact match, `Skill(name *)` prefix match.

## Sharing Skills

- **Project**: commit `.claude/skills/` to version control
- **Plugin**: add `skills/` directory in your [[wiki/claude-code/create-plugins|plugin]]
- **Org-wide**: deploy via managed settings

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Skill not triggering | Check description keywords; verify with "What skills are available?"; invoke directly |
| Skill triggers too often | Make description more specific; add `disable-model-invocation: true` |
| Description cut short | Trim `description`/`when_to_use`; front-load key use case; or set `SLASH_COMMAND_TOOL_CHAR_BUDGET` |

## Key Takeaways

- Skills = lazy-loaded playbooks that cost nothing until invoked
- Store globally (`~/.claude/skills/`) or per-project (`.claude/skills/`)
- `disable-model-invocation: true` for side-effect commands you want to control manually
- `user-invocable: false` for background knowledge Claude should load automatically
- `context: fork` to run skill in an isolated subagent with its own context
- Dynamic shell injection (`` !`cmd` ``) pre-populates prompts with live data before Claude sees them
- `allowed-tools` pre-approves specific tools so Claude doesn't prompt during the skill
- After auto-compaction, re-invoke large skills to restore full content

## Related

- [[wiki/claude-code/custom-subagents|Custom Subagents]] — delegate tasks to specialized agents
- [[wiki/claude-code/create-plugins|Create Plugins]] — package and distribute skills
- [[wiki/claude-code/overview|Claude Code Overview]] — full product overview

## Sources

- `raw/Extend Claude with skills.md` — official Claude Code skills documentation