# 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. ## The listing tax and `/skill-doctor` Every skill's `name` and `description` are loaded into context on every turn, whether Claude ever uses it or not. One skill is cheap. Two hundred are not, and the cost is invisible because it's paid in small amounts everywhere. [[Addy Osmani]] compared it to JavaScript bundle bloat: unused code that ships on every page load, compounding until someone measures per item instead of in aggregate. `/skill-doctor` (v2.1.252+) is the measuring tool. It shows what each skill costs in context and how often it fires, so you can decide which ones to turn off. In an interactive session it opens the report in the `/plugin` manager's **Stats** tab; with `-p` it prints as text. It needs feature-flag fetching, so it's unavailable in sessions that skip it. The maintenance routine Addy suggests, and which I've adopted: - `/skill-doctor` to find the skills that cost tokens and never run - `/skills` to disable or adjust them (overrides save locally) - `/doctor` for the setup itself: version, auth, PATH, file debt - `/context` for a live snapshot of the session, including the skill listing size *after* the budget is applied, which is what the model actually receives. `/context all` lists each skill with its source (user, project, or the providing plugin) and a rounded estimate (`~90`, `< 20`) computed with the model's tokenizer (v2.1.139+) - `/usage` for session and weekly consumption against plan limits One caveat from the comments on his post: "never invoked" and "rarely but critically invoked" look identical in the report. Check before you disable a skill that exists for a once-a-quarter task. For the other half of the question (does a skill that *does* fire change the outcome?), see [[Claude Code Plugin Evals]]. ## `/claude-api` subcommands The bundled `/claude-api` skill grew subcommands with [[Claude Fable 5.1]]: - `/claude-api cost-optimize`: diagnostics on your prompt cache configuration (cache reads are 4× cheaper on Fable 5.1, so hit rate matters more) - `/claude-api prompt-audit`: inspects prompts and skills for anti-patterns: verification rituals, emphasis boosters, scratchpad scaffolds, stale few-shot examples, contradictory rules - `/claude-api migrate`: updates API configuration to Fable 5.1 ## 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 - Find unused skills: https://code.claude.com/docs/en/skills#find-unused-skills - [[Addy Osmani]] on the five diagnostic commands: https://www.linkedin.com/posts/addyosmani_ai-programming-softwareengineering-share-7505321554847686656-X_2D ## Related - [[Claude Code]] - [[Claude Code Custom Commands]] - [[Claude Code Plugins]] - [[Claude Code Plugin Evals]] - [[Claude Code Mods]] - [[Claude Fable 5.1]] - [[Addy Osmani]] - [[AI Agent Skills]] - [[AI Agents]] - [[Anthropic]] - [[Hallmark]] - [[ASD-STE100 Simplified Technical English]]