Skills are how you teach Claude Code to do exactly what you need. Type /deploy and it runs your deployment workflow. Type /review and it checks your code against team standards. No memorizing prompts. No copy-pasting from a wiki.

If you've been using Claude Code without skills, you're doing way more typing than necessary.

This guide covers everything from your first skill to advanced patterns like subagent execution and dynamic context injection. By the end, you'll have custom commands tailored to your exact workflow.

What Skills Actually Are

A skill is a markdown file with instructions that Claude loads when relevant. Create a SKILL.md file, add some YAML frontmatter, write what you want Claude to do, and it becomes available as a slash command.

Skills serve two purposes:

Reference content: Knowledge Claude applies to your work (coding conventions, API patterns, style guides)
Task content: Step-by-step workflows Claude executes (/deploy, /commit, /fix-issue)

The recent update merged skills with the older slash commands system. If you have files in .claude/commands/, they still work. Skills just add more features: supporting files, subagent execution, and hooks.

Your First Skill in 2 Minutes

Let's create a skill that explains code with diagrams and analogies.

Step 1: Create the Directory

Skills live in a specific folder structure. For personal skills available across all projects:

mkdir -p ~/.claude/skills/explain-code

For project-specific skills that your team can share:

mkdir -p .claude/skills/explain-code

Step 2: Write SKILL.md

Create ~/.claude/skills/explain-code/SKILL.md:

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works or teaching about a codebase.
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow or structure
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake here?

Keep explanations conversational. Use multiple analogies for complex concepts.

Step 3: Use It

Two ways to trigger the skill:

Let Claude invoke it automatically by asking something that matches the description:

How does this authentication code work?

Or invoke it directly:

/explain-code src/auth/login.ts

That's it. You now have a reusable command that works in any project.

Where Skills Live

The location determines who can use it and when it takes precedence:

Location	Scope	Priority
`~/.claude/skills/`	All your projects	Personal
`.claude/skills/`	Current project only	Project
Plugin's `skills/`	Where plugin is enabled	Lowest

When skills share the same name, higher priority wins: enterprise > personal > project. Project skills are ideal for team conventions. Personal skills are for your individual workflow.

The Frontmatter Reference

All configuration happens in the YAML between --- markers. Here's what each field does:

---
name: my-skill
description: What this skill does and when to use it
argument-hint: [issue-number]
disable-model-invocation: true
user-invocable: false
allowed-tools: Read, Grep, Glob
model: haiku
context: fork
agent: Explore
---

Field	What It Does
`name`	The `/command` name. Uses directory name if omitted.
`description`	Helps Claude decide when to use this skill automatically.
`argument-hint`	Shows during autocomplete, like `[filename]`.
`disable-model-invocation`	Set `true` so only YOU can trigger it. Use for `/deploy` type commands.
`user-invocable`	Set `false` to hide from menu. For background knowledge only.
`allowed-tools`	Restrict what Claude can do when skill is active.
`model`	Use a specific model like `haiku` for speed or `opus` for quality.
`context`	Set `fork` to run in isolated subagent context.
`agent`	Which subagent type when using `context: fork`.

Passing Arguments

Skills can accept arguments via $ARGUMENTS or positional syntax.

Basic Arguments

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

When you run /fix-issue 123, Claude receives "Fix GitHub issue 123 following our coding standards..."

Positional Arguments

For multiple arguments, use $0, $1, $2 (or the longer $ARGUMENTS[0]):

---
name: migrate-component
description: Migrate a component between frameworks
---

Migrate the $0 component from $1 to $2.
Preserve all existing behavior and tests.

Running /migrate-component SearchBar React Vue substitutes correctly.

Real Examples That Ship

The Commit Skill

A skill that creates well-formatted commits:

---
name: commit
description: Create a conventional commit
disable-model-invocation: true
allowed-tools: Bash(git *)
---

1. Run `git status` and `git diff --staged`
2. Analyze all staged changes
3. Draft a commit message:
   - Use conventional commits format (feat:, fix:, etc.)
   - Keep first line under 72 characters
   - Focus on WHY not WHAT
4. Create the commit

The allowed-tools restricts Claude to only git commands. No file edits, no other bash operations.

The PR Review Skill

---
name: review-pr
description: Review a pull request
context: fork
agent: Explore
---

Review PR $0:

1. Fetch the diff with `gh pr diff $0`
2. Identify files changed
3. Check for:
   - Logic errors
   - Security issues
   - Missing error handling
   - Test coverage gaps
