Claude Skills

Creating Custom Skills in Claude Code: A Complete Guide

Skills are one of Claude Code's most powerful features — they let you teach Claude how to handle specific tasks in a consistent, repeatable way. Whether you're writing PR descriptions, conducting code reviews, or generating documentation, skills ensure Claude follows your exact process every time.

In this guide, we'll build a personal skill that teaches Claude how to write pull request descriptions in a consistent format. Since it's a personal skill, it lives in your home directory and works across all your projects.

What Are Skills?

Skills are reusable instruction sets stored as markdown files. They tell Claude:

When to activate (through the description field)
What to do (through the instruction content)
How to do it (through specific steps and formatting rules)

Think of skills as templates for common workflows. Once created, they ensure consistency across your team and save you from repeating the same instructions in every conversation.

Building Your First Skill: PR Descriptions

Let's create a skill that writes pull request descriptions in a standardized format.

Step 1: Create the Skill Directory

First, create a directory for your skill inside the skills folder. The directory name should match your skill name:

mkdir -p ~/.claude/skills/pr-description

Step 2: Write the SKILL.md File

Create a SKILL.md file inside that directory. The file has two parts separated by frontmatter dashes:

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR, writing a PR, or when the user asks to summarize changes for a pull request.
---

When writing a PR description:

1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

Breaking it down:

name: Identifies your skill uniquely
description: The matching criteria — tells Claude when to use this skill
Instructions: Everything after the second set of dashes — the actual steps Claude follows

Testing Your Skill

Claude Code loads skills at startup, so restart your session after creating one. You can verify it's available by checking the available skills list.

You should see your skill listed. To test it:

Make some changes on a branch
Say something like "write a PR description for my changes"
Claude will indicate it's using the PR description skill
It will check your diff and write a description following your template — same format every time

How Skill Matching Works

Understanding the matching process helps you write better skill descriptions.

When Claude Code starts, it scans four locations for skills but only loads the name and description — not the full content. This is an important detail for performance.

When you send a request, Claude compares your message against the descriptions of all available skills. For example, "explain what this function does" would match a skill described as "explain code with visual diagrams" because the intent overlaps.

Once a match is found, Claude asks you to confirm loading the skill. This confirmation step keeps you aware of what context Claude is pulling in. After you confirm, Claude reads the complete SKILL.md file and follows its instructions.

Skill Priority Hierarchy

If you clone a repository that has a skill with the same name as one of your personal skills, which one wins? There's a clear priority order:

Enterprise — managed settings, highest priority
Personal — your home directory (~/.claude/skills)
Project — the .claude/skills directory inside a repository
Plugins — installed plugins, lowest priority

This hierarchy lets organizations enforce standards through enterprise skills while still allowing individual customization. If your company has an enterprise "code-review" skill and you create a personal "code-review" skill with the same name, the enterprise version takes precedence.

Best practice: Use descriptive names to avoid conflicts. Instead of just "review," use something like "frontend-review" or "backend-review."

Updating and Removing Skills

To update a skill: Edit its SKILL.md file
To remove a skill: Delete its directory
Important: Restart Claude Code after any changes for them to take effect

Real-World Skill Examples

Code Review Skill

---
name: security-review
description: Performs security-focused code reviews. Use when reviewing code for security vulnerabilities or when the user asks for a security audit.
---

When performing a security review:

1. Check for common vulnerabilities:
   - SQL injection risks
   - XSS vulnerabilities
   - Authentication/authorization issues
   - Sensitive data exposure
   - CSRF protection

2. Review dependencies for known CVEs

3. Format findings as:
   - **Critical**: Immediate security risks
   - **High**: Significant vulnerabilities
   - **Medium**: Potential issues
   - **Low**: Best practice improvements

Documentation Generator

---
name: api-docs
description: Generates API documentation from code. Use when documenting endpoints, creating API references, or when the user asks to document an API.
---

When generating API documentation:

1. Identify all endpoints in the file
2. For each endpoint, document:
   - HTTP method and path
   - Description of what it does
   - Request parameters (query, path, body)
   - Response format with example
   - Possible error codes
   - Authentication requirements

3. Use OpenAPI/Swagger format
4. Include example requests using curl

Best Practices for Writing Skills

1. Write Clear Descriptions

The description is your matching criteria. Be specific about when the skill should activate:

✅ Good: "Writes unit tests for React components. Use when creating tests, writing test files, or when the user asks to test a component."

❌ Bad: "Helps with testing"

2. Use Step-by-Step Instructions

Break down complex tasks into numbered steps. This ensures consistency and makes skills easier to maintain.

3. Include Format Examples

Show Claude exactly what the output should look like. Use markdown formatting, code blocks, and templates.

4. Specify Tool Usage

If your skill needs specific tools (like git diff), mention them explicitly in the instructions.

5. Keep Skills Focused

One skill = one task. Don't create a "do-everything" skill. Instead, create multiple focused skills that can work together.

Skill Locations Explained

Personal Skills (`~/.claude/skills`)

Available across all projects
Survive project deletion
Perfect for your personal workflow preferences
Example: Your preferred PR description format

Project Skills (`.claude/skills`)

Committed to version control
Shared with the entire team
Project-specific conventions
Example: Project-specific code review checklist

Enterprise Skills

Managed by your organization
Enforced across all users
Cannot be overridden
Example: Company-wide security review standards

Plugin Skills

Installed from the plugin marketplace
Lowest priority
Can be overridden by any other skill type
Example: Community-contributed skills

Troubleshooting Common Issues

Skill Not Appearing

Verify the directory structure: ~/.claude/skills/skill-name/SKILL.md
Check the frontmatter format (three dashes, name and description fields)
Restart Claude Code

Skill Not Matching

Review your description — is it specific enough?
Try more explicit trigger phrases in the description
Test with different phrasings of your request

Conflicting Skills

Check the priority hierarchy
Rename skills to be more specific
Use claude skills list to see which version is loaded

Lesson Reflection

Before moving on, consider these questions:

What's one task in your daily workflow that you could turn into a skill right now? Think about repetitive tasks where you find yourself giving Claude the same instructions over and over.

How might the priority hierarchy affect your team's skill management strategy? Would you rely more on personal or project-level skills? How would you balance individual preferences with team standards?

What's Next

In the next lesson, you'll learn about advanced configuration options including:

Metadata fields for better skill organization
Tool restrictions with allowed-tools
Progressive disclosure for complex skills
Multi-file skill organization
Conditional logic and dynamic content

Skills transform Claude Code from a helpful assistant into a personalized development partner that understands your exact workflow. Start with one simple skill today, and gradually build a library that captures your team's best practices.

Ready to create your first skill? Start with something simple like PR descriptions or commit messages, then expand from there. The best skills are the ones you'll actually use every day.