Cloudflare Worker Dev Skill for Cursor

Cloudflare Workers, KV, Durable Objects, and edge computing development. Use for serverless APIs, caching, rate limiting, real-time features. Activate on "Workers", "KV", "Durable Objects", "wrangler", "edge function", "Cloudflare". NOT for Cloudflare Pages configuration (use deployment docs), DNS management, or general CDN settings.

3k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

177

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/curiositech/some_claude_skills --skill cloudflare-worker-dev

The instruction itself

26 sections, as written by the author

Cloudflare Workers Development

Build high-performance edge APIs with Workers, KV for caching, and Durable Objects for real-time coordination.

Core Architecture

When to Use What

| Service | Use Case | Characteristics |

|---------|----------|-----------------|

| Workers | Request handling, API logic | Stateless, 50ms CPU (free), 30s (paid) |

| KV | Caching, config, sessions | Eventually consistent, fast reads |

| Durable Objects | Real-time, coordination | Strongly consistent, single-threaded |

| R2 | File storage | S3-compatible, no egress fees |

| D1 | SQLite at edge | Serverless SQL, good for reads |

Worker Fundamentals

Basic Worker Structure

// src/index.ts
export interface Env {
  MEETING_CACHE: KVNamespace;
  RATE_LIMIT: KVNamespace;
  API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    // CORS handling
    if (request.method === 'OPTIONS') {
      return handleCORS();
    }

    try {
      // Route handling
      if (url.pathname === '/health') {
        return json({ status: 'ok' });
      }

      if (url.pathname.startsWith('/api/')) {
        return handleAPI(request, env, ctx);
      }

      return new Response('Not Found', { status: 404 });
    } catch (error) {
      console.error('Worker error:', error);
      return json({ error: 'Internal error' }, 500);
    }
  },

  // Cron trigger
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    ctx.waitUntil(runScheduledTask(env));
  }
};

CORS Headers (Essential)

const CORS_HEADERS = {
  'Access-Control-Allow-Origin': '*', // Or specific origin
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
  'Access-Control-Max-Age': '86400',
};

function handleCORS(): Response {
  return new Response(null, { status: 204, headers: CORS_HEADERS });
}

function json(data: unknown, status = 200): Response {
  return new Response(JSON.stringify(data), {
    status,
    headers: {
      ...CORS_HEADERS,
      'Content-Type': 'application/json',
    },
  });
}

wrangler.toml Configuration

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# KV Namespaces
[[kv_namespaces]]
binding = "MEETING_CACHE"
id = "abc123..."  # Production
preview_id = "def456..."  # Dev

[[kv_namespaces]]
binding = "RATE_LIMIT"
id = "ghi789..."

# Environment variables
[vars]
CACHE_TTL = "86400"
RATE_LIMIT_REQUESTS = "100"
RATE_LIMIT_WINDOW = "3600"

# Secrets (set via `wrangler secret put`)
# API_KEY, DATABASE_URL, etc.

# Cron triggers
[triggers]
crons = ["0 */6 * * *"]  # Every 6 hours

# Custom routes
# routes = [{ pattern = "api.example.com/*", zone_name = "example.com" }]

KV Storage Patterns

Basic KV Operations

// Write with TTL
await env.CACHE.put('key', JSON.stringify(data), {
  expirationTtl: 86400, // 24 hours in seconds
});

// Write with metadata
await env.CACHE.put('key', value, {
  expirationTtl: 3600,
  metadata: { createdAt: Date.now(), source: 'api' },
});

// Read
const value = await env.CACHE.get('key');
const parsed = await env.CACHE.get('key', 'json');

// Read with metadata
const { value, metadata } = await env.CACHE.getWithMetadata('key', 'json');

// Delete
await env.CACHE.delete('key');

// List keys
const { keys, cursor } = await env.CACHE.list({ prefix: 'meetings:' });

Geohash-Based Caching

import Geohash from 'latlon-geohash';

function getCacheKey(lat: number, lng: number, radius: number): string {
  // 3-char geohash = ~150km cells, good for metro areas
  const geohash = Geohash.encode(lat, lng, 3);
  return `meetings:${geohash}:${radius}`;
}

