Claude Skills — What They Are, How They Work, and When to Build Your Own

What Are Claude Skills?

Claude Skills are reusable tools that extend Claude’s knowledge and capabilities. They’re folders containing a SKILL.md file (Markdown with YAML frontmatter) that Claude automatically loads when relevant—or that you can invoke directly via /skill-name.

Key difference from Tool Use API: Skills are not HTTP endpoints or JSON schema definitions. They’re self-contained instructions that Claude reads and follows. No dashboard. No API registration. Just a simple file structure.

Where Skills Work

• Claude.ai (Pro, Max, Team, Enterprise)
• Claude Code (via custom Skills or built-in Skills)
• Claude API (via Files API or uploaded zips)
• Anthropic-provided Skills (PDF, PPTX, DOCX, XLSX parsing)

Why Use Skills?

Skills solve three problems:

1. Knowledge Extension: Teach Claude about proprietary tools, APIs, or processes
2. Consistency: Same instructions every time—no prompt engineering needed
3. Automation: Chain Skills together to automate workflows

---

Skill Anatomy: The SKILL.md Structure

Every Skill is a folder with a single SKILL.md file:

my-skill/
├── SKILL.md          # The only required file
└── (optional: images, examples, data files)

Basic SKILL.md Format

---
name: skill-name
description: What this Skill does AND when Claude should use it.
---

# Skill Title

## Instructions
[Clear, step-by-step instructions for Claude]

## Examples
[Concrete examples showing the Skill in action]

Real Example: PDF Parsing Skill

---
name: extract-pdf-tables
description: Extract tables from PDF documents. Use this when the user uploads a PDF and asks for table data, summaries, or analysis. Returns structured table data as JSON.
---

# Extract PDF Tables

## Instructions

When processing a PDF:

1. Identify all tables in the document
2. For each table:
   - Extract headers
   - Extract all rows
   - Preserve column structure
3. Output as JSON with `tables` array

## Examples

**User**: "Extract all pricing tables from this PDF"
**Skill Output**:
```json
{
  "tables": [
    {
      "title": "Enterprise Pricing",
      "headers": ["Feature", "Starter", "Pro", "Enterprise"],
      "rows": [
        ["Users", "1", "5", "Unlimited"],
        ["API Calls", "1000/mo", "10000/mo", "Custom"]
      ]
    }
  ]
}

---

## Anthropic Pre-Built Skills

Anthropic provides official Skills for common document formats. You don't need to create these—they're built-in:

| Skill | What It Does | Use When |
|---|---|---|
| **PDF** | Extract text, tables, metadata from PDFs | User uploads PDF; you need specific data |
| **PPTX** | Extract slides, speaker notes, structure from presentations | Analyzing PowerPoint/Keynote files |
| **DOCX** | Extract text, formatting, tables from Word docs | Processing Word documents |
| **XLSX** | Extract data, formulas, structure from Excel files | Analyzing spreadsheets |

These Skills are automatically available in Claude.ai and Claude Code. You invoke them by referencing the document type.

---

## Building Custom Skills

### Step 1: Define the Purpose

Before writing anything, answer:

- **What problem does this Skill solve?**
  - Not: "Help with data"
  - Yes: "Parse customer database exports and identify duplicate entries"

- **When should Claude use it?**
  - Not: "Anytime"
  - Yes: "When the user mentions 'duplicates' or 'data quality'"

- **What's the output?**
  - Not: "Information"
  - Yes: "List of duplicate records with confidence scores (0.0–1.0)"

### Step 2: Write Clear Instructions

Instructions should be step-by-step and unambiguous:

```yaml
---
name: find-duplicate-records
description: Identify duplicate customer records in a database export. Use when user asks about duplicates, data quality, or deduplication. Returns JSON with duplicate groups and match confidence.
---

# Find Duplicate Records

## Instructions

1. Parse the input data (CSV, JSON, or text format)
2. For each record:
   - Extract key fields: email, name, phone
   - Normalize: lowercase, remove whitespace
3. Compare records using fuzzy matching:
   - Email exact match = 1.0 confidence
   - Name + phone match = 0.8–0.9 confidence
   - Name only + similar domain = 0.6–0.7 confidence
4. Group duplicates:
   ```json
   {
     "duplicate_groups": [
       {
         "group_id": 1,
         "records": [
           {"id": "cust_123", "email": "john@acme.com"},
           {"id": "cust_456", "email": "john@acmegroup.com"}
         ],
         "confidence": 0.82
       }
     ],
     "total_duplicates_found": 12
   }

5. Return JSON with duplicate groups and confidence scores

Examples

User: “I have a customer list. Can you find duplicates?” Skill Response:

{
  "total_records": 5000,
  "duplicate_groups": [
    {
      "group_id": 1,
      "records": [
        {"id": "001", "name": "John Smith", "email": "john@company.com"},
        {"id": "256", "name": "John Smyth", "email": "john.smith@company.com"}
      ],
      "confidence": 0.89,
      "reason": "Name + email domain match"
    }
  ],
  "summary": "Found 347 potential duplicates affecting 694 records"
}

### Step 3: Include Examples

Examples show Claude *how* to apply the Skill. Include:

- A realistic user request
- What the Skill does step-by-step
- The exact output format

Don't over-explain. Keep examples concise.

### Step 4: Package and Deploy

**Option 1: Upload via Claude.ai Settings**

1. Create a folder: `my-skill/SKILL.md`
2. Zip it: `my-skill.zip`
3. Go to Claude.ai → Settings → Features → Upload Skill
4. Upload the zip
5. Claude loads the Skill automatically

**Option 2: Use via Claude Code**

1. Create `SKILL.md` in your project
2. Reference it: `Claude, use my custom Skill at ./my-skill/SKILL.md`
3. Claude loads and applies it

**Option 3: API (via Files API)**

```python
from anthropic import Anthropic

