How to Use Skills in Claude Code

Skills let you create custom slash commands that automate your workflows. Write the instructions once, then trigger them with a simple /command whenever you need them.

Skills in Claude Code are custom slash commands you create by adding a folder with a SKILL.md file inside ~/.claude/skills/. The folder name becomes the command — type /folder-name and Claude follows your instructions automatically. They let you automate repetitive workflows like code reviews, deployments, and report formatting with a single keystroke.

This guide shows you how to create skills from scratch, with real examples you can copy and start using today.

What Are Skills in Claude Code?

A skill is a folder containing instructions for Claude. The folder name becomes your command. When you type /folder-name, Claude reads those instructions and follows them.

Here's the core concept:

• Folder: ~/.claude/skills/review/
• File inside: SKILL.md (contains instructions)
• Result: You can type /review in Claude Code

That's it. Create a folder, add a SKILL.md file with instructions, and you have a custom command.

Where to Put Your Skills

Skills can live in two places:

Put general-purpose skills (like a code review command) in the personal folder. Put project-specific skills (like your project's deploy process) in the project folder. When skills share the same name, higher-priority locations win: enterprise > personal > project.

Skills are also automatically discovered from nested .claude/skills/ directories. For example, in a monorepo, skills in packages/frontend/.claude/skills/ are discovered when you're editing files in that package.

Creating Your First Skill

Let's create a simple skill that generates meeting notes from a discussion.

mkdir -p ~/.claude/skills/meeting-notes

---
name: meeting-notes
description: Generate structured meeting notes from a discussion or transcript
---

When the user provides meeting content, create structured notes with:

1. **Meeting Summary** (2-3 sentences)
2. **Key Decisions** (bullet points)
3. **Action Items** (with owners and deadlines if mentioned)
4. **Open Questions** (things that need follow-up)
5. **Next Steps**

Keep the notes concise. Use the participants' actual words when quoting decisions.
If no deadline is mentioned for an action item, note it as "TBD".

The SKILL.md Format

Every SKILL.md file has two parts:

1. Frontmatter (Required)

The section between --- markers contains metadata:

---
name: skill-name
description: What this skill does. Claude uses this to decide when to auto-load it.
---

The name field becomes your slash command. The description helps Claude know when the skill is relevant.

2. Instructions (Required)

Everything after the frontmatter is markdown instructions that Claude follows when the skill is invoked.

Optional Frontmatter Fields

Use disable-model-invocation for skills with side effects like deployments or sending messages. You want manual control over when those run.

Skill Directory Structure

Skills can include more than just SKILL.md. You can add helper scripts, templates, and data files:

.claude/skills/
├── code-review/
│   ├── SKILL.md              # Main instructions
│   ├── checklist.md          # Reference checklist
│   └── templates/
│       └── review-comment.md # Template for comments
├── deploy/
│   ├── SKILL.md
│   └── deploy.sh             # Helper script
└── report/
    ├── SKILL.md
    └── format.json           # Data file

Claude can access these files when running the skill. Reference them in your SKILL.md instructions.

Real Examples of Useful Skills

Example 1: Code Review Skill

File: ~/.claude/skills/review/SKILL.md

---
name: review
description: Review code changes for quality, security, and best practices
---

Review the recent code changes:

1. Run `git diff main` to see what changed
2. Check for security issues:
   - Hardcoded secrets or API keys
   - SQL injection vulnerabilities
   - Unvalidated user input
3. Check for performance problems:
   - N+1 query patterns
   - Missing database indexes
   - Unnecessary loops or computations
4. Check for maintainability:
   - Clear variable names
   - Appropriate comments
   - Test coverage

Report findings in three categories:
- **Critical** (must fix before merge)
- **Warnings** (should fix soon)
- **Suggestions** (nice to have)

Example 2: Daily Standup Skill

File: ~/.claude/skills/standup/SKILL.md

---
name: standup
description: Generate a daily standup update from recent activity
---

Generate my daily standup by:

1. Check `git log --since="yesterday" --author="$(git config user.name)"` for my commits
2. Look at any open PRs I'm working on
3. Check for any failing tests or CI issues

Format as:
**Yesterday:** [What I completed]
**Today:** [What I'm planning to work on]
**Blockers:** [Any issues preventing progress]

Keep it brief—3-4 bullet points max per section.

Example 3: Weekly Report Skill

File: ~/.claude/skills/weekly-report/SKILL.md

---
name: weekly-report
description: Generate a weekly progress report for stakeholders
---

Generate a weekly progress report:

1. Check commits from the past week: `git log --since="1 week ago"`
2. Summarize by category (features, fixes, documentation)
3. List any metrics improvements if available
4. Note upcoming work from TODO comments or issue tracker

Format for non-technical stakeholders:
- Lead with accomplishments and business impact
- Avoid technical jargon
- Include "Next Week" section with priorities
- Keep total length under 300 words

Example 4: Fix Issue Skill with Arguments

File: ~/.claude/skills/fix-issue/SKILL.md

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

Fix GitHub issue #$0:

1. Read the issue details from GitHub
2. Understand the problem and requirements
3. Find the relevant code
4. Implement the fix
5. Write or update tests
6. Create a commit with message: "Fix #$0: [brief description]"

If the issue is unclear, ask for clarification before starting.

Use it: /fix-issue 42

Passing Arguments to Skills

Skills can accept arguments when invoked. Use these variables in your SKILL.md:

Example: /deploy production fast sets $0 to "production" and $1 to "fast". You can also use ${CLAUDE_SESSION_ID} in your skill content for the current session ID, useful for logging or creating session-specific files.

Skills vs. CLAUDE.md: When to Use Which

Running Skills in Subagents

Add context: fork to your frontmatter to run a skill in an isolated subagent context. The skill content becomes the prompt that drives the subagent, separate from your main conversation history.

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

When this skill runs, a new isolated context is created. The agent field determines the execution environment (model, tools, and permissions). Results are summarized and returned to your main conversation. Options include built-in agents (Explore, Plan, general-purpose) or any custom subagent from .claude/agents/.

Dynamic Context Injection

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

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

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

Each ! backtick command executes immediately before Claude sees anything. Claude only sees the final result with actual data inserted.

Cross-Platform Skills

Skills aren't limited to Claude Code. They also work in:

• Claude.ai (web interface)
• Claude Desktop (app)

Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Define a skill once, use it everywhere. This is useful for teams that want consistent workflows across different Claude interfaces.

Best Practices

1. Keep SKILL.md under 500 lines. If you need more detail, put it in separate files and reference them.
2. Write clear descriptions. The description field helps Claude know when to auto-suggest your skill.
3. Use disable-model-invocation for dangerous skills. Anything that deploys, sends messages, or has side effects should be manual-only.
4. Test with simple cases first. Make sure your skill works before adding complexity.
5. Use arguments for flexibility. Instead of creating review-frontend and review-backend, create one review skill that takes a component argument.

Common Mistakes to Avoid

1. Wrong file name: It must be exactly SKILL.md (uppercase SKILL, lowercase .md).
2. Missing frontmatter: Every SKILL.md needs the --- section with at least a name.
3. Too long: Claude gets confused with very long instructions. Keep it focused.
4. Forgetting the folder: Each skill needs its own folder. You can't just create a file.
5. Spaces in folder names: Use hyphens instead of spaces. code-review not code review.

FAQ

How do I see all my available skills?

Type / in Claude Code and your custom skills appear in the command menu alongside built-in commands.

Can I share skills with my team?

Yes. Put skills in your project's .claude/skills/ folder and commit them to git. Everyone who clones the repo gets the same skills.

Why doesn't my skill show up?

Check four things: (1) folder is in ~/.claude/skills/ or .claude/skills/, (2) file is named exactly SKILL.md, (3) folder name uses lowercase and hyphens only, (4) you haven't exceeded the skill description character budget (2% of context window, ~16,000 chars fallback). Run /context to check for warnings about excluded skills.

Can Claude run skills automatically?

Yes. By default, Claude can detect when a skill is relevant and load it based on your request. Add disable-model-invocation: true to prevent this.

How do I edit an existing skill?

Just edit the SKILL.md file. Changes take effect immediately on your next conversation.

Related Guides

• How to Use Slash Commands — built-in commands reference
• How to Use MCP Servers — connect external tools
• How to Use CLAUDE.md Files — project configuration
• What Is Claude Code? — understand the basics