async function getMeetingsWithCache(
  lat: number,
  lng: number,
  radius: number,
  env: Env
): Promise<{ data: Meeting[]; cached: boolean; geohash: string }> {
  const geohash = Geohash.encode(lat, lng, 3);
  const cacheKey = `meetings:${geohash}:${radius}`;

  // Try cache first
  const cached = await env.MEETING_CACHE.get(cacheKey, 'json');
  if (cached) {
    return { data: cached, cached: true, geohash };
  }

  // Fetch fresh data
  const data = await fetchMeetings(lat, lng, radius);

  // Cache in background (don't await)
  env.ctx.waitUntil(
    env.MEETING_CACHE.put(cacheKey, JSON.stringify(data), {
      expirationTtl: 86400,
      metadata: { cachedAt: Date.now(), geohash },
    })
  );

  return { data, cached: false, geohash };
}

Response Headers for Cache Debugging

function meetingsResponse(data: Meeting[], cached: boolean, geohash: string): Response {
  return new Response(JSON.stringify(data), {
    headers: {
      ...CORS_HEADERS,
      'Content-Type': 'application/json',
      'X-Cache': cached ? 'HIT' : 'MISS',
      'X-Geohash': geohash,
      'Cache-Control': 'public, max-age=3600',
    },
  });
}

Rate Limiting

IP-Based Rate Limiting

interface RateLimitConfig {
  maxRequests: number;
  windowSeconds: number;
}

async function checkRateLimit(
  ip: string,
  env: Env,
  config: RateLimitConfig
): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
  const key = `rate:${ip}`;
  const now = Math.floor(Date.now() / 1000);
  const windowStart = now - config.windowSeconds;

  // Get current state
  const stored = await env.RATE_LIMIT.get(key, 'json') as {
    count: number;
    windowStart: number;
  } | null;

  // New window or expired
  if (!stored || stored.windowStart < windowStart) {
    await env.RATE_LIMIT.put(key, JSON.stringify({
      count: 1,
      windowStart: now,
    }), { expirationTtl: config.windowSeconds });

    return {
      allowed: true,
      remaining: config.maxRequests - 1,
      resetAt: now + config.windowSeconds,
    };
  }

  // Within window
  if (stored.count >= config.maxRequests) {
    return {
      allowed: false,
      remaining: 0,
      resetAt: stored.windowStart + config.windowSeconds,
    };
  }

  // Increment
  await env.RATE_LIMIT.put(key, JSON.stringify({
    count: stored.count + 1,
    windowStart: stored.windowStart,
  }), { expirationTtl: config.windowSeconds });

  return {
    allowed: true,
    remaining: config.maxRequests - stored.count - 1,
    resetAt: stored.windowStart + config.windowSeconds,
  };
}

// Usage in handler
async function handleAPI(request: Request, env: Env): Promise<Response> {
  const ip = request.headers.get('CF-Connecting-IP') || 'unknown';
  const rateLimit = await checkRateLimit(ip, env, {
    maxRequests: parseInt(env.RATE_LIMIT_REQUESTS || '100'),
    windowSeconds: parseInt(env.RATE_LIMIT_WINDOW || '3600'),
  });

  if (!rateLimit.allowed) {
    return json({ error: 'Rate limit exceeded' }, 429, {
      'X-RateLimit-Remaining': '0',
      'X-RateLimit-Reset': rateLimit.resetAt.toString(),
    });
  }

  // ... handle request
}

Durable Objects (Real-Time)

Chat Room Example

// wrangler.toml
// [[durable_objects.bindings]]
// name = "CHAT_ROOMS"
// class_name = "ChatRoom"
// [[migrations]]
// tag = "v1"
// new_classes = ["ChatRoom"]

export class ChatRoom {
  state: DurableObjectState;
  sessions: WebSocket[] = [];

  constructor(state: DurableObjectState) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/websocket') {
      if (request.headers.get('Upgrade') !== 'websocket') {
        return new Response('Expected WebSocket', { status: 400 });
      }