client = Anthropic()

# Upload Skill file
response = client.beta.files.upload(
    file=open("SKILL.md", "rb"),
)

skill_file_id = response.id

# Use in conversation
message = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    files=[{
        "id": skill_file_id,
        "mime_type": "text/markdown"
    }],
    messages=[{
        "role": "user",
        "content": "Use my Skill to process this data..."
    }]
)

---

Best Practices for Effective Skills

1. Write Ultra-Clear Instructions

❌ Vague:

description: Process data and find patterns

✅ Clear:

description: Analyze sales data by region. Identify regions with >20% growth. Return JSON with region, growth_rate, and rank.

2. Use Consistent Output Formats

Always return structured output (JSON, CSV, or formatted text):

## Instructions

[...steps...]

Always respond with valid JSON:
```json
{
  "status": "success|error",
  "results": [...],
  "metadata": {
    "records_processed": 1000,
    "timestamp": "ISO 8601 date"
  }
}

### 3. Include Edge Cases in Examples

Show Claude how to handle failures:

```yaml
## Examples

**User**: "Find duplicates in this list of 3 names"
**Expected response**:
```json
{
  "total_records": 3,
  "duplicate_groups": [],
  "note": "No duplicates found (minimum group size: 2)"
}

User: “Process this corrupted CSV” Expected response:

{
  "status": "error",
  "error": "CSV parsing failed at row 42",
  "suggestion": "Check row 42 for valid column structure"
}

### 4. Specify When NOT to Use the Skill

Be explicit about scope:

```yaml
---
name: analyze-sales
description: Analyze sales data (revenue, units, margins). Use when user uploads sales data or asks sales questions. Do NOT use for HR data, customer lists, or inventory.
---

This prevents Claude from misapplying the Skill.

5. Keep Instructions Concise

Aim for <500 words of instructions. Long Skills are hard for Claude to follow. If you need more, split into multiple Skills.

---

Skill Creator: Building Skills Faster

Anthropic provides the Skill Creator Skill, which helps you build custom Skills faster.

How It Works

1. Describe what you want the Skill to do
2. Skill Creator generates a SKILL.md template
3. You refine and deploy

Example

You: “Create a Skill that finds color contrasts in design files”

Skill Creator Response:

---
name: analyze-color-contrast
description: Analyze color contrast ratios in design files (PNG, SVG). Check accessibility compliance (WCAG AA/AAA). Returns contrast scores and recommendations.
---

# Analyze Color Contrast

## Instructions

1. Accept image files (PNG, JPG, SVG)
2. Extract all text + background colors
3. Calculate WCAG contrast ratio for each pair
4. Check against AA (4.5:1 text) and AAA (7:1 text) standards
5. Return JSON with:
   - Total color pairs analyzed
   - Passing/failing pairs
   - Accessibility level achieved
   - Specific recommendations

## Examples

**User**: "Check contrast in this design"
**Response**:
```json
{
  "file": "design.png",
  "analysis": {
    "total_pairs": 24,
    "wcag_aa_pass": 20,
    "wcag_aaa_pass": 15,
    "recommendations": [
      "Heading #1: Increase button text size for better visibility",
      "Footer: Darken background (current: 2.1:1, need 4.5:1)"
    ]
  },
  "status": "partial_pass"
}

Then you customize, add domain-specific details, and deploy.

---

## Advanced: Chaining Skills

Skills work together automatically. Claude chains them when solving complex problems.

### Example: Document → Analysis → Report

User: “Analyze this PDF and create an executive summary”

Claude chains:

1. PDF Skill (extract content)
2. Summarize Skill (condense key points)
3. Format Report Skill (create executive summary)

Result: Clean, formatted report

You don't need to explicitly chain—Claude figures it out if:
- Each Skill's purpose is clear
- Output from one feeds into another logically
- Instructions don't conflict

### Create Skills That Chain Well

Make outputs from one Skill useable by the next:

```yaml
---
name: extract-metrics
description: Extract KPIs from reports. Returns JSON with metric_name, value, unit, trend.
---

[instructions that guarantee JSON output]

---
name: generate-dashboard
description: Create dashboard from metrics JSON. Accepts output from extract-metrics Skill.
---

