Cloudflare Workers AI Skill for Claude
Cloudflare Workers AI for serverless GPU inference. Use for LLMs, text/image generation, embeddings, or encountering AI_ERROR, rate limits, token exceeded errors.
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/secondsky/claude-skills --skill cloudflare-workers-aiThe instruction itself
24 sections, as written by the authorCloudflare Workers AI - Complete Reference
Production-ready knowledge domain for building AI-powered applications with Cloudflare Workers AI.
Status: Production Ready ✅
Last Updated: 2025-11-21
Dependencies: cloudflare-worker-base (for Worker setup)
Latest Versions: [email protected], @cloudflare/[email protected]
Table of Contents
- Quick Start (5 minutes)
- Workers AI API Reference
- Model Selection Guide
- Common Patterns
- AI Gateway Integration
- Rate Limits & Pricing
- Production Checklist
Quick Start (5 minutes)
1. Add AI Binding
wrangler.jsonc:
{
"ai": {
"binding": "AI"
}
}
2. Run Your First Model
export interface Env {
AI: Ai;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
prompt: 'What is Cloudflare?',
});
return Response.json(response);
},
};
3. Add Streaming (Recommended)
const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
messages: [{ role: 'user', content: 'Tell me a story' }],
stream: true, // Always use streaming for text generation!
});
return new Response(stream, {
headers: { 'content-type': 'text/event-stream' },
});
Why streaming?
- Prevents buffering large responses in memory
- Faster time-to-first-token
- Better user experience for long-form content
- Avoids Worker timeout issues
Workers AI API Reference
Core API: env.AI.run()
const response = await env.AI.run(model, inputs, options?);
| Parameter | Type | Description |
|-----------|------|-------------|
| model | string | Model ID (e.g., @cf/meta/llama-3.1-8b-instruct) |
| inputs | object | Model-specific inputs (see model type below) |
| options.gateway.id | string | AI Gateway ID for caching/logging |
| options.gateway.skipCache | boolean | Skip AI Gateway cache |
Returns: Promise<ModelOutput> (non-streaming) or ReadableStream (streaming)
Input Types by Model Category
| Category | Key Inputs | Output |
|----------|------------|--------|
| Text Generation | messages[], stream, max_tokens, temperature | { response: string } |
| Embeddings | text: string \| string[] | { data: number[][], shape: number[] } |
| Image Generation | prompt, num_steps, guidance | Binary PNG |
| Vision | messages[].content[].image_url | { response: string } |
📄 Full model details: Load references/models-catalog.md for complete model list, parameters, and rate limits.
Model Selection Guide
Text Generation (LLMs)
| Model | Best For | Rate Limit | Size |
|-------|----------|------------|------|
| @cf/meta/llama-3.1-8b-instruct | General purpose, fast | 300/min | 8B |
| @cf/meta/llama-3.2-1b-instruct | Ultra-fast, simple tasks | 300/min | 1B |
| @cf/qwen/qwen1.5-14b-chat-awq | High quality, complex reasoning | 150/min | 14B |
| @cf/deepseek-ai/deepseek-r1-distill-qwen-32b | Coding, technical content | 300/min | 32B |
| @hf/thebloke/mistral-7b-instruct-v0.1-awq | Fast, efficient | 400/min | 7B |
Text Embeddings
| Model | Dimensions | Best For | Rate Limit |
|-------|-----------|----------|------------|
| @cf/baai/bge-base-en-v1.5 | 768 | General purpose RAG | 3000/min |
| @cf/baai/bge-large-en-v1.5 | 1024 | High accuracy search | 1500/min |
| @cf/baai/bge-small-en-v1.5 | 384 | Fast, low storage | 3000/min |
Image Generation
| Model | Best For | Rate Limit | Speed |
|-------|----------|------------|-------|
| @cf/black-forest-labs/flux-1-schnell | High quality, photorealistic | 720/min | Fast |
| @cf/stabilityai/stable-diffusion-xl-base-1.0 | General purpose | 720/min | Medium |
| @cf/lykon/dreamshaper-8-lcm | Artistic, stylized | 720/min | Fast |
Vision Models
| Model | Best For | Rate Limit |
|-------|----------|------------|
| @cf/meta/llama-3.2-11b-vision-instruct | Image understanding | 720/min |
| @cf/unum/uform-gen2-qwen-500m | Fast image captioning | 720/min |
Common Patterns
Pattern 1: Chat with Streaming
app.post('/chat', async (c) => {
const { messages } = await c.req.json<{ messages: Array<{ role: string; content: string }> }>();
const stream = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', { messages, stream: true });
return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
});
Pattern 2: RAG (Retrieval Augmented Generation)
// 1. Generate embedding for query
const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [userQuery] });
// 2. Search Vectorize
const matches = await env.VECTORIZE.query(embeddings.data[0], { topK: 3 });
// 3. Build context
const context = matches.matches.map((m) => m.metadata.text).join('\n\n');
// 4. Generate with context
const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
messages: [
{ role: 'system', content: `Answer using this context:\n${context}` },
{ role: 'user', content: userQuery },
],
stream: true,
});
return new Response(stream, { headers: { 'content-type': 'text/event-stream' } });
📄 More patterns: Load references/best-practices.md for structured output, image generation, multi-model consensus, and production patterns.
AI Gateway Integration
Enable caching, logging, and cost tracking with AI Gateway:
const response = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' }, {
gateway: { id: 'my-gateway', skipCache: false },
});
Benefits: Cost tracking, response caching (50-90% savings on repeated queries), request logging, rate limiting, analytics.
Rate Limits & Pricing
Information last verified: 2025-01-14
Rate limits and pricing vary significantly by model. Always check the official documentation for the most current information:
- Rate Limits: https://developers.cloudflare.com/workers-ai/platform/limits/
- Pricing: https://developers.cloudflare.com/workers-ai/platform/pricing/
Free Tier: 10,000 neurons/day
Paid Tier: $0.011 per 1,000 neurons
📄 Per-model details: See references/models-catalog.md for specific rate limits and pricing for each model.
Production Checklist
Essential before deploying:
- [ ] Enable AI Gateway for cost tracking
- [ ] Implement streaming for text generation
- [ ] Add rate limit retry with exponential backoff
- [ ] Validate input length (prevent token limit errors)
- [ ] Add input sanitization (prevent prompt injection)
📄 Full checklist: Load references/best-practices.md for complete production checklist, error handling patterns, monitoring, and cost optimization.
External SDK Integrations
Workers AI supports OpenAI SDK compatibility and Vercel AI SDK:
// OpenAI SDK - use same patterns with Workers AI models
const openai = new OpenAI({
apiKey: env.CLOUDFLARE_API_KEY,
baseURL: `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/ai/v1`,
});
// Vercel AI SDK - native integration
import { createWorkersAI } from 'workers-ai-provider';
const workersai = createWorkersAI({ binding: env.AI });
📄 Full integration guide: Load references/integrations.md for OpenAI SDK, Vercel AI SDK, and REST API examples.
Limits Summary
| Feature | Limit |
|---------|-------|
| Concurrent requests | No hard limit (rate limits apply) |
| Max input tokens | Varies by model (typically 2K-128K) |
| Max output tokens | Varies by model (typically 512-2048) |
| Streaming chunk size | ~1 KB |
| Image size (output) | ~5 MB |
| Request timeout | Workers timeout applies (30s default, 5m max CPU) |
| Daily free neurons | 10,000 |
| Rate limits | See "Rate Limits & Pricing" section |
When to Load References
| Reference File | Load When... |
|----------------|--------------|
| references/models-catalog.md | Choosing a model, checking rate limits, comparing model capabilities |
| references/best-practices.md | Production deployment, error handling, cost optimization, security |
| references/integrations.md | Using OpenAI SDK, Vercel AI SDK, or REST API instead of native binding |
References
Other skills for the same job
different authors, same section of the catalogue
Production-ready patterns for building LLM applications. Covers RAG pipelines, agent architectures, prompt IDEs, and LLMOps monitoring. Use when designing AI applications, implementing RAG, building agents, or setting up LLM observability.
Build production ML systems with PyTorch 2.x, TensorFlow, and modern ML frameworks. Implements model serving, feature engineering, A/B testing, and monitoring. Use PROACTIVELY for ML model deployment, inference optimization, or production ML infrastructure.
World-class ML engineering skill for productionizing ML models, MLOps, and building scalable ML systems. Expertise in PyTorch, TensorFlow, model deployment, feature stores, model monitoring, and ML infrastructure. Includes LLM integration, fine-tuning, RAG systems, and agentic AI. Use when deploying ML models, building ML platforms, implementing MLOps, or integrating LLMs into production systems.
Expert in Langfuse - the open-source LLM observability platform. Covers tracing, prompt management, evaluation, datasets, and integration with LangChain, LlamaIndex, and OpenAI. Essential for debugging, monitoring, and improving LLM applications in production. Use when: langfuse, llm observability, llm tracing, prompt management, llm evaluation.
Use this skill for reinforcement learning tasks including training RL agents (PPO, SAC, DQN, TD3, DDPG, A2C, etc.), creating custom Gym environments, implementing callbacks for monitoring and control, using vectorized environments for parallel training, and integrating with deep RL workflows. This skill should be used when users request RL algorithm implementation, agent training, environment design, or RL experimentation.
Managed vector database for production AI applications. Fully managed, auto-scaling, with hybrid search (dense + sparse), metadata filtering, and namespaces. Low latency (<100ms p95). Use for production RAG, recommendation systems, or semantic search at scale. Best for serverless, managed infrastructure.
Deploy, evaluate, fine-tune, and manage Foundry agents end-to-end with azd: hosted agent scaffold/run/deploy, prompt agent create, batch eval, continuous eval, prompt optimizer, Agent Optimizer scaffold, agent.yaml, dataset curation from traces, model fine-tuning (SFT/DPO/RFT). USE FOR: azd ai agent, azd provision/deploy, deploy agent, hosted agent, create agent, add tool to agent, invoke agent, evaluate agent, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, agent optimizer, deploy model, Foundry project, RBAC, role assignment, permissions, quota, capacity, region, troubleshoot agent, deployment failure, AI Services, create Foundry resource, provision, knowledge index, customize deployment, onboard, availability, fine-tune, SFT, DPO, RFT, training-data, grader, distillation, fine-tuned model, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).
Cost optimization patterns for LLM API usage — model routing by task complexity, budget tracking, retry logic, and prompt caching.
How to use it
Take secondsky/cloudflare-workers-ai from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.