      const [client, server] = Object.values(new WebSocketPair());

      server.accept();
      this.sessions.push(server);

      server.addEventListener('message', (event) => {
        this.broadcast(event.data as string, server);
      });

      server.addEventListener('close', () => {
        this.sessions = this.sessions.filter(s => s !== server);
      });

      return new Response(null, { status: 101, webSocket: client });
    }

    return new Response('Not found', { status: 404 });
  }

  broadcast(message: string, exclude?: WebSocket) {
    this.sessions.forEach(session => {
      if (session !== exclude && session.readyState === WebSocket.OPEN) {
        session.send(message);
      }
    });
  }
}

// In main worker
export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    if (url.pathname.startsWith('/room/')) {
      const roomId = url.pathname.split('/')[2];
      const id = env.CHAT_ROOMS.idFromName(roomId);
      const room = env.CHAT_ROOMS.get(id);
      return room.fetch(request);
    }
  }
};

Deployment & Debugging

Commands

# Development
npx wrangler dev                    # Local dev server
npx wrangler dev --remote           # Dev against real KV/DO

# Deployment
npx wrangler deploy                 # Deploy to production
npx wrangler deploy --env staging   # Deploy to staging

# Secrets
npx wrangler secret put API_KEY     # Set secret
npx wrangler secret list            # List secrets

# KV Management
npx wrangler kv:key list --namespace-id=xxx
npx wrangler kv:key get --namespace-id=xxx "key"
npx wrangler kv:key delete --namespace-id=xxx "key"

# Logs
npx wrangler tail                   # Real-time logs
npx wrangler tail --format=pretty   # Formatted output

Error Codes

| Code | Meaning |

|------|---------|

| 1101 | Worker threw exception |

| 1102 | CPU time limit exceeded |

| 1015 | Rate limited by Cloudflare |

| 524 | Origin timeout (>100s) |

Quick Reference

// Get client IP
const ip = request.headers.get('CF-Connecting-IP');

// Get country
const country = request.cf?.country;

// Background task (won't block response)
ctx.waitUntil(doBackgroundWork());

// Streaming response
return new Response(readableStream, {
  headers: { 'Content-Type': 'text/event-stream' }
});

// Proxy request
const response = await fetch(upstreamUrl, request);
return new Response(response.body, response);

Anti-Patterns

❌ Awaiting KV writes in hot path

// ❌ ANTI-PATTERN: Blocks response on cache write
async function handler(request: Request, env: Env) {
  const data = await fetchData();
  await env.CACHE.put('key', data);  // Unnecessary wait!
  return json(data);
}

// ✅ CORRECT: Background write with waitUntil
async function handler(request: Request, env: Env, ctx: ExecutionContext) {
  const data = await fetchData();
  ctx.waitUntil(env.CACHE.put('key', data));  // Non-blocking
  return json(data);
}

❌ Missing CORS handling

// ❌ ANTI-PATTERN: No preflight handling = broken browser requests
export default {
  async fetch(request: Request) {
    return json({ data: 'hello' });  // OPTIONS requests fail!
  }
}

// ✅ CORRECT: Handle OPTIONS preflight
export default {
  async fetch(request: Request) {
    if (request.method === 'OPTIONS') {
      return new Response(null, { status: 204, headers: CORS_HEADERS });
    }
    return json({ data: 'hello' });
  }
}

❌ Secrets in wrangler.toml

# ❌ ANTI-PATTERN: Secrets in config (committed to git!)
[vars]
API_KEY = "sk-live-xxxxx"

# ✅ CORRECT: Use wrangler secret
# Run: npx wrangler secret put API_KEY
# Access: env.API_KEY

❌ Ignoring KV eventual consistency

// ❌ ANTI-PATTERN: Read immediately after write
await env.KV.put('count', String(newCount));
const verify = await env.KV.get('count');  // May return old value!

// ✅ CORRECT: Trust write succeeded, or use Durable Objects for consistency
await env.KV.put('count', String(newCount));
return json({ count: newCount });  // Return what you wrote

❌ Blocking on external APIs without timeout

