====== Claude Code Skills ======

**Claude Code Skills** (also called **slash commands** or **custom commands**) are reusable, markdown-based instruction files that extend [[claude_code|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 [[https://agentskills.io|Agent Skills]] standard, which works across multiple AI coding tools((Source [[https://agentskills.io|Agent Skills Open Standard]])). 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((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

===== How Skills Work =====

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:

  - The user types /skillname or asks a question that matches a skill's description
  - Claude Code locates the skill definition (SKILL.md or a markdown file in .claude/commands/)
  - The skill's YAML frontmatter is parsed for configuration (allowed tools, invocation mode, context settings)
  - Any !`command` shell injections in the skill content are executed and their output is substituted in
  - The $ARGUMENTS placeholder is replaced with any arguments the user provided
  - 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((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

===== File Structure =====

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

<code>
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
</code>

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.

<code yaml>
---
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
</code>

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((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

==== Frontmatter Fields ====

All frontmatter fields are optional. Only description is recommended so Claude knows when to use the skill((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

^ Field ^ Description ^
| name | Display name and /slash-command. Defaults to the directory name. Lowercase letters, numbers, hyphens; max 64 characters. |
| description | What the skill does and when to use it. Claude uses this to decide when to auto-invoke. Truncated at 250 characters in the listing. |
| argument-hint | Hint shown during autocomplete, e.g. [issue-number] or [filename] [format]. |
| disable-model-invocation | Set true to prevent Claude from auto-loading the skill. User must invoke manually with /name. |
| user-invocable | Set false to hide from the / menu. For background knowledge only Claude should apply. |
| allowed-tools | Tools Claude can use without asking permission when this skill is active. |
| model | Override the model used when this skill is active. |
| effort | Override the effort level (low, medium, high, max). |
| context | Set fork to run in an isolated subagent context. |
| agent | Which subagent type to use when context: fork is set (e.g. Explore, Plan, or a custom agent). |
| hooks | Hooks scoped to the skill's lifecycle. |
| paths | Glob patterns that limit when the skill activates. |
| shell | Shell for inline commands (bash or powershell). |

==== String Substitutions ====

Skills support variable substitution for dynamic values in their content:

^ Variable ^ Description ^
| $ARGUMENTS | All arguments passed when invoking the skill. |
| $ARGUMENTS[N] | Access a specific argument by zero-based index. |
| $N | Shorthand for $ARGUMENTS[N] (e.g. $0, $1). |
| ${CLAUDE_SESSION_ID} | The current session ID. |
| ${CLAUDE_SKILL_DIR} | The directory containing the skill's SKILL.md. |

Example with positional arguments:

<code yaml>
---
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.
</code>

Running /migrate-component SearchBar React Vue substitutes the values into the prompt((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

===== Project vs. User vs. Enterprise Skills =====

Where a skill is stored determines its scope:

^ Location ^ Path ^ Applies To ^
| Enterprise | Managed settings (organization-deployed) | All users in the organization |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All of the user's projects |
| Project | .claude/skills/<skill-name>/SKILL.md | The specific project only |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Projects where the plugin is enabled |

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((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

**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/((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

===== Bundled 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((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])):

^ Skill ^ Purpose ^
| /batch <instruction> | Orchestrate large-scale parallel changes across a codebase using git worktrees. |
| /claude-api | Load Claude API and Agent SDK reference for the project's language. |
| /debug [description] | Enable debug logging and troubleshoot session issues. |
| /loop [interval] <prompt> | Run a prompt repeatedly on an interval (e.g. polling a deployment). |
| /simplify [focus] | Review recent changes for code reuse, quality, and efficiency; spawns three parallel review agents. |

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((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])).

===== Creating Custom Skills =====

==== Simple Example: Blog Post Generator ====

A skill for generating blog posts with a static site generator((Source [[https://cloudartisan.com/posts/2025-04-14-claude-code-tips-slash-commands/|Cloud Artisan — Claude Code Tips: Custom Slash Commands]])):

<code yaml>
---
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
</code>

Invoke with: /new-post My Article Title

==== Advanced Example: PR Summary with Dynamic Context ====

The !`command` syntax runs shell commands before the skill content reaches Claude, injecting live data into the prompt((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]])):

<code yaml>
---
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.
</code>

==== Invocation Control ====

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.

^ Frontmatter ^ User Can Invoke ^ Claude Can Invoke ^
| (default) | Yes | Yes |
| disable-model-invocation: true | Yes | No |
| user-invocable: false | No | Yes |

===== Skills vs. Hooks =====

Skills and [[claude_code|hooks]] both extend Claude Code, but they serve fundamentally different purposes((Source [[https://code.claude.com/docs/en/hooks|Anthropic — Claude Code Hooks]])):

^ Aspect ^ Skills ^ Hooks ^
| **Nature** | Prompt-based instructions Claude follows | Shell commands, HTTP calls, or LLM prompts that execute automatically |
| **Trigger** | User types /skillname or Claude auto-detects relevance | Lifecycle events fire automatically (PreToolUse, PostToolUse, Stop, etc.) |
| **Purpose** | Add reusable workflows, context, and capabilities | Validate actions, enforce policies, automate side effects |
| **Can block actions** | No — advisory only | Yes — can block tool execution (exit code 2 or decision: block) |
| **Configuration** | SKILL.md files in skills directories | JSON in settings files or hooks.json |
| **User interaction** | Interactive — user invokes and sees results | Transparent — runs in the background |
| **Analogy** | A recipe card Claude follows | A guard rail or tripwire that fires on events |

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

===== Best Practices =====

  * **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'."//((Source [[https://www.linkedin.com/posts/carlvellotti_skills-are-claude-codes-most-powerful-feature-activity-7429946350034747392-rxRN|Carl Vellotti — 10 Essential Skills Rules]]))
  * **Only build skills for repeated tasks**: If you have explained the same workflow more than three times, it belongs in a skill((Source [[https://www.linkedin.com/posts/carlvellotti_skills-are-claude-codes-most-powerful-feature-activity-7429946350034747392-rxRN|Carl Vellotti — 10 Essential Skills Rules]]))
  * **Keep SKILL.md under 500 lines**: Move detailed reference material to separate supporting files((Source [[https://code.claude.com/docs/en/skills|Anthropic — Extend Claude with skills]]))
  * **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)((Source [[https://uxplanet.org/claude-code-claude-md-vs-skills-35685676b367|Nick Babich — Claude Code CLAUDE.md vs Skills]]))
  * **Test skills with direct invocation** (/skillname) before relying on auto-detection

===== See Also =====

  * [[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]] — Engineering practices for AI agent systems

===== References =====