# Claude Code Skills Claude Code Skills are a mechanism to extend [[Claude Code]]'s capabilities with reusable instructions, scripts, and resources. Skills follow the [[AI Agent Skills]] open standard and can be invoked by the user (via `/skill-name`) or automatically by Claude when relevant to the conversation. Skills supersede the earlier "custom slash commands" system. Existing `.claude/commands/` files continue to work, but skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic loading when relevant. ## How Skills Work Each skill is a directory containing a `SKILL.md` file (required) with YAML frontmatter and Markdown instructions. The frontmatter describes what the skill does and configures its behavior. The Markdown body contains the instructions Claude follows when the skill is activated. Claude Code uses **progressive disclosure** to manage context efficiently: 1. **Metadata** (~100 tokens): `name` and `description` are loaded at startup for all skills 2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body loads only when the skill is activated 3. **Resources** (as needed): Supporting files in `scripts/`, `references/`, or `assets/` load on demand ## Skill Locations Where a skill is stored determines its scope: | Location | Path | Scope | |----------|------|-------| | Enterprise | Managed settings | All users in the organization | | Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All projects for the user | | Project | `.claude/skills/<skill-name>/SKILL.md` | Current project only | | Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Where the plugin is enabled | When skills share the same name, higher-priority locations win: enterprise > personal > project. Plugin skills use a `plugin-name:skill-name` namespace to avoid conflicts. ## Skill Directory Structure ``` my-skill/ ├── SKILL.md # Main instructions (required) ├── scripts/ # Executable scripts Claude can run ├── references/ # Additional documentation loaded on demand ├── assets/ # Templates, images, data files └── examples/ # Example outputs showing expected format ``` ## Frontmatter Fields | Field | Required | Description | |-------|----------|-------------| | `name` | No | Display name (defaults to directory name). Lowercase, numbers, hyphens only | | `description` | Recommended | What the skill does and when to use it | | `argument-hint` | No | Hint for expected arguments (e.g., `[issue-number]`) | | `disable-model-invocation` | No | Set to `true` to prevent automatic invocation by Claude | | `user-invocable` | No | Set to `false` to hide from the `/` menu | | `allowed-tools` | No | Tools Claude can use without asking permission | | `model` | No | Model to use when the skill is active | | `effort` | No | Override effort level (low, medium, high, max) | | `context` | No | Set to `fork` to run in a forked subagent context | | `agent` | No | Subagent type to use when `context: fork` is set | | `hooks` | No | Hooks scoped to the skill's lifecycle | ## Invocation Control | Configuration | User can invoke | Claude can invoke | |--------------|----------------|-------------------| | Default | Yes | Yes | | `disable-model-invocation: true` | Yes | No | | `user-invocable: false` | No | Yes | Use `disable-model-invocation: true` for workflows with side effects (e.g., deploy, commit). Use `user-invocable: false` for background knowledge Claude should use when relevant but that users shouldn't invoke directly. ## Dynamic Context The `!`command`` syntax runs shell commands before the skill content is sent to Claude. The output replaces the placeholder, enabling dynamic data injection (e.g., fetching PR diffs with `gh`). ## Arguments and variables Arguments are passed using the `$ARGUMENTS` placeholder (or `$ARGUMENTS[N]` / `$N` for positional access). If `$ARGUMENTS` is absent from the skill content, arguments are appended automatically. `${CLAUDE_SKILL_DIR}` resolves to the skill's own directory path, useful for referencing scripts, assets, or references within the skill. ## Subagent Execution Adding `context: fork` to the frontmatter runs the skill in an isolated subagent. The main conversation only sees the final result, not intermediate tool calls, keeping the primary context window clean. The forked subagent gets a fresh context window loaded with CLAUDE.md plus the skill content as its prompt. The `agent` field selects the subagent type (`Explore`, `Plan`, `general-purpose`, or a custom subagent). This is useful for skills that do heavy research or multi-step work where intermediate steps would clutter the main context. ## Bundled skills These ship with Claude Code and are available in every session: - **`/code-review`** (formerly `/simplify`): reviews recently changed files for code reuse, quality, and efficiency issues, then fixes them. Spawns review agents in parallel, aggregates findings, applies fixes. Pass optional text to focus: `/code-review focus on memory efficiency`. Accepts an `effort` parameter that controls reasoning budget vs cost: - `low` — short, scoped, latency-sensitive tasks that aren't intelligence-sensitive - `medium` — cost-sensitive work that can trade off some intelligence for fewer tokens - `high` — balances tokens and intelligence; minimum for intelligence-sensitive work, or to cut spend vs `xhigh` - `xhigh` — best results for most coding and agentic tasks; **recommended default on [[Claude Opus 4.7]]** - `max` — can improve performance on demanding tasks but shows diminishing returns and tends to overthink. Test before adopting broadly Pass `--comment` to post findings as inline PR comments. See also [[Claude Code Review]] for the managed multi-agent GitHub-integrated service. - **`/batch <instruction>`**: orchestrates large-scale changes across a codebase in parallel. Researches the codebase, decomposes work into 5-30 independent units, presents a plan for approval. Spawns one background agent per unit, each in an isolated git worktree. Each agent implements its unit, runs tests, and opens a PR. Example: `/batch migrate src/ from Solid to React` - **`/debug [description]`**: troubleshoots the current session by reading the session debug log - **`/loop [interval] <prompt>`**: runs a prompt repeatedly on an interval (see [[Claude Code Tasks]]) - **`/claude-api`**: loads Claude API reference material for your project's language and Agent SDK reference ## References - Documentation: https://code.claude.com/docs/en/skills - Agent Skills open standard: https://agentskills.io - Example skills: https://github.com/anthropics/skills - Skills (incl. /code-review, /batch): https://code.claude.com/docs/en/slash-commands ## Related - [[Claude Code]] - [[Claude Code Custom Commands]] - [[Claude Code Plugins]] - [[AI Agent Skills]] - [[AI Agents]] - [[Anthropic]]