The Complete Guide to Claude Code Skills: Everything You Need to Know

Claude Code has fundamentally changed how developers work with AI. But the real power isn't in the base tool—it's in skills. Skills are modular capabilities that extend Claude Code's functionality, turning a general-purpose AI assistant into a domain-specific expert.

This guide covers everything you need to know about Claude Code skills: what they are, how they work, how to install them, and how to create your own.

What Are Claude Code Skills?

Skills are reusable instructions and capabilities that customize Claude Code's behavior for specific tasks. Think of them like browser extensions for your AI coding assistant—they add specialized functionality without modifying the core tool.

A skill might:

• Define a specific workflow for code reviews
• Establish coding conventions for your project
• Create custom commands for common tasks
• Set up agents for specialized domains
• Integrate external tools via MCP servers

The beauty of skills is their modularity. You can mix and match skills to create the exact development environment you need.

The Four Types of Claude Code Skills

Claude Code supports four distinct skill types, each serving different purposes:

1. Commands

Commands are slash-triggered actions that execute specific workflows. They're the most common skill type and the easiest to create.

# /commit

Create a git commit following conventional commit standards.

## Instructions

1. Run `git status` to see changed files
2. Run `git diff --staged` to analyze staged changes
3. Generate a conventional commit message
4. Create the commit with the message

Commands are invoked with a slash: /commit, /review, /deploy.

When to use commands:

• Repetitive multi-step workflows
• Tasks that need consistent execution
• Actions triggered by user intent

2. Skills (Passive Context)

Unlike commands, skills provide passive context that's always available. They don't require invocation—they shape how Claude Code behaves by default.

# Project Coding Standards

## TypeScript Conventions

- Use strict TypeScript (no `any`)
- Prefer interfaces over types
- Use barrel exports for modules

## File Organization

- Components in `/components`
- Hooks in `/hooks`
- Utils in `/lib`

Skills are automatically loaded based on project context and influence Claude Code's responses without explicit invocation.

When to use skills:

• Project-wide coding standards
• Domain knowledge that should always be available
• Context that shapes behavior across all interactions

3. Agents

Agents are specialized personas that can be triggered for specific domains. They have their own system prompts and can be configured with specific tools and behaviors.

# Security Auditor Agent

You are a security-focused code reviewer. Your primary concern is identifying vulnerabilities, security anti-patterns, and potential attack vectors.

## Focus Areas

- SQL injection
- XSS vulnerabilities
- Authentication flaws
- Authorization bypasses
- Sensitive data exposure

## Behavior

Always explain the risk level (Critical/High/Medium/Low) and provide remediation guidance.

Agents can be invoked explicitly or triggered automatically based on context.

When to use agents:

• Specialized domain expertise
• Tasks requiring a specific persona
• Complex multi-turn interactions

4. Plugins

Plugins are packages that bundle multiple skills, commands, agents, and MCP integrations together. They're the most comprehensive skill type.

{
  "name": "fullstack-developer",
  "version": "1.0.0",
  "description": "Complete fullstack development toolkit",
  "commands": ["commands/*.md"],
  "skills": ["skills/*.md"],
  "agents": ["agents/*.md"],
  "mcp": {
    "servers": {
      "postgres": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"]
      }
    }
  }
}

Plugins provide a cohesive experience for specific development scenarios.

When to use plugins:

• Comprehensive toolkits for specific stacks
• Distributing multiple related skills
• Complex integrations requiring MCP servers

Installing Skills

Method 1: Manual Installation

The simplest approach is creating a .claude/ directory in your project:

mkdir -p .claude/commands
mkdir -p .claude/skills

Then add your skill files:

# Create a command
cat > .claude/commands/test.md << 'EOF'
# /test

Run the test suite with coverage reporting.

## Steps

1. Run `npm test -- --coverage`
2. Report any failing tests
3. Summarize coverage metrics
EOF

Method 2: Using CLAUDE.md

The CLAUDE.md file in your project root is automatically loaded by Claude Code. It's the primary way to provide project context:

# Project: E-commerce Platform

## Tech Stack
- Next.js 14 with App Router
- Prisma with PostgreSQL
- Tailwind CSS
- Stripe for payments

## Coding Standards
- Use Server Components by default
- Client Components only when needed
- Prefer Server Actions over API routes
- Always use TypeScript strict mode

## Common Commands
- `npm run dev` - Start development server
- `npm run db:push` - Push schema changes
- `npm run db:seed` - Seed database

Method 3: Global Installation

For skills you want available across all projects, use the global Claude directory:

# macOS/Linux
~/.claude/commands/
~/.claude/skills/

# Windows
%USERPROFILE%\.claude\commands\
%USERPROFILE%\.claude\skills\

Method 4: Plugin Installation

Plugins can be installed from GitHub:

# Clone the plugin
git clone https://github.com/example/claude-plugin ~/.claude/plugins/example-plugin

# Or add to your project
git submodule add https://github.com/example/claude-plugin .claude/plugins/example

The SKILL.md Format

The standard format for Claude Code skills uses Markdown with specific conventions:

Basic Structure

---
name: "skill-name"
description: "What this skill does"
version: "1.0.0"
author: "Your Name"
tags: ["category", "domain"]
---

# Skill Title

Brief description of what this skill provides.

## Instructions

Detailed instructions for Claude Code to follow.

## Examples

Show example usage and expected outputs.

## Configuration

Any configuration options or environment variables.

Frontmatter Fields

Writing Effective Instructions

The instructions section is where your skill's value lives. Follow these principles:

1. Be Specific, Not Vague

# Bad
Review the code and suggest improvements.

# Good
Review the code for:
1. TypeScript type safety issues
2. Missing error handling
3. Performance anti-patterns (N+1 queries, unnecessary re-renders)
4. Security vulnerabilities (XSS, injection)

For each issue found, provide:
- Location (file:line)
- Severity (Critical/High/Medium/Low)
- Explanation of the problem
- Suggested fix with code example

2. Include Context

# Context

This project uses:
- Next.js 14 App Router
- Server Components by default
- Prisma for database access
- Zod for validation

When suggesting code, ensure compatibility with these technologies.

3. Define Output Format

# Output Format

Respond with a structured review:

## Summary
One paragraph overview of code quality.

## Issues Found
List each issue with severity badge.

## Recommendations
Prioritized list of improvements.

## Code Snippets
Any suggested code changes.

Creating Your First Custom Skill

Let's build a practical skill: a PR description generator.

Step 1: Create the File

mkdir -p .claude/commands
touch .claude/commands/pr-description.md

Step 2: Write the Skill

---
name: "pr-description"
description: "Generate comprehensive PR descriptions from git diff"
version: "1.0.0"
tags: ["git", "pr", "documentation"]
---

# /pr-description

Generate a well-structured pull request description based on the current branch's changes.

## Instructions

1. Get the base branch (usually `main` or `master`)
2. Run `git log main..HEAD --oneline` to see commits
3. Run `git diff main...HEAD` to see all changes
4. Analyze the changes and generate a PR description

## PR Description Template

### Summary
Brief one-line description of what this PR does.

### Changes Made
- Bullet points of specific changes
- Group by category (Features, Fixes, Refactoring, etc.)

### Testing Done
- How the changes were tested
- Any new tests added

### Screenshots (if applicable)
Describe any UI changes.

### Breaking Changes
List any breaking changes or migration steps needed.

### Related Issues
Link to related issues: Fixes #XX, Relates to #YY

## Output

Generate the PR description in Markdown format, ready to paste into GitHub.

Step 3: Test the Skill

claude
> /pr-description

Advanced Skill Patterns

Conditional Logic

Skills can include conditional instructions:

# /deploy

Deploy the application to the specified environment.

## Instructions

1. Determine the target environment from user input
2. If production:
   - Require explicit confirmation
   - Run full test suite first
   - Create a git tag
3. If staging:
   - Run smoke tests only
   - No tag required
4. Execute deployment command for the environment

