Claude Code Skills: Complete Guide to Custom Commands & Slash Commands

This article may contain affiliate links. We may earn a small commission if you purchase through our links, at no extra cost to you. We only recommend tools we’ve personally tested.

Affiliate Disclosure: Some links in this article are affiliate links. If you make a purchase through these links, we may earn a commission at no additional cost to you. We only recommend tools we actively use and trust.

If you have been using Claude Code for more than a few days, you have probably noticed yourself typing the same instructions over and over. “Review this PR.” “Run the tests and fix failures.” “Write a commit message following our conventions.” Claude Code skills solve this problem by letting you package reusable prompts and workflows into custom slash commands you can invoke with a single keystroke.

In this guide, you will learn everything about Claude Code skills: what they are, how to create them, and how to use them to dramatically speed up your development workflow. Whether you want a simple /commit shortcut or a multi-step deploy pipeline, this article has you covered.

For a broader overview of Claude Code’s feature set, see our complete Claude Code guide.

—

What Are Claude Code Skills?

Claude Code skills are custom slash commands that you define to encapsulate reusable prompts, instructions, and workflows. When you type / in Claude Code, you see a list of available commands. Skills let you add your own entries to that list.

Think of skills as saved prompt templates with superpowers. Unlike a simple text snippet, a skill can:

• Accept arguments and parameters from the user at invocation time
• Include multi-step instructions that Claude follows sequentially
• Reference file paths, tools, and project context dynamically
• Be scoped to a specific project or shared globally across all projects
• Be version-controlled alongside your codebase

Built-in Skills vs Custom Skills

Claude Code ships with several built-in skills that handle common development tasks:

These built-in skills work out of the box, but custom skills are where the real power lies. You can create skills tailored to your team’s exact workflow, coding standards, and deployment process.

—

How to Create Custom Skills

There are two approaches to defining custom skills in Claude Code: CLAUDE.md skill definitions and the .claude/skills/ directory. Both methods work, and you can mix them in the same project.

Method 1: The .claude/skills/ Directory

The recommended approach for most teams is to create skill files in your project’s .claude/skills/ directory. Each skill gets its own markdown file.

Step 1: Create the Skills Directory

mkdir -p .claude/skills

Step 2: Create a Skill File

Each .md file in the skills directory becomes a slash command. The filename determines the command name. For example, .claude/skills/test.md becomes the /test command.

Here is a basic skill file:

---
name: test
description: Run tests and fix any failures
arguments:

name: scope

description: Test scope (unit, integration, e2e, or all)
required: false
default: all
---

# Test Runner Skill

Run the test suite for this project and handle failures.

Instructions


Identify the test framework used in this project (check package.json, pyproject.toml, Cargo.toml, etc.)
Run the test suite with scope: $ARGUMENTS.scope
If any tests fail:


Analyze the failure output
Identify the root cause
Fix the code (not the test, unless the test itself is wrong)
Re-run the failing tests to confirm the fix


Report a summary of results

Step 3: Use Your Skill

Now you can invoke it in Claude Code:

/test
/test --scope unit
/test --scope e2e

Method 2: CLAUDE.md Skill Definitions

For simpler skills or project-wide conventions, you can define skills directly in your CLAUDE.md file. This keeps everything in one place and is useful for skills that are tightly coupled to project instructions.

# Skills

/deploy
Deploy the current branch to the specified environment.

Run the test suite. Abort if any tests fail.
Build the production bundle with npm run build
Deploy to the target environment using ./scripts/deploy.sh $ARGUMENTS.env
Verify the deployment by checking the health endpoint
Report the deployment status


Arguments:

env (required): Target environment (staging, production)

Which Method Should You Use?

For most teams, we recommend the .claude/skills/ directory for anything beyond trivial one-liners.

—

Skill Syntax and Parameters

Understanding the full syntax available in skill definitions lets you build more powerful and flexible commands.

YAML Frontmatter

Every skill file supports optional YAML frontmatter for metadata:

---
name: skill-name          # Command name (defaults to filename)
description: Short desc    # Shown in autocomplete
arguments:                 # Parameters the skill accepts

name: param_name

description: What this param does
required: true         # true or false
default: some_value    # Default if not provided
allowed_tools:             # Restrict which tools the skill can use

