How to Upload Skills to Claude

Quick Answer

You have 3 options to upload the .zip file:

Option 1: Automatic Upload (Recommended for CLI)

# Set your API key (one-time setup)
export ANTHROPIC_API_KEY=sk-ant-...

# Package and upload automatically
python3 cli/package_skill.py output/react/ --upload

# OR upload existing .zip
python3 cli/upload_skill.py output/react.zip

✅ Fully automatic | No manual steps | Requires API key

Option 2: Manual Upload (No API Key)

# Package the skill
python3 cli/package_skill.py output/react/

# This will:
# 1. Create output/react.zip
# 2. Open output/ folder automatically
# 3. Show clear upload instructions

# Then upload manually to https://claude.ai/skills

✅ No API key needed | Works for everyone | Simple

Option 3: Claude Code MCP (Easiest)

In Claude Code, just say:
"Package and upload the React skill"

# Automatically packages and uploads!

✅ Natural language | Fully automatic | Best UX

What's Inside the Zip?

The .zip file contains:

steam-economy.zip
├── SKILL.md              ← Main skill file (Claude reads this first)
└── references/           ← Reference documentation
    ├── index.md          ← Category index
    ├── api_reference.md  ← API docs
    ├── pricing.md        ← Pricing docs
    ├── trading.md        ← Trading docs
    └── ...               ← Other categorized docs

Note: The zip only includes what Claude needs. It excludes:

.backup files
Build artifacts
Temporary files

What Does package_skill.py Do?

The package script:

Finds your skill directory (e.g., output/steam-economy/)
Validates SKILL.md exists (required!)
Creates a .zip file with the same name
Includes all files except backups
Saves to output/ directory

Example:

python3 cli/package_skill.py output/steam-economy/

📦 Packaging skill: steam-economy
   Source: output/steam-economy
   Output: output/steam-economy.zip
   + SKILL.md
   + references/api_reference.md
   + references/pricing.md
   + references/trading.md
   + ...

✅ Package created: output/steam-economy.zip
   Size: 14,290 bytes (14.0 KB)

Complete Workflow

Step 1: Scrape & Build

python3 cli/doc_scraper.py --config configs/steam-economy.json

Output:

output/steam-economy_data/ (raw scraped data)
output/steam-economy/ (skill directory)

Step 2: Enhance (Recommended)

python3 cli/enhance_skill_local.py output/steam-economy/

What it does:

Analyzes reference files
Creates comprehensive SKILL.md
Backs up original to SKILL.md.backup

Output:

output/steam-economy/SKILL.md (enhanced)
output/steam-economy/SKILL.md.backup (original)

Step 3: Package

python3 cli/package_skill.py output/steam-economy/

Output:

output/steam-economy.zip ← THIS IS WHAT YOU UPLOAD

Step 4: Upload to Claude

Go to Claude (claude.ai)
Click "Add Skill" or skill upload button
Select output/steam-economy.zip
Done!

What Files Are Required?

Minimum required structure:

your-skill/
└── SKILL.md          ← Required! Claude reads this first

Recommended structure:

your-skill/
├── SKILL.md          ← Main skill file (required)
└── references/       ← Reference docs (highly recommended)
    ├── index.md
    └── *.md          ← Category files

Optional (can add manually):

your-skill/
├── SKILL.md
├── references/
├── scripts/          ← Helper scripts
│   └── *.py
└── assets/           ← Templates, examples
    └── *.txt

File Size Limits

The package script shows size after packaging:

✅ Package created: output/steam-economy.zip
   Size: 14,290 bytes (14.0 KB)

Typical sizes:

Small skill: 5-20 KB
Medium skill: 20-100 KB
Large skill: 100-500 KB

Claude has generous size limits, so most documentation-based skills fit easily.

Quick Reference

Package a Skill

python3 cli/package_skill.py output/steam-economy/

Package Multiple Skills

