Claude Code Skills: The Complete Setup and Creation Guide

This Claude Code skills setup guide teaches you everything about installing, creating, and managing skills-the reusable instruction sets that make Claude work your way, automatically.

You've been using Claude Code for a while. You've written the same prompt five times this week. You've explained your company's formatting rules again. You've re-typed your code review checklist for the third PR today.

There's a better way.

Skills are how you teach Claude to work your way-once. Instead of repeating yourself, you create a skill that captures your process. Claude applies it automatically whenever relevant.

This Claude Code skills tutorial walks you through everything: installing pre-built skills, creating your own, and organizing skills for your team.

---

What Are Skills?

Claude Code skills are reusable instruction sets stored as markdown files (SKILL.md) that Claude follows automatically when relevant to your task. Skills let you define workflows once-brand voice guidelines, code review checklists, report formatting-and have Claude apply them automatically without re-explaining every time.

A skill is a set of instructions that Claude follows automatically when relevant to your task.

Think of skills as teaching Claude how you work:

• Your brand voice guidelines
• Your code review checklist
• Your report formatting template
• Your data cleaning process

Key characteristics:

• Persistent - Set them once, use them forever
• Automatic - Claude applies them when relevant (no need to invoke manually)
• Shareable - Export and share with teammates
• Stackable - Multiple skills can apply to the same task

Real Examples: What People Actually Build

Skills aren't just for developers. Here's what real users are doing:

Marketing & Content

• SEO Content Optimizer: "A full SEO workflow, equivalent to 2+ hours of junior writer time, packaged into a single Skill that delivers in minutes."
• Newsletter Repurposing: Transform one blog post into LinkedIn posts, Twitter threads, and email snippets-all matching your voice.
• Brand Voice Checker: Scan any content for off-brand language before publishing.

Internal Communications

• Status Reports: "A set of resources to help me write all kinds of internal communications using the formats my company likes-status reports, leadership updates, incident reports, project updates."
• Meeting Prep: Before client calls, automatically pull recent support tickets, usage metrics, and outstanding issues into a 2-minute briefing.

Finance & Operations

• Management Accounting: "Skills streamline our finance workflows. Claude processes multiple spreadsheets, catches anomalies, and generates reports using our procedures. What once took a day, we accomplish in an hour."
• Contract Review: Scan agreements for specific clauses, compare against your standard terms, flag items for legal review.

Writing & Research

• Brainstorm Headlines: Generate and critique headline alternatives for any piece.
• Research Assistant: Conduct supporting research, act as thesaurus, make SEO recommendations-one user reported "writing way more" as a result.

---

Skills vs. CLAUDE.md: Which Do You Need?

Before creating a skill, make sure you actually need one. Both skills and CLAUDE.md give Claude context-but they serve different purposes.

Rule of thumb: CLAUDE.md is what this project is. Skills are how to do things.

• CLAUDE.md = Project documentation that Claude reads. Lives in your repo, visible to everyone.
• Skills = Reusable workflows that Claude applies automatically. Can be personal or shared.

If you just need Claude to know about your tech stack or project structure, add it to CLAUDE.md. If you want Claude to do something a specific way every time, create a skill.

---

Where Skills Live

Skills can exist in two locations:

Personal Skills (Global)

~/.claude/skills/
├── brand-voice/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── weekly-report/
    └── SKILL.md

Personal skills apply everywhere you use Claude Code-any project, any folder.

Use personal skills for:

• Your individual preferences
• Workflows you use across multiple projects
• Personal productivity patterns

Project Skills (Local)

your-project/
├── .claude/
│   └── skills/
│       ├── pr-template/
│       │   └── SKILL.md
│       └── testing-standards/
│           └── SKILL.md
├── src/
└── package.json

Project skills apply only within that project folder and its subfolders.

Use project skills for:

• Team conventions specific to this codebase
• Project-specific templates and workflows
• Standards you want version-controlled with your code

---

Installing Pre-Built Skills

You don't need to create skills from scratch. We've curated a library of production-ready skills you can install in seconds.

Browse the Skills Library

Our Skills Library has skills organized by category:

Popular starting points:

• PDF Skill - Extract text, analyze contracts, summarize documents
• Frontend Design - Generate polished UI components and pages
• DOCX Skill - Create and edit Word documents with proper formatting
• Skill Creator - Let Claude build custom skills for you

Each skill page includes installation instructions, example prompts, and use cases.

Method 1: Direct Download

The simplest approach-download the SKILL.md file directly. Each skill in our Skills Library shows the exact command.

Terminal

