What Are Skills

CLAUDE.md loads every session and shapes everything. But some instructions only matter sometimes. Loading them all the time wastes context window. Skills solve this.

Skills Are On-Demand Knowledge

A skill is a reusable instruction set in a SKILL.md file. Drop it in the right directory, and Claude Code adds it to its toolkit. When a matching task comes up, Claude Code pulls it in automatically. Or you call it directly with /skill-name.

Your CLAUDE.md loads every session, no exceptions. Always-on context. Skills load on demand, only eating context window when they're relevant. Think of CLAUDE.md as your permanent briefing and skills as specialist manuals grabbed off the shelf when needed.

(You might have seen the old "commands" concept. Commands have been merged into skills. If you had custom commands, they still work, but skills are the way forward.)

How a SKILL.md File Works

Two parts: YAML frontmatter at the top, markdown content below.

---
name: deploy-staging
description: Deploy the current branch to our staging environment
argument-hint: "[branch-name]"
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Bash
---

Below the frontmatter, you write instructions in markdown. Two flavors. Reference content is knowledge Claude Code should apply while working ("Our API uses camelCase for all JSON fields"). Task content is step-by-step procedure ("Run the test suite, build the Docker image, push to registry").

The frontmatter fields you'll actually use: name and description are obvious. argument-hint tells users what arguments the skill expects. allowed-tools restricts which tools Claude Code can use during execution. model pins the skill to a specific model. context injects additional files. More fields exist, but these cover 90% of what you need.

Where Skills Live

Four levels, all discovered automatically.

Personal skills in ~/.claude/skills/<name>/SKILL.md. Follow you across every project. Your deploy workflow, your review checklist, your way of doing things.

Project skills in .claude/skills/<name>/SKILL.md inside your repo. Team-shared. Commit to source control, everyone gets them.

Plugin skills come bundled with plugins you install. Someone else wrote them.

Enterprise skills get pushed by org admins through managed settings.

Claude Code also does automatic discovery in monorepos. It walks the directory tree and finds SKILL.md files in subdirectories. No registration, no path configuration. Drop the file and it gets picked up.

Invocation Control

Two fields control who triggers a skill.

disable-model-invocation: true means only you can invoke it. Claude Code never triggers it on its own. Non-negotiable for skills with side effects. Deploying to production, running destructive database migrations, anything you wouldn't want happening because Claude Code felt like it.

user-invocable: false is the opposite. Only Claude Code can invoke it. Background knowledge that gets applied when relevant but doesn't make sense as a user-facing command.

Default: both can invoke. Claude Code triggers when it seems relevant, you can call it with /skill-name.

Bundled Skills

Claude Code ships with a handful of skills out of the box. /simplify reviews changed files and suggests simplifications. /batch handles large-scale parallel changes across many files. /debug helps troubleshoot what went wrong. /loop sets up recurring prompts. /claude-api gives Claude Code a reference for the Anthropic API so it writes correct API calls.

No install, no config. Already there.

Try it. Run /simplify after making a few changes. It reviews the diff and suggests concrete simplifications. Then create your own:

mkdir -p .claude/skills/lint-check

Create .claude/skills/lint-check/SKILL.md with this content:

---
name: lint-check
description: Run linting and fix all auto-fixable issues
user-invocable: true
allowed-tools:
  - Bash
---
 
# Lint Check
 
1. Run the project linter with the auto-fix flag
2. Review any remaining warnings that could not be auto-fixed
3. Summarize what was fixed and what needs manual attention

Type /lint-check in your next session. Claude Code follows those steps using only the Bash tool.

Skills Follow an Open Standard

Skills aren't proprietary to Claude Code. They follow the Agent Skills open standard at agentskills.io. Skills you write here could work with other tools that adopt the same standard. The format is documented and stable.

Wrapping Up

Skills load on demand while CLAUDE.md loads every session. A SKILL.md is just YAML frontmatter plus markdown instructions, living at one of four levels (personal, project, plugin, enterprise). Set disable-model-invocation: true for anything with side effects, no exceptions. And five bundled skills ship ready to use: /simplify, /batch, /debug, /loop, /claude-api.