# Package all skills in output/
for dir in output/*/; do
  if [ -f "$dir/SKILL.md" ]; then
    python3 cli/package_skill.py "$dir"
  fi
done

Check What's in a Zip

unzip -l output/steam-economy.zip

Test a Packaged Skill Locally

# Extract to temp directory
mkdir temp-test
unzip output/steam-economy.zip -d temp-test/
cat temp-test/SKILL.md

Troubleshooting

"SKILL.md not found"

# Make sure you scraped and built first
python3 cli/doc_scraper.py --config configs/steam-economy.json

# Then package
python3 cli/package_skill.py output/steam-economy/

"Directory not found"

# Check what skills are available
ls output/

# Use correct path
python3 cli/package_skill.py output/YOUR-SKILL-NAME/

Zip is Too Large

Most skills are small, but if yours is large:

# Check size
ls -lh output/steam-economy.zip

# If needed, check what's taking space
unzip -l output/steam-economy.zip | sort -k1 -rn | head -20

Reference files are usually small. Large sizes often mean:

Many images (skills typically don't need images)
Large code examples (these are fine, just be aware)

What Does Claude Do With the Zip?

When you upload a skill zip:

Claude extracts it
Reads SKILL.md first - This tells Claude:
- When to activate this skill
- What the skill does
- Quick reference examples
- How to navigate the references
Indexes reference files - Claude can search through:
- references/*.md files
- Find specific APIs, examples, concepts
Activates automatically - When you ask about topics matching the skill

Example: Using the Packaged Skill

After uploading steam-economy.zip:

You ask: "How do I implement microtransactions in my Steam game?"

Claude:

Recognizes this matches steam-economy skill
Reads SKILL.md for quick reference
Searches references/microtransactions.md
Provides detailed answer with code examples

API-Based Automatic Upload

Setup (One-Time)

# Get your API key from https://console.anthropic.com/
export ANTHROPIC_API_KEY=sk-ant-...

# Add to your shell profile to persist
echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.bashrc  # or ~/.zshrc

Usage

# Upload existing .zip
python3 cli/upload_skill.py output/react.zip

# OR package and upload in one command
python3 cli/package_skill.py output/react/ --upload

How It Works

The upload tool uses the Anthropic /v1/skills API endpoint to:

Read your .zip file
Authenticate with your API key
Upload to Claude's skill storage
Verify upload success

Troubleshooting

"ANTHROPIC_API_KEY not set"

# Check if set
echo $ANTHROPIC_API_KEY

# If empty, set it
export ANTHROPIC_API_KEY=sk-ant-...

"Authentication failed"

Verify your API key is correct
Check https://console.anthropic.com/ for valid keys

"Upload timed out"

Check your internet connection
Try again or use manual upload

Upload fails with error

Falls back to showing manual upload instructions
You can still upload via https://claude.ai/skills

Summary

What you need to do:

With API Key (Automatic):

✅ Scrape: python3 cli/doc_scraper.py --config configs/YOUR-CONFIG.json
✅ Enhance: python3 cli/enhance_skill_local.py output/YOUR-SKILL/
✅ Package & Upload: python3 cli/package_skill.py output/YOUR-SKILL/ --upload
✅ Done! Skill is live in Claude

Without API Key (Manual):

✅ Scrape: python3 cli/doc_scraper.py --config configs/YOUR-CONFIG.json
✅ Enhance: python3 cli/enhance_skill_local.py output/YOUR-SKILL/
✅ Package: python3 cli/package_skill.py output/YOUR-SKILL/
✅ Upload: Go to https://claude.ai/skills and upload the .zip

What you upload:

The .zip file from output/ directory
Example: output/steam-economy.zip

What's in the zip:

SKILL.md (required)
references/*.md (recommended)
Any scripts/assets you added (optional)

That's it! 🚀

UPLOAD_GUIDE.md 8.1 KB History Raw

How to Upload Skills to Claude

Quick Answer

Option 1: Automatic Upload (Recommended for CLI)

Option 2: Manual Upload (No API Key)

Option 3: Claude Code MCP (Easiest)

What's Inside the Zip?

What Does package_skill.py Do?

Complete Workflow

Step 1: Scrape & Build

Step 2: Enhance (Recommended)

Step 3: Package

Step 4: Upload to Claude

What Files Are Required?

File Size Limits

Quick Reference

Package a Skill

Package Multiple Skills

Check What's in a Zip

Test a Packaged Skill Locally

Troubleshooting

"SKILL.md not found"

"Directory not found"

Zip is Too Large

What Does Claude Do With the Zip?

Example: Using the Packaged Skill

API-Based Automatic Upload

Setup (One-Time)

Usage

How It Works

Troubleshooting

Summary

With API Key (Automatic):

Without API Key (Manual):

UPLOAD_GUIDE.md 8.1 KB

History Raw