$mkdir -p ~/.claude/skills/pdf

$curl -o ~/.claude/skills/pdf/SKILL.md https://raw.githubusercontent.com/anthropics/skills/main/skills/pdf/SKILL.md

Downloaded: SKILL.md

Now Claude can analyze PDFs. Test it:

claude - ~/Documents

$claude

You: Analyze the contract in proposal.pdf and find the termination clause

Using skill: PDF

I found the termination clause on page 12, section 8.2...

Method 2: Plugin Marketplace

Claude Code has a plugin system for installing skill bundles:

claude - ~

$claude

You: /plugin marketplace add anthropics/skills

Added marketplace: anthropics/skills

You: /plugin install document-skills@anthropic-agent-skills

Installed: document-skills (includes pdf, docx, xlsx, pptx)

Method 3: Clone and Customize

For exploring or modifying skills:

Terminal

$git clone https://github.com/anthropics/skills.git ~/anthropic-skills

$cp -r ~/anthropic-skills/skills/pdf ~/.claude/skills/

Skill installed

---

Creating Your First Custom Skill

Pre-built skills are great, but the real power comes from creating your own. You have two paths: let Claude help you (easier) or write it yourself (more control).

The Easy Way: Use Skill Creator

Don't want to write SKILL.md files by hand? Use the Skill Creator skill to generate them through conversation.

claude - ~

You: Help me create a skill for my weekly status report

Using skill: Skill Creator

I'll help you create a status report skill. Let me ask a few questions:

1. What sections does your report typically include?

2. Who's the audience (manager, team, stakeholders)?

3. What format do you need (Slack, email, document)?

Answer Claude's questions, and it generates a complete SKILL.md file tailored to your workflow.

Install Skill Creator:

Terminal

$mkdir -p ~/.claude/skills/skill-creator

$curl -o ~/.claude/skills/skill-creator/SKILL.md https://raw.githubusercontent.com/anthropics/skills/main/skills/skill-creator/SKILL.md

Voice-First Skill Creation

Here's an unconventional tip from power users: use voice to create skills faster.

The setup:

• Use a local whisper model (or any speech-to-text)
• Speak your workflow description instead of typing

Why it works:

1. Faster than typing - Describing a workflow verbally takes 2 minutes; writing it takes 10
2. More natural capture - You explain processes more completely when talking than when writing
3. Claude handles transcription errors - Mistranscriptions like "ExcelElanishMark" get interpreted correctly as "exclamation mark" from context

claude - ~

You: [Speaking via voice input] Help me create a skill for my weekly report. Every Friday I pull data from our dashboard, summarize the key metrics, highlight wins and blockers, and send it to my manager in Slack. The format should be bullet points, no more than 300 words, and I always include next week's priorities at the end.

Using skill: Skill Creator

Based on your description, here's a SKILL.md for your weekly report...

This approach is especially valuable for non-technical users who find writing structured documents tedious. Speak your workflow, let Claude structure it.

The Spec-Based Approach: Let Claude Interview You

Instead of writing your SKILL.md from scratch, let Claude interview you about your workflow first. This technique comes from developers who build large features with Claude Code.

How it works:

claude - ~

You: I want to create a skill for my weekly status report. Interview me about my workflow first-ask questions about what I need, then generate the SKILL.md.

Claude: I'll help you create a comprehensive status report skill. Let me understand your workflow:

1. Who reads these reports? (manager, team, stakeholders, executives?)

2. What sections do you typically include?

3. Where does the source data come from? (project board, git commits, notes?)

4. What format do you deliver in? (Slack, email, doc?)

5. What's your biggest pain point with the current process?

After answering these questions, Claude generates a SKILL.md that captures your actual workflow-not a generic template.

Why this works:

• Surfaces requirements you'd forget to write down
• Captures edge cases through follow-up questions
• Produces skills that match how you actually work
• Takes 5 minutes of conversation instead of 30 minutes of writing

Creating Skills Manually

Want full control? Here's how to write skills yourself.

The Anatomy of a Skill

At minimum, a skill is a folder containing a SKILL.md file:

my-skill/
└── SKILL.md

The SKILL.md file has two parts:

1. YAML frontmatter - Metadata that Claude reads first
2. Markdown content - Instructions Claude follows

Here's the simplest possible skill:

---
name: friendly-tone
description: Makes all responses warm and conversational
---

# Friendly Tone

When responding:
- Use "you" and "I" instead of formal language
- Add occasional encouragement ("Great question!")
- Keep sentences short and scannable
- Avoid corporate jargon

