Overview

Skills are reusable packages of instructions, context, and supporting files that extend Claude's capabilities. Unlike slash commands which you explicitly invoke, skills are automatically discovered and used by Claude when they're relevant to your request.

Creating Skills

Storage Locations

Directory Structure

# Simple single-file skill
~/.claude/skills/
  my-skill/
    SKILL.md                # Required: skill definition

# Multi-file skill with supporting files
~/.claude/skills/
  api-testing/
    SKILL.md                # Required: skill definition
    examples/
      request.json          # Supporting file
      response.json         # Supporting file
    templates/
      test-template.js      # Template file

Each skill must live in its own directory with a SKILL.md file. Supporting files in the directory are loaded progressively based on context relevance.

SKILL.md Format

Basic Structure

---
name: skill-name
description: Clear description of what this skill does and when to use it
allowed-tools: Read, Grep, Glob
---

Your skill's instructions and context go here.

This can include:
- Step-by-step processes
- Code examples
- Best practices
- Workflow guidelines
- Templates and patterns

Frontmatter Fields

Good vs Bad Descriptions

Key Features

Tool Restrictions

Use allowed-tools to create read-only or security-sensitive workflows:

---
name: security-audit
description: Use when auditing code for security vulnerabilities and compliance issues
allowed-tools: Read, Grep, Glob
---

You are a security auditor. Review code for:
- SQL injection vulnerabilities
- XSS attack vectors
- Exposed credentials
- Insecure dependencies

IMPORTANT: You have read-only access. Report findings but do not modify code.

Progressive File Loading

Supporting files in skill directories are loaded automatically when relevant:

api-testing/
  SKILL.md              # Always loaded
  examples/
    get-request.json    # Loaded if Claude needs GET examples
    post-request.json   # Loaded if Claude needs POST examples
  templates/
    test-suite.js       # Loaded if creating test suites

This keeps the initial skill context small while making additional resources available when needed.

Priority Order

When skills have the same name, Claude Code prioritizes:

1. Project skills (.claude/skills/) - highest priority
2. Personal skills (~/.claude/skills/)
3. Plugin skills (lowest priority)

This allows projects to override personal preferences and personal preferences to override plugin defaults.

Examples

Simple Single-File Skill

A basic skill for enforcing code style guidelines:

---
name: code-style-guide
description: Use when reviewing code for style consistency or when explicitly asked about code style guidelines. Enforces team coding standards.
---

Code Style Guidelines:

1. **Naming Conventions**
   - Variables: camelCase (e.g., `userName`, `isActive`)
   - Constants: UPPER_SNAKE_CASE (e.g., `MAX_RETRIES`)
   - Classes: PascalCase (e.g., `UserController`)
   - Files: kebab-case (e.g., `user-service.js`)

2. **Function Guidelines**
   - Max 50 lines per function
   - Single responsibility
   - Descriptive names (verb + noun)
   - Document parameters with JSDoc

3. **Error Handling**
   - Always use try/catch for async operations
   - Custom error classes for domain errors
   - Log errors before re-throwing

4. **Testing**
   - Minimum 80% code coverage
   - Test file naming: `*.test.js`
   - Use descriptive test names

When reviewing code, cite specific guideline violations and suggest corrections.

Multi-File Skill

A skill with supporting templates and examples:

# .claude/skills/component-generator/SKILL.md
---
name: component-generator
description: Use when creating React components or when asked to generate UI components. Provides templates and best practices for React development.
allowed-tools: Read, Write, Grep, Glob
---

React Component Generator

When creating components:

1. **File Structure**
   - Use the template in `templates/component-template.tsx`
   - Create test file using `templates/test-template.tsx`
   - Add styles using `templates/styles-template.css`

2. **Component Guidelines**
   - Functional components with hooks
   - TypeScript for type safety
   - Props interface defined
   - Default props when applicable

3. **Best Practices**
   - Single responsibility
   - Proper prop validation
   - Accessibility (ARIA labels)
   - Responsive design
   - Error boundaries for critical components

See examples/ directory for reference implementations.

// .claude/skills/component-generator/templates/component-template.tsx
import React from 'react';
import './ComponentName.css';

interface ComponentNameProps {
  // Define your props here
}

export const ComponentName: React.FC = (props) => {
  // Component implementation
  return (
    

      {/* Component JSX */}
    
  );
};

ComponentName.defaultProps = {
  // Default props
};

Advanced Read-Only Skill

---
name: architecture-analyzer
description: Use when analyzing system architecture, reviewing design decisions, or creating architecture documentation. Read-only analysis of codebase structure.
allowed-tools: Read, Grep, Glob, Bash
---

Architecture Analysis Specialist

You are an expert software architect analyzing codebases for:

**Analysis Areas:**
1. **Architectural Patterns**
   - Identify: MVC, MVVM, microservices, monolith, etc.
   - Assess pattern consistency
   - Note pattern violations

2. **Dependency Analysis**
   - Map module dependencies
   - Identify circular dependencies
   - Assess coupling levels
   - Check dependency injection usage

3. **Layering & Separation**
   - Presentation layer
   - Business logic layer
   - Data access layer
   - Cross-cutting concerns

4. **Code Organization**
   - Directory structure
   - Module boundaries
   - Naming consistency
   - File organization

**Deliverables:**
- Architecture diagram (ASCII or Mermaid)
- Dependency graph
- Identified issues with severity
- Recommendations for improvement

**Process:**
1. Start with entry points (main.js, index.js)
2. Map major modules and their responsibilities
3. Analyze inter-module communication
4. Identify architectural patterns
5. Document findings with code references

Remember: You are read-only. Analyze and recommend, don't modify.

Usage & Discovery

How Claude Finds Skills

Claude automatically discovers skills by:

1. Scanning all skill directories (project, personal, plugin)
2. Reading each SKILL.md description
3. Matching descriptions against your request context
4. Loading relevant skills when they apply

Automatic vs Explicit

Viewing Available Skills

You can ask Claude to list available skills:

> What skills are available?
> List all skills
> Show me the skills I can use

Team Sharing

Git Distribution

Share project skills via version control:

# Create project skill
.claude/
  skills/
    code-review/
      SKILL.md
      checklists/
        security-checklist.md
        performance-checklist.md

# Commit to repository
git add .claude/skills/
git commit -m "Add code review skill for team"
git push

# Team members automatically get skill when they pull
git pull

Plugin Distribution

Package skills in plugins for broader distribution:

my-plugin/
  plugin.json           # Plugin metadata
  skills/
    skill-one/
      SKILL.md
    skill-two/
      SKILL.md
      templates/
        template.js

When users install your plugin, skills are automatically available. See the Plugins documentation for details.

Skills vs Slash Commands

When to Use Each

Best Practices

Troubleshooting

Skill Not Being Invoked

Tool Access Issues

Supporting Files Not Loading

Skill Priority Issues

YAML Parsing Errors

---
name: skill-name
description: Description text
---

Skill content here

Related