Skip to content

UPLOAD_GUIDE.md

Latest commit

 

History

History
351 lines (264 loc) · 8.07 KB

UPLOAD_GUIDE.md

File metadata and controls

351 lines (264 loc) · 8.07 KB

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:

  1. Finds your skill directory (e.g., output/steam-economy/)
  2. Validates SKILL.md exists (required!)
  3. Creates a .zip file with the same name
  4. Includes all files except backups
  5. 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

  1. Go to Claude (claude.ai)
  2. Click "Add Skill" or skill upload button
  3. Select output/steam-economy.zip
  4. 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:

  1. Claude extracts it
  2. Reads SKILL.md first - This tells Claude:
    • When to activate this skill
    • What the skill does
    • Quick reference examples
    • How to navigate the references
  3. Indexes reference files - Claude can search through:
    • references/*.md files
    • Find specific APIs, examples, concepts
  4. 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:

  1. Read your .zip file
  2. Authenticate with your API key
  3. Upload to Claude's skill storage
  4. 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"

"Upload timed out"

  • Check your internet connection
  • Try again or use manual upload

Upload fails with error

Summary

What you need to do:

With API Key (Automatic):

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

Without API Key (Manual):

  1. ✅ Scrape: python3 cli/doc_scraper.py --config configs/YOUR-CONFIG.json
  2. ✅ Enhance: python3 cli/enhance_skill_local.py output/YOUR-SKILL/
  3. ✅ Package: python3 cli/package_skill.py output/YOUR-SKILL/
  4. ✅ 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! 🚀