That's it. This skill will activate whenever you ask Claude to write something where tone matters.

Step-by-Step: Build a Code Review Skill

Let's create something more useful-a code review skill that applies your team's standards.

Step 1: Create the skill folder

Terminal

$mkdir -p ~/.claude/skills/code-review

Step 2: Create SKILL.md with your requirements

---
name: code-review
description: Reviews code changes for security, tests, documentation, and style following team standards
---

# Code Review Checklist

When reviewing code, check each of these areas systematically.

## Security
- [ ] No hardcoded secrets, API keys, or credentials
- [ ] User input is validated and sanitized
- [ ] SQL queries use parameterized statements
- [ ] Authentication checks are in place for protected routes

## Testing
- [ ] New functionality has corresponding tests
- [ ] Edge cases are covered (null, empty, boundary values)
- [ ] Tests are independent and don't rely on execution order

## Documentation
- [ ] Public functions have clear docstrings
- [ ] Complex logic has inline comments explaining "why"
- [ ] README updated if behavior changes

## Code Style
- [ ] Follows existing patterns in the codebase
- [ ] No commented-out code left behind
- [ ] Variable names are descriptive
- [ ] Functions do one thing well

## Output Format

Provide feedback as a markdown checklist with:
- ✅ for passing items
- ❌ for issues with specific line numbers and suggestions
- ⚠️ for minor concerns or suggestions

End with a summary: "Ready to merge" or "Needs changes: [list]"

Step 3: Save and test

Save this file to ~/.claude/skills/code-review/SKILL.md, then:

claude - ~/my-project

$claude

You: Review the changes in my last commit

Using skill: code-review

## Code Review: commit abc123

### Security

✅ No hardcoded secrets detected

❌ Line 47: User input passed directly to SQL query...

Claude automatically used your code review skill because the task matched the skill's description.

Common Mistakes to Avoid

These gotchas trip up even experienced users. Learn from the community's hard-won lessons.

Prettier Breaking Your SKILL.md

Prettier or other formatters reformat your YAML frontmatter, breaking Claude Code's parsing. Skills silently don't appear.

Fix: Add a prettier-ignore comment:

<!-- prettier-ignore -->
---
name: my-skill
description: Reviews code for security vulnerabilities and suggests fixes
---

Or keep descriptions on a single line. Multi-line descriptions are the usual culprit.

The Silent Character Limit

Skill descriptions exceeding 15,000 characters fail silently. No warning, no error-skills just stop working.

Fix: Set a higher budget or keep SKILL.md lean:

export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000

Vague Descriptions That Never Trigger

Generic descriptions don't give Claude enough signal to activate your skill.

# Won't trigger reliably
description: Helps with writing

# Triggers consistently
description: Applies Acme Corp brand voice when writing customer-facing emails, documentation, blog posts, and marketing copy

Include specific trigger terms-the types of tasks, content, or contexts where this skill applies.

Deeply Nested File References

Claude partially reads files when references are nested too deep (A → B → C → D). Keep references flat-link directly from SKILL.md to reference files.

---

Making Skills Work Reliably

Here's something the documentation doesn't emphasize: skills are supposed to activate automatically, but they often don't.

Community testing found that with basic setup, skills activate only about 20% of the time-essentially a coin flip. This section covers techniques that dramatically improve activation rates.

Why Skills Don't Activate

Claude decides whether to use a skill based on matching your request against skill descriptions. This semantic matching is imperfect. Without reinforcement, Claude often "blags its way through" with general knowledge instead of loading your carefully crafted skill.

The Forced Evaluation Pattern (84% Success)

This technique forces Claude to explicitly evaluate each skill before proceeding. It's verbose, but it works.

When you want to ensure skills activate, include this in your prompt:

Before responding, evaluate each available skill:
1. List each skill with YES/NO and brief reasoning
2. Activate relevant skills using the Skill() tool immediately
3. Only then proceed with the task

CRITICAL: The evaluation is worthless unless you ACTIVATE the skills.

Why it works: Forcing Claude to "show its work" before proceeding makes it harder to skip skill activation. The explicit evaluation step creates a commitment mechanism.

The Explicit Mention Approach

Simpler than forced evaluation-just mention the skill by name:

Use my code-review skill to review these changes.

vs.

Review these changes.

The first activates the skill reliably. The second might or might not.

Validation Scripts in Skills

For critical workflows, add validation to your skills:

## Validation

After completing the task, verify:
1. Run the validation script: `./validate-output.sh`
2. If validation fails, report specific errors
3. Fix issues and re-validate

