Skills are one of the most powerful features of Claude Code, transforming how developers interact with AI-assisted coding. This guide covers what skills are, how they work, how to create them, and where to find community-contributed skills.

What Are Claude Code Skills?

Skills are structured packages of instructions, scripts, and resources that extend Claude’s capabilities for specialized tasks. Think of them as reusable expertise modules that teach Claude how to complete specific workflows in a repeatable way.

Unlike simple prompts, skills can include:

Step-by-step instructions
Executable scripts (Python, Bash, etc.)
Templates and reference documentation
Examples and assets

Skills are model-invoked, meaning Claude automatically decides when to use them based on context. When your request matches a skill’s description, Claude activates it without explicit instruction.

How Skills Affect Claude’s Behavior

Skills fundamentally change how Claude approaches tasks through several mechanisms.

Progressive Disclosure Architecture

Skills use a token-efficient design. During startup, only the name and description (~100 tokens each) load into the system prompt. When Claude determines a skill is relevant, it loads the full instructions (typically under 5k tokens). Bundled resources load only as needed.

This architecture means you can have dozens of skills installed without bloating your context window.

Context-Aware Activation

Claude analyzes your conversation, reads available skill descriptions, and activates matching skills automatically. This means asking “analyze this PDF” can trigger a PDF processing skill without you typing /pdf.

The magic happens in the description field. Claude uses this metadata to determine relevance, so a well-crafted description is essential for reliable auto-invocation.

Consistent, Repeatable Workflows

Instead of Claude improvising each time, skills provide standardized procedures. A /deploy skill ensures the same testing, building, and deployment steps run every time. This consistency is valuable for:

Team workflows that need standardization
Complex multi-step procedures
Operations with side effects where you want predictable behavior

Creating Custom Skills

Basic Structure

Every skill lives in a directory with a required SKILL.md file:

my-skill/
├── SKILL.md           # Required: main instructions
├── scripts/           # Optional: executable code
├── references/        # Optional: documentation
└── assets/            # Optional: templates, icons

The SKILL.md File

A skill file has two parts: YAML frontmatter and markdown content.

---
name: code-review
description: Perform thorough code review focusing on bugs, security, and best practices. Use when user asks for code review or PR feedback.
---

# Code Review Skill

## Purpose
Systematically review code for quality, security vulnerabilities, and adherence to best practices.

## Steps
1. Scan for security vulnerabilities (OWASP Top 10)
2. Check for logic errors and edge cases
3. Verify error handling
4. Assess code readability and maintainability
5. Suggest improvements with examples

## Output Format
Provide findings in priority order: Critical > High > Medium > Low

Required Frontmatter Fields

Field	Description	Constraints
`name`	Becomes the `/slash-command`	Max 64 chars, lowercase, letters/numbers/hyphens only
`description`	Tells Claude when to invoke	Max 200 chars, critical for auto-invocation

Optional Frontmatter Fields

---
name: deploy
description: Deploy application to production
disable-model-invocation: true  # User-only invocation
allowed-tools: ["Bash", "Read"]  # Restrict tool access
context: fork                     # Run in isolated subagent
---

Skill Locations

Skills can be placed in three locations. Higher priority wins when names conflict:

Enterprise: Managed by organization admins
Personal: ~/.claude/skills/ - applies to all your projects
Project: .claude/skills/ - project-specific skills

Plugin skills use a plugin-name:skill-name namespace, so they never conflict with other levels.

Step-by-Step: Creating a Security Analysis Skill

Let’s walk through creating a practical project-local skill that analyzes your code for security vulnerabilities. This skill will check for OWASP Top 10 issues, common vulnerabilities, and security anti-patterns.

Step 1: Create the Skill Directory

In your project root, create the skill structure:

mkdir -p .claude/skills/security-scan

Step 2: Create the SKILL.md File

Create .claude/skills/security-scan/SKILL.md with the following content:

---
name: security-scan
description: Scan codebase for security vulnerabilities including OWASP Top 10, injection flaws, authentication issues, and sensitive data exposure. Use when asked to check security, audit code, or find vulnerabilities.
---

# Security Analysis Skill

## Purpose
Perform comprehensive security analysis of the codebase, identifying vulnerabilities and providing actionable remediation guidance.

## Scope
Analyze code for:
- **Injection vulnerabilities**: SQL, NoSQL, OS command, LDAP injection
- **Authentication flaws**: Weak passwords, missing MFA, session issues
- **Sensitive data exposure**: Hardcoded secrets, unencrypted data, logging PII
- **XML/XXE vulnerabilities**: External entity processing risks
- **Access control issues**: Missing authorization, privilege escalation
- **Security misconfigurations**: Debug modes, default credentials, verbose errors
- **XSS vulnerabilities**: Reflected, stored, and DOM-based XSS
- **Insecure deserialization**: Untrusted data deserialization
- **Dependency vulnerabilities**: Known CVEs in packages
- **Insufficient logging**: Missing audit trails, error suppression

## Workflow

1. **Identify technology stack** - Determine languages, frameworks, and dependencies
2. **Scan for hardcoded secrets** - API keys, passwords, tokens in code
3. **Check input validation** - User input handling and sanitization
4. **Review authentication** - Login flows, session management, password policies
5. **Analyze data handling** - Encryption, storage, transmission security
6. **Examine dependencies** - Check package.json, requirements.txt, go.mod for known vulnerabilities
7. **Review API security** - Rate limiting, authentication, input validation

## Output Format

### Security Scan Report

**Risk Level**: Critical | High | Medium | Low

#### Critical Issues
- [File:Line] Issue description
  - **Impact**: What could happen
  - **Fix**: How to remediate

#### High Issues
...

#### Recommendations
1. Immediate actions
2. Short-term improvements
3. Long-term security posture

## Language-Specific Checks

### JavaScript/TypeScript
- Dynamic code execution patterns
- innerHTML assignments without sanitization
- Missing Content-Security-Policy
- Prototype pollution risks

### Python
- Pickle with untrusted data
- shell=True in subprocess calls
- SQL string concatenation
- Debug mode in production

### Go
- Unchecked errors
- Race conditions
- Unsafe pointer usage

Step 3: Add a Reference Checklist (Optional)

Create .claude/skills/security-scan/references/owasp-checklist.md:

# OWASP Top 10 Quick Reference

## A01:2021 - Broken Access Control
- [ ] Verify authorization on every request
- [ ] Deny by default
- [ ] Implement rate limiting

## A02:2021 - Cryptographic Failures
- [ ] No hardcoded secrets
- [ ] Strong encryption (AES-256, RSA-2048+)
- [ ] TLS 1.2+ for data in transit

## A03:2021 - Injection
- [ ] Parameterized queries
- [ ] Input validation
- [ ] Output encoding

## A04:2021 - Insecure Design
- [ ] Threat modeling performed
- [ ] Security requirements defined
- [ ] Secure development lifecycle

## A05:2021 - Security Misconfiguration
- [ ] No default credentials
- [ ] Error messages don't leak info
- [ ] Security headers configured

## A06:2021 - Vulnerable Components
- [ ] Dependencies up to date
- [ ] No known CVEs
- [ ] Minimal dependencies

## A07:2021 - Authentication Failures
- [ ] Strong password policy
- [ ] MFA available
- [ ] Secure session management

## A08:2021 - Software and Data Integrity
- [ ] Verify code/data integrity
- [ ] Secure CI/CD pipeline
- [ ] Signed updates

## A09:2021 - Security Logging Failures
- [ ] Log authentication events
- [ ] Log access control failures
- [ ] Tamper-evident logs

## A10:2021 - Server-Side Request Forgery
- [ ] Validate/sanitize URLs
- [ ] Allowlist destinations
- [ ] Disable redirects

Step 4: Test Your Skill

Run Claude Code in your project and test with these prompts:

# Explicit invocation
/security-scan

# Natural language (tests auto-invocation)
"Check this codebase for security issues"
"Are there any vulnerabilities in the authentication code?"
"Audit the API endpoints for security problems"

Step 5: Iterate and Improve

Based on results, refine your skill:

Add project-specific checks (your framework, your patterns)
Include known vulnerability patterns from past incidents
Add remediation templates for common issues

This security skill will now be available whenever you work in this project, helping catch vulnerabilities early in development.

Controlling Invocation Behavior

By default, both you and Claude can invoke any skill. You type /skill-name for explicit invocation, and Claude loads it automatically when relevant. Two frontmatter fields let you restrict this:

User-Only Invocation

disable-model-invocation: true

Only you can invoke the skill. Use this for workflows with side effects or that you want to control timing:

/commit - You don’t want Claude deciding to commit because your code looks ready
/deploy - Deployment should be an explicit decision
/send-slack-message - Outbound communication needs human approval

Claude-Only Invocation

user-invocable: false

Only Claude can invoke the skill. Use this for background knowledge that isn’t actionable as a command. A legacy-system-context skill explains how an old system works. Claude should know this when relevant, but /legacy-system-context isn’t a meaningful action for users to take.

Summary Table

Setting	Who Can Invoke	Use Case
Default	Both user & Claude	General skills
`disable-model-invocation: true`	User only	Dangerous operations, deployments
`user-invocable: false`	Claude only	Background context/knowledge

Best Practices

1. Write Precise Descriptions

The description is the primary trigger mechanism. Include both what the skill does and when to use it. Research shows that a WHEN + WHEN NOT pattern works well:

Bad:

description: "Helps with deployments"

Good:

description: "Deploy application to staging or production. Use when user asks to deploy, ship, or release code. Do NOT use for local development builds."

2. Keep Skills Focused

Create separate skills for different workflows. Multiple focused skills compose better than one monolithic skill.

Keep SKILL.md under 500 lines
Put detailed documentation in separate referenced files
One skill = one workflow

If you find yourself typing the same prompt repeatedly across multiple conversations, it’s time to create a skill.

3. Test with Varied Prompts

After creating a skill, test it with different phrasings to ensure:

It triggers when expected
It doesn’t trigger when it shouldn’t
The workflow produces correct results

4. Security Considerations

Never hardcode API keys or passwords in skill files
Review downloaded skills before enabling them
Use MCP connections for external service access
Validate any scripts you include

5. Manage Context Budget

Skill descriptions are loaded into context so Claude knows what’s available. If you have many skills, they may exceed the character budget (default 15,000 characters).

Run /context to check for warnings about excluded skills. To increase the limit, set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

Skill Types

Thinking about how you want to invoke a skill helps guide what to include:

Reference Skills

Add knowledge Claude applies to your current work: conventions, patterns, style guides, domain knowledge. This content runs inline so Claude can use it alongside your conversation context.

Task Skills

Give Claude step-by-step instructions for a specific action like deployments, commits, or code generation. These are often actions you want to invoke directly with /skill-name rather than letting Claude decide when to run them.

Forked Context Skills

Add context: fork to your frontmatter when you want a skill to run in isolation. The skill content becomes the prompt that drives a subagent. It won’t have access to your conversation history, which is useful for self-contained workflows.

Example: Creating a PR Review Skill

Here’s a complete example of a practical skill:

---
name: pr-review
description: Review pull request for code quality, security, and best practices. Use when asked to review a PR, check a merge request, or audit code changes.
disable-model-invocation: true
---

# Pull Request Review

## Prerequisites
- GitHub CLI (`gh`) authenticated
- PR number or URL provided

## Workflow