// ❌ ANTI-PATTERN: External API can hang your worker
const data = await fetch('https://slow-api.com/data');

// ✅ CORRECT: Add timeout with AbortController
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);
try {
  const data = await fetch('https://slow-api.com/data', {
    signal: controller.signal
  });
} finally {
  clearTimeout(timeout);
}

References

See /references/ for detailed guides:

kv-patterns.md - Advanced KV usage patterns
durable-objects.md - Real-time features with DO
debugging.md - Troubleshooting common issues

Other skills for the same job

different authors, same section of the catalogue

Azure Kubernetes Automatic Readiness

by microsoft

vendor ×3

Assess Kubernetes workloads and cluster configuration for AKS Automatic compatibility. Identifies incompatibilities, generates fixes, and guides migration from AKS Standard to AKS Automatic. WHEN: migrate to AKS Automatic, check AKS Automatic readiness, validate manifests for Automatic, assess cluster for Automatic compatibility, fix deployment for Automatic compatibility, identify AKS Automatic migration blockers, is my cluster ready for AKS Automatic.

Discovers available Azure OpenAI model capacity across regions and projects. Analyzes quota limits, compares availability, and recommends optimal deployment locations based on capacity requirements. USE FOR: find capacity, check quota, where can I deploy, capacity discovery, best region for capacity, multi-project capacity search, quota analysis, model availability, region comparison, check TPM availability. DO NOT USE FOR: actual deployment (hand off to preset or customize after discovery), quota increase requests (direct user to Azure Portal), listing existing deployments.

Interactive guided deployment flow for Azure OpenAI models with full customization control. Step-by-step selection of model version, SKU (GlobalStandard/Standard/ProvisionedManaged), capacity, RAI policy (content filter), and advanced options (dynamic quota, priority processing, spillover). USE FOR: custom deployment, customize model deployment, choose version, select SKU, set capacity, configure content filter, RAI policy, deployment options, detailed deployment, advanced deployment, PTU deployment, provisioned throughput. DO NOT USE FOR: quick deployment to optimal region (use preset).

Unified Azure OpenAI model deployment skill with intelligent intent-based routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI policy), and capacity discovery across regions and projects. USE FOR: deploy model, deploy gpt, create deployment, model deployment, deploy openai model, set up model, provision model, find capacity, check model availability, where can I deploy, best region for model, capacity analysis. DO NOT USE FOR: listing existing deployments (use foundry_models_deployments_list MCP tool), deleting deployments, agent creation (use agent/create), project creation (use project/create).

Intelligently deploys Azure OpenAI models to optimal regions by analyzing capacity across all available regions. Automatically checks current region first and shows alternatives if needed. USE FOR: quick deployment, optimal region, best region, automatic region selection, fast setup, multi-region capacity check, high availability deployment, deploy to best location. DO NOT USE FOR: custom SKU selection (use customize), specific version selection (use customize), custom capacity configuration (use customize), PTU deployments (use customize).

This skill should be used when working with LaminDB, an open-source data framework for biology that makes data queryable, traceable, reproducible, and FAIR. Use when managing biological datasets (scRNA-seq, spatial, flow cytometry, etc.), tracking computational workflows, curating and validating data with biological ontologies, building data lakehouses, or ensuring data lineage and reproducibility in biological research. Covers data management, annotation, ontologies (genes, cell types, diseases, tissues), schema validation, integrations with workflow managers (Nextflow, Snakemake) and MLOps platforms (W&B, MLflow), and deployment strategies.

Latch platform for bioinformatics workflows. Build pipelines with Latch SDK, @workflow/@task decorators, deploy serverless workflows, LatchFile/LatchDir, Nextflow/Snakemake integration.

Run Python code in the cloud with serverless containers, GPUs, and autoscaling. Use when deploying ML models, running batch processing jobs, scheduling compute-intensive tasks, or serving APIs that require GPU acceleration or dynamic scaling.

17k tokens

How to use it

Copy the folder

Take curiositech/cloudflare-worker-dev from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

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.

Install what it needs

The instructions reference npx. Without those the skill loads but fails at the first command.