Make validation verbose. Include specific error messages like:
"Field 'signature_date' not found. Available fields: customer_name,
order_total, signature_date_signed"

Verbose validation helps Claude self-correct when skills partially activate or miss instructions.

Troubleshooting

Skill Not Being Used

Symptoms: Claude ignores your skill even when relevant.

Fixes:

1. Check the description field-is it specific enough?
2. Verify the skill is in the right location (~/.claude/skills/ or .claude/skills/)
3. Check that SKILL.md has valid YAML frontmatter
4. Try explicitly mentioning the skill: "Use my code-review skill to..."

Skill Loading but Wrong Behavior

Symptoms: Claude uses the skill but doesn't follow all instructions.

Fixes:

1. Simplify instructions-shorter and clearer beats comprehensive
2. Add examples of good output
3. Put the most important instructions first
4. Use headings to organize sections Claude can reference

Conflicting Skills

Symptoms: Two skills seem to fight each other.

Fixes:

1. Make descriptions more specific so only one applies
2. Combine related skills into one
3. Use conditional sections: "When doing X, follow these rules..."

---

Advanced Patterns

Once you're comfortable with basic skills, these patterns unlock more power.

Multi-File Skills

Skills can reference additional files. Put them in the same folder:

brand-voice/
├── SKILL.md
├── examples.md
├── words-we-use.md
└── words-we-avoid.md

In your SKILL.md, reference them:

---
name: brand-voice
description: Applies company brand voice guidelines to all written content
---

# Brand Voice Guidelines

Apply our brand voice to all content. When writing:

1. Check `words-we-use.md` for preferred terminology
2. Check `words-we-avoid.md` for banned words
3. See `examples.md` for before/after comparisons

## Core Principles
...

Claude loads the additional files only when needed, keeping things fast.

Skills with Scripts

Skills can include executable code. This is powerful for automation:

deploy-checker/
├── SKILL.md
├── check-tests.sh
└── validate-env.sh

---
name: deploy-checker
description: Validates deployment readiness by running pre-flight checks
---

# Deployment Readiness Check

Before any deployment, run these validation scripts:

1. Run `./check-tests.sh` to verify all tests pass
2. Run `./validate-env.sh` to check environment variables
3. Report any failures with specific remediation steps

Conditional Instructions

Make skills smarter with conditional logic:

---
name: response-format
description: Formats responses appropriately for different contexts
---

# Response Formatting

Adjust format based on context:

## For Slack messages
- Keep under 300 words
- Use emoji sparingly (1-2 max)
- Break into short paragraphs

## For documentation
- Use full sentences
- Include code examples
- Add cross-references to related docs

## For email
- Start with the main point
- Use bullet points for lists
- End with clear next steps

Skill Stacking: Combining Multiple Skills

Skills are composable-Claude can use several skills together on a single task. But there are limits.

How skill stacking works:

Claude scans all available skills, evaluates relevance, and loads the ones that apply. For a task like "write a customer email about our new feature," Claude might activate:

• Your brand-voice skill
• Your email-format skill
• Your product-knowledge skill

The reality check:

Community testing reveals important constraints:

One user reported: "Watching the thinking bubble for five minutes while Claude juggled three instruction sets. It worked, but the quality dipped."

Best practices for stacking:

1. Design complementary skills that chain rather than overlap
2. Keep each skill focused on one domain
3. Avoid redundant instructions across skills
4. Test combinations before relying on them for critical work

# Good: Complementary skills
- brand-voice (how to write)
- email-format (structure)
- customer-data (what to reference)

# Problematic: Overlapping skills
- writing-style-a (formal tone)
- writing-style-b (casual tone)
- general-writing (mixed guidance)

---

Long Projects & Teams

These patterns help when you're working on multi-day projects or collaborating with others.

The HANDOFF.md Pattern for Long Projects

Skills work within a single session, but what about multi-day projects? Here's a pattern from power users that preserves context across sessions.

The problem: You're building something complex over several days. Each new Claude session starts fresh-you lose the context of what you've built, what's working, and what's next.

The solution: Before ending a session, create a HANDOFF.md that summarizes the state:

# Project Handoff: Auth System Refactor

## What's Done
- Migrated user model to new schema
- Updated login endpoint
- Tests passing for basic auth flow

## Current State
- Working on: Password reset flow
- Blocked on: Email service integration (need API key)
- Last file edited: src/auth/reset.ts

## Next Steps
1. Get email API key from team
2. Implement reset token generation
3. Build reset confirmation page

