Claude Code Skills (also called slash commands or custom commands) are reusable, markdown-based instruction files that extend Claude Code's capabilities. When a developer types /skillname in a Claude Code session, the system loads the corresponding markdown file and uses it as a prompt, giving Claude specific instructions for a task or workflow. Skills follow the open Agent Skills standard, which works across multiple AI coding tools¹⁾. The feature was introduced in late 2025 and has since evolved into a full programmable agent platform with subagent execution, dynamic context injection, and lifecycle hooks²⁾.

Skills are markdown files stored in specific directories. When a user types / in Claude Code, the system displays a list of available commands — both built-in and custom. Claude Code reads the skill's description to determine when it should be loaded automatically, or the user can invoke a skill directly by name.

The lifecycle of a skill invocation:

1. The user types /skillname or asks a question that matches a skill's description
2. Claude Code locates the skill definition (SKILL.md or a markdown file in .claude/commands/)
3. The skill's YAML frontmatter is parsed for configuration (allowed tools, invocation mode, context settings)
4. Any !`command` shell injections in the skill content are executed and their output is substituted in
5. The $ARGUMENTS placeholder is replaced with any arguments the user provided
6. The fully-rendered prompt is sent to Claude, which follows the instructions

Skill descriptions are loaded into context so Claude knows what skills are available, but the full skill content only loads when actually invoked. This keeps token usage efficient³⁾.

Each skill is a directory containing a SKILL.md file as the entrypoint, plus optional supporting files:

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

The SKILL.md file has two parts: YAML frontmatter (between — markers) that configures behavior, and markdown content with instructions Claude follows when the skill is invoked.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Deploy $ARGUMENTS to production:

1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Legacy .claude/commands/ files (plain markdown without a directory wrapper) continue to work and support the same frontmatter. Skills are the recommended format since they support additional features like supporting files and subagent execution⁴⁾.

All frontmatter fields are optional. Only description is recommended so Claude knows when to use the skill⁵⁾.

Skills support variable substitution for dynamic values in their content:

Example with positional arguments:

---
name: migrate-component
description: Migrate a component from one framework to another
---
 
Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Running /migrate-component SearchBar React Vue substitutes the values into the prompt⁶⁾.

Where a skill is stored determines its scope:

When skills share the same name across levels, higher-priority locations win: enterprise overrides personal, which overrides project. Plugin skills use a plugin-name:skill-name namespace so they cannot conflict with other levels⁷⁾.

Project skills (stored in .claude/skills/ or .claude/commands/) are committed to version control and shared with the entire team. Personal skills (stored in ~/.claude/skills/ or ~/.claude/commands/) are private to the developer and work across all projects.

Claude Code also supports automatic discovery from nested directories in monorepos. Editing a file in packages/frontend/ causes Claude to also check packages/frontend/.claude/skills/⁸⁾.

Claude Code ships with several bundled skills available in every session. Unlike built-in commands (which execute fixed logic), bundled skills are prompt-based playbooks that let Claude orchestrate work using its tools⁹⁾:

Built-in commands like /help, /compact, /clear, /model, /effort, /copy, and /permissions are separate from skills — they execute fixed logic directly rather than loading prompt-based instructions¹⁰⁾.

A skill for generating blog posts with a static site generator¹¹⁾:

---
name: new-post
description: Create a new blog post draft
disable-model-invocation: true
argument-hint: <title>
---

I want to create a new blog post with the following title: $ARGUMENTS
 
1. Generate the proper kebab-case filename with today's date
2. Create the file with the appropriate scaffolding command
3. Update the front matter with title, date, and draft status
4. Show the command to serve the site locally for preview

Invoke with: /new-post My Article Title

The !`command` syntax runs shell commands before the skill content reaches Claude, injecting live data into the prompt¹²⁾:

---
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 concisely.

Two frontmatter fields control who can trigger a skill:

• disable-model-invocation: true: Only the user can invoke the skill. Use for workflows with side effects like deploying or committing.
• user-invocable: false: Only Claude can invoke the skill. Use for background knowledge that is not meaningful as a user action.

Skills and hooks both extend Claude Code, but they serve fundamentally different purposes¹³⁾:

When to use skills: Repeatable workflows (code review, deployment, test generation), encoding team knowledge, prompt templates that benefit from reuse.

When to use hooks: Preventing dangerous commands (blocking rm -rf), auto-formatting files after edits, enforcing linting on every save, loading environment variables at session start.

• Front-load the description: The description field drives auto-invocation. Write trigger phrases, not summaries. Example: “When user wants to deploy. Triggers: 'ship it', 'push to prod'.”¹⁴⁾
• Only build skills for repeated tasks: If you have explained the same workflow more than three times, it belongs in a skill¹⁵⁾
• Keep SKILL.md under 500 lines: Move detailed reference material to separate supporting files¹⁶⁾
• Restrict tools when possible: Use allowed-tools to limit what Claude can do during a skill, reducing the risk of unintended side effects
• Use disable-model-invocation: true for dangerous workflows: Deployments, database migrations, and anything with side effects should require explicit user invocation
• Commit project skills to version control: Skills in .claude/skills/ become shared team knowledge
• Put context in CLAUDE.md, capabilities in skills: CLAUDE.md is the “project brain” (always loaded); skills are reusable capabilities (loaded on demand)¹⁷⁾
• Test skills with direct invocation (/skillname) before relying on auto-detection

• Claude Code — Overview of the Claude Code CLI agent
• claude_agent_sdk — The SDK for building agents with Claude Code as a library
• System Prompt Templates — Techniques for authoring effective system prompts
• Agentic Engineering: Disciplined AI-Assisted Software Development — Engineering practices for AI agent systems