1. **Fetch PR details**
   ```bash
   gh pr view <PR_NUMBER> --json title,body,files
   gh pr diff <PR_NUMBER>

Review checklist
- Security vulnerabilities
- Breaking changes
- Test coverage
- Documentation updates
- Performance implications
Output format Provide structured feedback with line-specific comments.

Example Output

PR Review: Add user authentication

Critical

Line 45: SQL injection vulnerability in user lookup

Suggestions

Consider adding rate limiting to login endpoint
Add unit tests for edge cases


## Popular Skill Repositories

### Official

**[anthropics/skills](https://github.com/anthropics/skills)** - Anthropic's official skill repository, including a `skill-creator` skill that helps you build new skills. This is the authoritative source for skill patterns and best practices.

### Community Collections

| Repository | Description |
|------------|-------------|
| [ComposioHQ/awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) | Curated list with integration skills for 1000+ apps (Slack, GitHub, email) |
| [travisvn/awesome-claude-skills](https://github.com/travisvn/awesome-claude-skills) | Focused on Claude Code workflows and productivity |
| [VoltAgent/awesome-claude-skills](https://github.com/VoltAgent/awesome-claude-skills) | Includes security-focused skills from Trail of Bits (CodeQL, Semgrep) |
| [obra/superpowers](https://github.com/obra/superpowers) | 20+ battle-tested skills: TDD, debugging, brainstorming, planning |
| [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | Domain-specific expertise packages and subagents |
| [hesreallyhim/awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | Index of 75+ Claude Code repos across categories |

### Marketplace

**[SkillsMP.com](https://skillsmp.com/)** - Searchable marketplace with 71,000+ agent skills. Filter by category, author, and popularity. Compatible with Claude Code, Codex CLI, and ChatGPT.

## Skills vs Commands vs Subagents vs CLAUDE.md

Understanding when to use each customization option:

| Feature | Use Case |
|---------|----------|
| **Skills** | Auto-applied workflows with supporting files |
| **Slash Commands** | Explicit, repeatable terminal entry points |
| **Subagents** | Keep main context small; delegate exploration |
| **CLAUDE.md** | Short, always-true project conventions |

Note: Custom slash commands (`.claude/commands/`) and skills have been merged. A file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review` and work the same way. If both exist with the same name, the skill takes precedence.

## Getting Started

1. **Explore existing skills**: Browse the [anthropics/skills](https://github.com/anthropics/skills) repository and community collections
2. **Install a few skills**: Copy skill directories to `~/.claude/skills/` for personal use
3. **Test auto-invocation**: Try natural language requests and see which skills activate
4. **Create your first skill**: Start with a simple workflow you repeat often
5. **Iterate on descriptions**: Refine the description until auto-invocation is reliable

Skills transform Claude Code from a general-purpose assistant into a specialized tool tailored to your workflows. By encoding your team's best practices, security requirements, and domain knowledge into skills, you get consistent, high-quality results across your projects.

---

## Level Up Your AI Development Skills

Want to master Claude Code, prompt engineering, and building production AI applications? Our **[Programming with Large Language Models](/training/llm-programming)** course covers everything from API fundamentals to advanced agentic workflows.

In this hands-on training, you'll learn:
- How to effectively use Claude Code and create custom skills
- Prompt engineering patterns that deliver consistent results
- Building RAG systems and AI-powered applications
- Cost optimization and production deployment strategies

Whether you're integrating LLMs into existing systems or building AI-native applications, this course gives your team the practical skills to ship with confidence. [Learn more about our LLM training →](/training/llm-programming)

---

**Sources:**
- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
- [How to Create Custom Skills - Claude Help Center](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills)
- [Anthropic's Official Skills Repository](https://github.com/anthropics/skills)
- [Skill Authoring Best Practices - Claude Docs](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
- [Anthropic Engineering: Equipping Agents for the Real World](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Claude Agent Skills: A First Principles Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/)
- [Inside Claude Code Skills - Mikhail Shilkov](https://mikhail.io/2025/10/claude-code-skills/)
- [Claude Code Customization Guide - alexop.dev](https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/)

Claude Code Skills: The Complete Guide for Developers

TL;DR

Key Takeaways