Bash
Read
Edit

---

Variable Interpolation

Skills can reference dynamic values within their instructions:

Multi-Step Instructions

Structure your skill instructions as numbered steps for reliable execution:

## Instructions


First, read the relevant configuration files
Then, analyze the current state
Make the necessary changes
Verify the changes work correctly
Report what was done

Claude follows these steps sequentially, which gives you predictable, repeatable workflows.

—

Practical Examples

Let’s walk through several real-world skills that you can adapt for your own projects.

Example 1: Smart Commit Skill

This skill goes beyond the built-in /commit by enforcing your team’s commit conventions:

---
name: commit
description: Create a conventional commit with smart analysis
arguments:

name: type

description: "Commit type: feat, fix, refactor, docs, test, chore"
required: false
---

# Smart Commit

Create a git commit following Conventional Commits specification.

Instructions


Run git status and git diff --staged to understand what changed
If nothing is staged, identify the relevant changed files and stage them


Never stage .env files, credentials, or large binary files


Analyze the changes to determine:


The appropriate commit type (feat, fix, refactor, docs, test, chore)
If a type was provided via $ARGUMENTS.type, use that instead
A concise summary (under 72 characters)
Whether a longer body is warranted


Format the commit message as:

   

type(scope): summary

Optional longer description if the change is complex.

5. Create the commit

Show the commit hash and message for confirmation

Example 2: PR Review Skill

A thorough code review skill that checks for common issues:

---
name: review
description: Perform a thorough code review on the current changes
arguments:

name: base

description: Base branch to compare against
required: false
default: main
---

# Code Review Skill

Instructions


Get the diff: git diff $ARGUMENTS.base...HEAD
Also review the individual commits: git log --oneline $ARGUMENTS.base...HEAD
For each changed file, analyze:


Correctness: Logic errors, edge cases, off-by-one errors
Security: SQL injection, XSS, credential exposure, path traversal
Performance: N+1 queries, unnecessary re-renders, memory leaks
Readability: Naming, complexity, documentation
Testing: Are changes covered by tests? Should new tests be added?


Check for:


Breaking API changes without version bumps
Missing database migrations
Dependency changes that need security review


Format the review as:


Summary: One paragraph overview
Critical Issues: Must fix before merge (if any)
Suggestions: Nice-to-have improvements
Positive Notes: What was done well

Example 3: Deploy Skill

Automate your deployment pipeline with safety checks:

---
name: deploy
description: Deploy to staging or production with safety checks
arguments:

name: env

description: Target environment (staging or production)
required: true

name: skip-tests

description: Skip test suite (use with caution)
required: false
default: "false"
---

# Deploy Skill

Instructions


Confirm the current branch and environment:


If deploying to production, verify we are on the main branch
If not on main, warn and abort unless overridden


Unless skip-tests is "true", run the full test suite


Abort deployment if any tests fail


Build the project: npm run build
Run environment-specific deployment:


staging: ./scripts/deploy.sh staging
production: ./scripts/deploy.sh production


Wait for the deployment to complete
Verify the health endpoint responds with 200
Run smoke tests against the deployed environment
Report deployment status with:


Environment URL
Deployed commit hash
Any warnings or notes

Example 4: Documentation Generator

Automatically generate or update documentation:

---
name: docs
description: Generate or update documentation for a module
arguments:

name: path

description: Path to the module or file to document
required: true
---

# Documentation Generator

Instructions


Read the source file(s) at $ARGUMENTS.path
Analyze the public API:


Exported functions, classes, and types
Parameters and return types
Side effects and dependencies


Check for existing documentation in the same directory
Generate or update documentation including:


Module overview and purpose
Installation/setup if applicable
API reference for each export
Usage examples for common patterns
Edge cases or gotchas


Write the documentation as a markdown file alongside the source
If JSDoc/docstrings are missing in the source, add them too

Example 5: Database Migration Skill

For projects with database migrations:

---
name: migrate
description: Create and verify a database migration
arguments:

name: name

description: Migration name (e.g., add-users-email-index)
required: true

name: action

description: "Action: create, run, rollback, or status"
required: false
default: create
---

# Database Migration Skill

Instructions