Tool Integration

Skills can specify which tools to use:

# /analyze-bundle

Analyze the JavaScript bundle size.

## Tools Required

- Bash (for running build commands)
- Read (for analyzing output files)

## Instructions

1. Run `npm run build`
2. Read the build output for bundle sizes
3. Identify the largest chunks
4. Suggest optimization strategies

Chaining Skills

Skills can reference other skills:

# /ship

Complete workflow: test, build, and deploy.

## Instructions

1. First, execute the /test command
2. If tests pass, execute /build
3. If build succeeds, execute /deploy staging
4. Report final status

Skill Organization Best Practices

Directory Structure

.claude/
├── commands/           # Slash commands
│   ├── commit.md
│   ├── review.md
│   └── deploy.md
├── skills/             # Passive context
│   ├── coding-standards.md
│   └── architecture.md
├── agents/             # Specialized personas
│   ├── security-auditor.md
│   └── performance-optimizer.md
└── plugins/            # External plugins
    └── example-plugin/

Naming Conventions

• Use kebab-case for file names: code-review.md
• Use descriptive names: typescript-strict-mode.md not ts-rules.md
• Prefix commands with the action: generate-, analyze-, create-

Documentation

Include a README in your .claude/ directory:

# Project Claude Code Skills

## Commands Available

| Command | Description |
|---------|-------------|
| /commit | Create conventional commits |
| /review | Code review current changes |
| /deploy | Deploy to environment |

## Skills Loaded

- `coding-standards.md` - TypeScript conventions
- `architecture.md` - Project architecture guide

## Setup

Copy `.env.example` to `.env` and configure.

Sharing and Distribution

GitHub Repositories

The most common way to share skills:

# Create a skills repository
gh repo create my-claude-skills --public

# Add your skills
cp -r .claude/* my-claude-skills/
cd my-claude-skills
git add . && git commit -m "Initial skills"
git push

Others can clone or submodule your skills.

AI Skill Market

Submit your skills to the AI Skill Market for discovery:

1. Ensure your skill has complete metadata
2. Provide clear documentation
3. Include example usage
4. Submit via the marketplace submission form

Versioning

Use semantic versioning for your skills:

• Major (1.0.0 → 2.0.0): Breaking changes
• Minor (1.0.0 → 1.1.0): New features, backward compatible
• Patch (1.0.0 → 1.0.1): Bug fixes

Common Skill Categories

Development Workflows

• Git operations (commit, PR, branch management)
• Code review automation
• Documentation generation
• Testing workflows

Code Quality

• Linting and formatting
• Security auditing
• Performance analysis
• Accessibility checking

Domain-Specific

• Frontend frameworks (React, Vue, Angular)
• Backend frameworks (Express, FastAPI, Rails)
• Infrastructure (Docker, Kubernetes, Terraform)
• Databases (SQL optimization, migrations)

Project Management

• Issue creation
• Sprint planning
• Release notes generation
• Changelog management

Troubleshooting

Skill Not Loading

1. Check file location is correct (.claude/ directory)
2. Verify file extension is .md
3. Check for syntax errors in frontmatter
4. Restart Claude Code to reload skills

Skill Behavior Unexpected

1. Review the instructions for ambiguity
2. Add more specific guidance
3. Include examples of expected output
4. Test with different inputs

Conflicts Between Skills

1. Check for overlapping triggers
2. Use more specific naming
3. Adjust priority in skill metadata
4. Consider consolidating related skills

Conclusion

Claude Code skills transform a powerful AI assistant into your personalized development environment. By understanding the four skill types—commands, skills, agents, and plugins—you can create workflows that match exactly how you work.

Start simple: create one command that automates a task you do daily. Then expand. Before long, you'll have a comprehensive skill library that makes you dramatically more productive.

The best part? Skills are shareable. What you build can help other developers, and what others build can help you. That's the power of the skill ecosystem.

---

Ready to explore more? Check out our guide on Commands vs Skills vs Agents: Which to Build to decide what type of skill fits your needs.