[instructions that accept the specific JSON format]

Claude chains these automatically because the output format of the first matches the expected input of the second.

---

Real-World Examples

Example 1: Code Review Skill

---
name: code-review
description: Review code for bugs, performance issues, and best practices. Use when user shares code snippets or asks for reviews. Returns structured feedback with severity levels.
---

# Code Review

## Instructions

1. Analyze the code for:
   - Logic errors (severity: critical)
   - Performance issues (memory, loops, database queries)
   - Security vulnerabilities (hardcoded secrets, injection risks)
   - Style violations (naming, formatting)

2. Return JSON:
```json
{
  "file": "filename",
  "issues": [
    {
      "line": 42,
      "severity": "critical|high|medium|low",
      "type": "bug|performance|security|style",
      "description": "...",
      "suggestion": "..."
    }
  ],
  "summary": "Found 3 critical issues, 2 performance concerns"
}

Examples

User: “Review this function for bugs”

Skill Response:

{
  "issues": [
    {
      "line": 15,
      "severity": "critical",
      "type": "bug",
      "description": "Loop modifies collection while iterating (will skip items)",
      "suggestion": "Create a copy or use filter() instead of splice()"
    }
  ],
  "summary": "Found 1 critical issue"
}

### Example 2: Customer Support Skill

```yaml
---
name: support-ticket-analyzer
description: Analyze support tickets. Classify by urgency, extract action items, and suggest responses. Use when reviewing customer tickets or complaints.
---

# Support Ticket Analyzer

## Instructions

1. Extract:
   - Customer sentiment (positive, neutral, negative)
   - Urgency (critical, high, medium, low)
   - Product/feature mentioned
   - Action items (what needs to be fixed)

2. Suggest response template

3. Return JSON with classification + suggested response

## Examples

**User**: "Analyze this support ticket..."

**Skill Response**:
```json
{
  "sentiment": "negative",
  "urgency": "critical",
  "product": "Mobile App",
  "action_items": [
    "Fix login crash on iOS 17.4",
    "Refund $50 subscription"
  ],
  "suggested_response": "We sincerely apologize for the crash. Our team is prioritizing a fix for iOS 17.4. In the meantime, we're issuing a full refund..."
}

### Example 3: Data Validation Skill

```yaml
---
name: validate-data
description: Validate data quality (completeness, format, duplicates). Use when importing or processing datasets. Returns validation report with errors and warnings.
---

# Validate Data

## Instructions

1. Check each record for:
   - Required fields present (no nulls)
   - Format compliance (email, phone, date formats)
   - Value ranges (age, quantity, price)
   - Duplicates

2. Return:
```json
{
  "total_records": 1000,
  "valid": 950,
  "invalid": 50,
  "errors": [
    {"row": 42, "field": "email", "issue": "Invalid format"}
  ],
  "warnings": [
    {"row": 100, "field": "age", "issue": "Unusually high value (156)"}
  ]
}

Examples

User: “Validate this CSV…”

Skill Response: [validation report with error count and suggested fixes]

---

## Troubleshooting: Why Skills Don't Work

### Problem 1: Claude Doesn't Use the Skill

**Reason**: Description is unclear or too broad

**Fix**: Make the "when to use" explicit:

```yaml
# ❌ Before
description: Process data

# ✅ After
description: Extract dates from unstructured text (emails, documents). Returns JSON array with dates and context. Use when user asks "find dates" or uploads text with dates.

Problem 2: Claude Misinterprets Instructions

Reason: Step-by-step instructions are vague

Fix: Be granular:

# ❌ Before
## Instructions
Analyze the data and find insights

# ✅ After
## Instructions
1. Load the dataset
2. For each column, calculate: mean, median, standard deviation
3. Identify outliers (values >3σ from mean)
4. Return JSON with per-column analysis

Problem 3: Output Format is Inconsistent

Reason: Instructions don’t specify format

Fix: Show exact format in instructions:

## Instructions
[...steps...]

Always respond with this JSON structure:
```json
{
  "status": "success",
  "data": {...},
  "metadata": {...}
}

---

## Skill Creator Reference

The **Anthropic Skill Creator** is available in Claude.ai and Claude Code. Use it to:

- Generate Skill templates from descriptions
- Refine existing Skills
- Test Skills before deploying
- Get feedback on Skill design

**Access**: Claude.ai → search "Skill Creator" or `/skill-creator`

---

## Next Steps

1. **Start with a simple Skill**: Pick one problem you solve repeatedly
2. **Test it in Claude.ai**: Upload and refine based on results
3. **Share it**: Zip and share with your team
4. **Iterate**: Improve based on feedback
5. **Combine Skills**: Create workflows by chaining multiple Skills

Skills are simple, powerful, and surprisingly effective at extending Claude's capabilities. Build your first Skill today.

---

## Resources

- **Anthropic Skills GitHub**: github.com/anthropics/skills
- **Skill Creator**: Available in Claude.ai and Claude Code
- **Pre-built Skills**: PDF, PPTX, DOCX, XLSX (built-in to Claude.ai)