Detect the migration framework (Prisma, Knex, Django, Alembic, etc.)
Based on $ARGUMENTS.action:


create: Generate a new migration file named $ARGUMENTS.name
run: Apply pending migrations
rollback: Revert the last migration
status: Show migration status


If creating a migration:


Generate both the up and down migration
Ensure the down migration fully reverses the up migration
Add appropriate indexes
Handle nullable fields explicitly


After running or rolling back, verify the schema state
Report what changed in the database schema

—

How Skills Differ from Hooks

A common point of confusion is the difference between skills and hooks. They serve fundamentally different purposes:

Hooks run automatically when certain events occur (like before a commit or after a file save). Skills only run when you explicitly invoke them. Use hooks for enforcement and guardrails; use skills for workflows and productivity.

—

How Skills Differ from MCP Tools

Another distinction worth understanding is between skills and MCP (Model Context Protocol) tools. If you are building custom integrations, knowing when to use each is important.

Use skills when you want to combine and orchestrate Claude’s existing tools (Bash, Read, Edit, etc.) into repeatable workflows. Use MCP tools when you need Claude to interact with external systems it cannot reach natively — databases, APIs, custom services.

For a deep dive into building MCP servers, see our guide to building MCP servers.

—

Advanced Patterns

Once you are comfortable with basic skills, these advanced patterns unlock even more powerful workflows.

Chaining Skills

You can reference other skills within a skill’s instructions to create multi-step pipelines:

---
name: release
description: Full release pipeline
arguments:

name: version

description: Release version (e.g., 1.2.0)
required: true
---

# Release Pipeline

Instructions


Update version numbers in package.json and related files to $ARGUMENTS.version
Run the full test suite (as if invoking /test --scope all)
Generate a changelog entry from commits since the last tag
Create a commit with message: "chore: release v$ARGUMENTS.version"
Create a git tag: v$ARGUMENTS.version
Build the production bundle
Deploy to staging first (as if invoking /deploy --env staging)
After staging verification, deploy to production (as if invoking /deploy --env production)
Create a GitHub release with the changelog as the body

Conditional Logic

Skills can include conditional instructions that Claude evaluates at runtime:

## Instructions


Check the project type:


If package.json exists: this is a Node.js project, use npm/yarn
If pyproject.toml exists: this is a Python project, use pip/poetry
If Cargo.toml exists: this is a Rust project, use cargo
If go.mod exists: this is a Go project, use go toolchain


Run the appropriate test command for the detected project type
If the project has a CI configuration (.github/workflows/, .gitlab-ci.yml, etc.),

verify that local test results match what CI would run

Project-Aware Skills with Context Loading

Skills can instruct Claude to read project configuration before taking action:

---
name: lint-fix
description: Fix all linting issues in the project
---

# Lint Fix Skill

Instructions


Read the project's linting configuration:


.eslintrc, biome.json, .prettierrc, ruff.toml, .golangci.yml, etc.


Read CLAUDE.md for any project-specific coding standards
Run the project's lint command with auto-fix enabled
For any remaining issues that could not be auto-fixed:


Read the offending file
Apply the fix manually following the project's style guide


Run the linter again to confirm zero remaining issues
Stage the fixed files (do not commit)

Scoped Skills: Global vs Project

You can define skills at different scopes:

• Project skills (.claude/skills/): Available only in that project. Committed to version control and shared with your team.
• User-global skills (~/.claude/skills/): Available in all your projects. Personal productivity shortcuts.

# Project skill (shared with team)
mkdir -p .claude/skills
echo "# My project skill" > .claude/skills/my-skill.md

# Global skill (personal, all projects)
mkdir -p ~/.claude/skills
echo "# My global skill" > ~/.claude/skills/my-skill.md

If both scopes define a skill with the same name, the project-level skill takes priority.

—

Community Skills and Sharing

One of the advantages of skills being plain markdown files is that they are trivially easy to share.

Sharing Skills with Your Team

Since skills live in the .claude/skills/ directory, they are automatically version-controlled when you commit them. Every team member who clones the repo gets the same skills. This is a powerful way to standardize workflows across your organization.

Discovering Community Skills

The Claude Code community has started sharing skill collections. Common places to find them:

• GitHub repositories tagged with claude-code-skills
• Blog posts and tutorials from the developer community
• Team-specific collections shared internally

Creating a Skill Library

For organizations with multiple projects, consider creating a shared skill library:

# Create a shared skills repo
git init claude-code-skills-library

# Organize by category
mkdir -p skills/{git,testing,deployment,documentation,security}

# In each project, symlink or copy the skills you need
ln -s /path/to/claude-code-skills-library/skills/git/smart-commit.md .claude/skills/commit.md

—

Best Practices

After building dozens of custom skills, here are the patterns that lead to the most reliable results:

1. Be specific in your instructions. Vague prompts produce vague results. Tell Claude exactly what tools to use, what output format to produce, and what edge cases to handle.

1. Include verification steps. Every skill should end with a verification step that confirms the action succeeded. “Run the tests,” “Check the health endpoint,” “Verify the file was created.”

1. Handle failure gracefully. Include instructions for what Claude should do when something goes wrong. “If the build fails, analyze the error and fix it before proceeding.”

1. Keep skills focused. A skill that does one thing well is more useful than a skill that tries to do everything. Compose simple skills into pipelines for complex workflows.

1. Document your skills. Use the description field in frontmatter so your team knows what each skill does without reading the full definition.

1. Test your skills. Try your skill in different scenarios to make sure the instructions are robust. Edge cases in your instructions become edge cases in Claude’s behavior.

1. Version your skills with your code. Skills in .claude/skills/ should be committed alongside the code they operate on. When your project’s structure changes, update the skills to match.

—

—

Frequently Asked Questions

What is a Claude Code skill?

A Claude Code skill is a custom slash command defined in a markdown file that packages reusable prompts and multi-step instructions into a single, invocable command. Skills live in your project’s .claude/skills/ directory or in your CLAUDE.md file and can accept arguments, reference project context, and orchestrate Claude’s built-in tools.

How do I create a custom slash command in Claude Code?

Create a markdown file in your project’s .claude/skills/ directory. The filename becomes the command name. For example, creating .claude/skills/deploy.md gives you the /deploy command. Add YAML frontmatter for metadata and arguments, then write your instructions in markdown.

Can Claude Code skills accept parameters?

Yes. Define arguments in the YAML frontmatter of your skill file using the arguments array. Each argument can have a name, description, required flag, and default value. Reference arguments in your instructions using $ARGUMENTS.name syntax.

What is the difference between Claude Code skills and hooks?

Skills are user-triggered slash commands for reusable workflows. Hooks are event-triggered automations that run before or after specific actions (like commits or file saves). Use skills for on-demand tasks and hooks for automatic enforcement and guardrails.

Can I share Claude Code skills with my team?

Yes. Skills stored in your project’s .claude/skills/ directory are version-controlled with your codebase. When team members clone the repository, they automatically get access to all project skills.

Do Claude Code skills work with MCP tools?

Yes. Skills can instruct Claude to use any available tool, including MCP tools. If you have MCP servers configured, your skills can reference those tools in their instructions. Skills orchestrate tools; MCP tools provide new capabilities.

How many skills can I define in a project?

There is no hard limit on the number of skills you can define. However, for maintainability, keep your skill collection focused on the workflows your team actually uses. A curated set of 10-15 well-crafted skills is more valuable than 50 barely-used ones.

Can skills call other skills?

Not directly through a formal invocation mechanism. However, you can write a skill’s instructions to perform the same steps another skill would. For complex pipelines, describe the full workflow in a single “orchestrator” skill that encompasses all the necessary steps.

—

Conclusion

Claude Code skills transform repetitive development tasks into one-command workflows. By defining custom slash commands, you standardize your team’s processes, reduce errors, and let Claude handle the mechanical parts of software development while you focus on the creative decisions.

Start small: pick your most repetitive task, write a skill for it, and iterate. Once you experience the productivity boost of a well-crafted skill, you will want to create them for every part of your workflow.

Ready to level up your Claude Code setup? Check out our complete Claude Code guide for more tips on getting the most out of AI-assisted development. If you want to go beyond skills and build fully custom AI agents, see our Claude Code Agent SDK guide. And for details on which plan best supports your workflow, read our Claude Code pricing guide.