4. Return a summary with specific line references

Using context: fork runs this in an isolated context, keeping verbose output out of your main conversation.

The Safe Reader Skill

A read-only mode for exploring without risk:

---
name: safe-reader
description: Read files without making changes
allowed-tools: Read, Grep, Glob
---

Explore the codebase in read-only mode.
You cannot edit or write files.

Dynamic Context Injection

The !command syntax runs shell commands before the skill content is sent to Claude. The output replaces the placeholder.

---
name: pr-summary
description: Summarize current PR
context: fork
---

## Pull request context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize this pull request...

When the skill runs, each !command executes immediately. Claude receives the actual data, not the command.

Running Skills in Subagents

Adding context: fork runs the skill in isolation. The skill content becomes the prompt that drives the subagent. It won't have access to your conversation history.

This is powerful for:

Long-running research that produces verbose output
Tasks you want to run in background
Workflows with different tool permissions

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

The agent field specifies which subagent configuration to use. Built-in options: Explore (fast, read-only), Plan (research for planning), general-purpose (full capabilities).

Adding Supporting Files

Skills can include multiple files. Keep SKILL.md focused. Reference details from supporting files:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template Claude fills in
├── examples.md        # Example outputs
└── scripts/
    └── validate.sh    # Script Claude can execute

Reference them from your SKILL.md:

## Resources

- For API reference, see [reference.md](reference.md)
- For examples, see [examples.md](examples.md)

Claude loads these on demand rather than all at once.

Skills vs MCP: When to Use Each

This confuses a lot of people. The answer is simple:

MCP provides connectivity and data access (connects to Notion, Figma, databases)
Skills provide instructions and workflow logic (how to use those connections)

They're complementary. A single skill can coordinate multiple MCP servers. Multiple skills can enhance value from a single MCP connection.

Example: You have a Linear MCP for issue tracking. A skill tells Claude HOW to use it for your team's workflow.

Controlling Who Invokes Skills

Two frontmatter fields control invocation:

disable-model-invocation: true: Only you can invoke. Claude won't trigger it automatically. Use for anything with side effects: deploy, commit, send messages.

user-invocable: false: Only Claude can invoke. Hide from the / menu. Use for background knowledge that isn't an actionable command.

Frontmatter	You Can Invoke	Claude Can Invoke
(default)	Yes	Yes
`disable-model-invocation: true`	Yes	No
`user-invocable: false`	No	Yes

Adding Hooks to Skills

Skills can define hooks that run during execution. This enables self-validation. The hook receives JSON data via stdin containing tool input and output.

---
name: csv-generator
description: Generate CSV files
hooks:
  PostToolUse:
    - matcher: "Write"
      hooks:
        - type: command
          command: "./scripts/validate-csv.sh"
---

The validation script reads stdin to get the file path and validates the output:

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')
python validate_csv.py "$FILE"

Every time Claude writes a file, the validation script runs. If it exits with code 2, the operation is blocked and Claude sees the error message.

See our hooks guide for the full hook configuration reference.

Sharing Skills

With your team: Commit .claude/skills/ to version control. Everyone gets the same commands.

Across projects: Put skills in ~/.claude/skills/ for personal use everywhere.

As a plugin: Create a skills/ directory in your plugin. Others can install and use them.

The emerging ecosystem at skills.sh has pre-built skills you can install directly.

Troubleshooting

Skill Not Triggering

Check the description includes keywords Claude would recognize
Verify it appears when you type /
Try invoking directly with /skill-name

Skill Triggers Too Often

Make the description more specific
Add disable-model-invocation: true if you only want manual triggers

Claude Doesn't See All Skills

Skill descriptions have a character budget (default 15K). If you have many skills, some may be excluded. Run /context to check for warnings.

To increase the limit:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000

The Workflow That Works

Start simple. Build skills as you notice repetition:

Notice you're typing the same prompt repeatedly
Create a skill with that prompt
Add arguments for the variable parts
Refine based on what goes wrong

Don't try to build perfect skills upfront. Iterate. The best skills emerge from actual usage patterns.

What's Next

Skills are one piece of the Claude Code extensibility system. They work together with:

Hooks for automation around tool events
Subagents for specialized task delegation
MCP for external tool connections
CLAUDE.md for persistent project context

The developers shipping 50K lines in two weeks aren't typing more. They're building skills that encode their workflows, letting Claude handle the repetitive parts while they focus on architecture and decisions.

Start with one skill. The compound effect of removing friction adds up fast.

POSTS