image-upload

Image Upload Skill

Upload local images to various image hosting providers and get shareable URLs in multiple formats.

Quick Start

Just tell Claude to upload an image:

Upload this image: /path/to/screenshot.png

Claude will upload it to the default provider (Catbox) and return the URL.

Usage Examples

Basic Upload

Upload /tmp/screenshot.png

Upload with Custom Name

Upload /path/to/image.jpg as "my-screenshot"

Upload to Specific Provider

Upload /path/to/photo.png to imgur

Get Specific Format

Upload this image and give me the markdown: /path/to/diagram.png

Supported Providers

Provider	Max Size	Config Required	Best For
Catbox	200MB	No	Default, anonymous, permanent
ImgBB	32MB	API Key	Reliable, good API
Imgur	20MB	Client-ID	Popular, widely supported
Freeimage	64MB	API Key	Large files
ImgHippo	50MB	API Key	Alternative option
Weibo	20MB	Cookies	China users (legacy)

Configuration

No Configuration Required (Default)

Catbox.moe works out of the box without any API keys!

Optional: Configure Other Providers

Create a .env file in your project or ~/.claude/ directory:

# Use a different default provider
IMAGE_UPLOAD_PROVIDER=imgbb

# Provider API keys
IMGBB_API_KEY=your_key_here
IMGUR_CLIENT_ID=your_client_id
FREEIMAGE_API_KEY=your_key
IMGHIPPO_API_KEY=your_key

Output Formats

The skill returns URLs in multiple formats:

• URL: Direct link to the image
• Markdown: ![name](url) for documentation
• HTML: <img src="url"> for web pages
• BBCode: [IMG]url[/IMG] for forums

Programmatic Use

import { uploadImage } from 'image-upload';

const result = await uploadImage('/path/to/image.png', {
  provider: 'catbox',
  name: 'my-image'
});

console.log(result.url);           // https://files.catbox.moe/abc123.png
console.log(result.formatted.markdown); // ![my-image](https://...)

CLI Usage

# Install dependencies
cd image-upload && npm install

# Upload an image
npx tsx src/index.ts /path/to/image.png

# With options
npx tsx src/index.ts /path/to/image.png --provider imgur --name screenshot

Error Handling

The skill handles common errors gracefully:

• File not found
• File too large for provider
• Unsupported file type
• Network errors
• Authentication failures

Notes

• Catbox is the recommended default - no signup, no limits, permanent hosting
• ImgBB and Imgur have daily rate limits but are more established
• Weibo is legacy and not recommended for new projects
• All uploads are anonymous unless you configure user accounts

Getting Started (go here when the user does not know what to enter)

Trigger：/图床 新手, "How do I use this", "First time using it", "What can it do", "Walk me through it", and when the user enters a skill name but does not give any task.

The iron rules of this mode:Do not assume, do not ask for things. The user may not have anything ready, so do not start by asking them for files, API keys, or specific requirements. Follow these four steps:

1. First explain what this is (within three sentences)

One sentence:upload local images to a free image hosting provider and get the link directly. It returns a format that can be pasted directly into Markdown, so when writing articles and adding illustrations, you no longer need to find an image host and copy links yourself.

2. Give numbered options so they can continue by pressing Enter

Do not ask open-ended questions ("What do you want to do?" is a burden for beginners). Give 3 options plus a default:

想先看哪个？（直接回车 = 1）
  1. 先讲讲怎么用
  2. 把这张图传上去拿链接
  3. 支持哪些图床

3. Demonstrate it directly, explaining while doing it

After they choose, immediately demonstrate it for them, usingsample data, without requiring them to provide anything. After each step is completed, add a line saying "💡 What just happened", explaining the meaning of that step in one sentence.

4. Graduation

After the demonstration, ask only one yes-or-no question: "Do you want to run through it for real with your own images?" If yes, proceed to the normal workflow; if no, tell them they can come back anytime and enter /图床 新手。