## Key Decisions Made
- Using JWT for reset tokens (not database sessions)
- 24-hour expiry on reset links
- Rate limiting: 3 requests per hour per email

How to use it:

1. End each session by asking Claude: "Create a HANDOFF.md summarizing our progress"
2. Start the next session by pointing Claude at the handoff: "Read HANDOFF.md and continue from where we left off"

This preserves institutional knowledge without burning tokens on context that might get compacted away.

Organizing Skills for Teams

When working with teams, organization matters.

Project Skills for Team Standards

Put shared standards in your project's .claude/skills/ folder:

your-project/
├── .claude/
│   └── skills/
│       ├── api-design/
│       │   └── SKILL.md
│       ├── test-patterns/
│       │   └── SKILL.md
│       └── commit-format/
│           └── SKILL.md
├── src/
└── README.md

Commit these to git. Now everyone who works on the project gets the same skills automatically.

Naming Conventions

Use consistent naming to keep things organized:

Documentation Template

Include this in your skill for maintainability:

---
name: my-skill
description: What this skill does and when Claude should use it
---

# Skill Name

## Purpose
Brief description of what this skill accomplishes.

## When This Applies
- Trigger condition 1
- Trigger condition 2

## Instructions
[Your actual instructions here]

## Examples
[Good input/output examples]

## Maintainer
Created by: [Name]
Last updated: [Date]
Questions: [Contact]

Best Practices from Anthropic

Anthropic's engineering team shares these guidelines for effective skills:

1. Start with Evaluation

Before building a skill, test Claude on the task without one. Note where it falls short. Build skills to fill those specific gaps-not to over-specify things Claude already handles well.

2. Write Clear Descriptions

The description field is critical. Claude uses it to decide when to apply the skill. Be specific about triggers.

3. Structure for Scale

If your SKILL.md gets long (over ~500 lines), split it:

complex-skill/
├── SKILL.md           # Core instructions, references other files
├── examples.md        # Detailed examples
├── edge-cases.md      # Special handling
└── templates/
    ├── format-a.md
    └── format-b.md

4. Iterate Based on Usage

Skills improve with feedback. When Claude misapplies a skill or misses something:

1. Note the specific failure
2. Add clarifying instructions
3. Test again

Ask Claude: "What would have helped you handle that better?" and update the skill accordingly.

5. Keep Instructions Claude-Centric

Write instructions as if briefing a capable colleague:

# Good
Check for SQL injection vulnerabilities. Flag any query where user input
is concatenated directly into the SQL string.

# Less effective
SQL INJECTION IS BAD. NEVER ALLOW IT. CHECK EVERYTHING CAREFULLY!!!

Claude responds better to clear, professional instructions than to emphasized warnings.

---

Quick Reference

Skill File Structure

---
name: skill-name          # Required: lowercase with hyphens
description: When to use  # Required: triggers skill matching
---

# Your Instructions Here

Write clear, direct instructions that Claude will follow.

File Locations

Installation Commands

# Direct download
curl -o ~/.claude/skills/NAME/SKILL.md [URL]

# Plugin marketplace
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

How Skills Work Under the Hood

Skills use a design pattern called progressive disclosure:

You could have a skill with 50 pages of documentation. Claude doesn't load all 50 pages upfront. It reads the name and description, decides if it's relevant, then loads more only when needed.

This means:

• You can create very detailed skills without context bloat
• Claude stays fast because it loads just-in-time
• Skills can reference entire folders of examples, templates, and scripts

---

What's Next?

You now know how to install and create Claude Code skills. Here's how to keep building:

Immediate actions:

1. Install one pre-built skill from the Skills Library
2. Create one simple skill for something you repeat often
3. Try the Skill Creator for a guided experience

Keep learning:

• Agents, Skills, Hooks & MCP Explained - Understand how skills fit with other Claude Code concepts
• Claude Code Plan Mode Tutorial - The 5-minute habit that saves hours
• Claude Code Context Management - Why results degrade and how to fix it
• Skills Library - Browse all available pre-built skills
• Ultimate Beginner's Guide - Full Claude Code fundamentals

Official resources:

• Anthropic Skills Repository - Official pre-built skills
• Claude Code Documentation - Technical reference
• Agent Skills Engineering Blog - Design principles deep dive

---

Ready to Master Claude Code?

Skills are just one part of becoming a Claude Code power user. In AI Essentials for Business Leaders, we go hands-on with skills, hooks, MCP, and more.

You'll leave with:

• Custom skills built for your specific workflows
• Practical experience with the full Claude Code toolkit
• A network of professionals on the same journey

Reserve Your Spot →