skills Documentation

Technical Documentation: openai/skills

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[!IMPORTANT]
This repository is deprecated. For current Codex skill and plugin examples, use the OpenAI Plugins repository. If you want to add your own skills to Codex, follow the Build plugins guide, which includes instructions for creating a skill-only plugin.

Agent Skills

Agent Skills are folders of instructions, scripts, and resources that AI agents can discover and use to perform at specific tasks. Write once, use everywhere.

Codex uses skills to help package capabilities that teams and individuals can use to complete specific tasks in a repeatable way. This repository catalogs skills for use and distribution with Codex.

Learn more:

• Using skills in Codex
• Create custom skills in Codex
• Agent Skills open standard

Installing a skill Copy Chapter

Skills in .system are automatically installed in the latest version of Codex.

To install curated or experimental skills, you can use the $skill-installer inside Codex.

Curated skills can be installed by name (defaults to skills/.curated):

$skill-installer gh-address-comments

For experimental skills, specify the skill folder. For example:

$skill-installer install the create-plan skill from the .experimental folder

Or provide the GitHub directory URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

After installing a skill, restart Codex to pick up new skills.

License Copy Chapter

The license of an individual skill can be found directly inside the skill's directory inside the LICENSE.txt file.

Overview (`skills/.curated/notion-knowledge-capture/evaluations/README.md`) Copy Section

Knowledge Capture Skill Evaluations

Evaluation scenarios for testing the Knowledge Capture skill across different Codex models.

Purpose Copy Chapter

These evaluations ensure the Knowledge Capture skill:

• Correctly identifies content types (how-to guides, FAQs, decision records, wikis)
• Extracts relevant information from conversations
• Structures content appropriately for each type
• Searches and places content in the right Notion location
• Works consistently across Haiku, Sonnet, and Opus

Evaluation Files Copy Chapter

conversation-to-wiki.json Copy Section

Tests capturing conversation content as a how-to guide for the team wiki.

Scenario: Save deployment discussion to wiki
Key Behaviors:

• Extracts steps, gotchas, and best practices from conversation
• Identifies content as How-To Guide
• Structures with proper sections (Overview, Prerequisites, Steps, Troubleshooting)
• Searches for team wiki location
• Preserves technical details (commands, configs)

decision-record.json Copy Section

Tests capturing architectural or technical decisions with full context.

Scenario: Document database migration decision
Key Behaviors:

• Extracts decision context, alternatives, and rationale
• Follows decision record structure (Context, Decision, Alternatives, Consequences)
• Captures both selected and rejected options with reasoning
• Places in decision log or ADR database
• Links to related technical documentation

Running Evaluations Copy Chapter

1. Enable the knowledge-capture skill
2. Submit the query from the evaluation file
3. Provide conversation context as specified
4. Verify all expected behaviors are met
5. Check success criteria for quality
6. Test with Haiku, Sonnet, and Opus

Expected Skill Behaviors Copy Chapter

Knowledge Capture evaluations should verify:

Content Extraction Copy Section

• Accurately captures key points from conversation context
• Preserves specific technical details, not generic placeholders
• Maintains context and nuance from discussion

Content Type Selection Copy Section

• Correctly identifies appropriate content type (how-to, FAQ, decision record, wiki page)
• Uses matching structure from reference documentation
• Applies proper Notion markdown formatting

Notion Integration Copy Section

• Searches for appropriate target location (wiki, decision log, etc.)
• Creates well-structured pages with clear titles
• Uses proper parent placement
• Includes discoverable titles and metadata

Quality Standards Copy Section

• Content is actionable and future-reference ready
• Technical accuracy is preserved
• Organization aids discoverability
• Formatting enhances readability

Creating New Evaluations Copy Chapter

When adding Knowledge Capture evaluations:

1. Use realistic conversation content - Include actual technical details, decisions, or processes
2. Test different content types - How-to guides, FAQs, decision records, meeting notes, learnings
3. Vary complexity - Simple captures vs. complex technical discussions
4. Test discovery - Finding the right wiki section or database
5. Include edge cases - Unclear content types, minimal context, overlapping categories

Example Success Criteria Copy Chapter

Good (specific, testable):

• "Structures content using How-To format with numbered steps"
• "Preserves exact bash commands from conversation"
• "Creates page with title format 'How to [Action]'"
• "Places in Engineering Wiki → Deployment section"

Bad (vague, untestable):

• "Creates good documentation"
• "Uses appropriate structure"
• "Saves to the right place"

Overview (`skills/.curated/notion-meeting-intelligence/evaluations/README.md`) Copy Section

Meeting Intelligence Skill Evaluations

Evaluation scenarios for testing the Meeting Intelligence skill across different Codex models.

Purpose Copy Chapter

These evaluations ensure the Meeting Intelligence skill:

• Gathers context from Notion workspace
• Enriches with Codex research appropriately
• Creates both internal pre-reads and external agendas
• Distinguishes between Notion facts and Codex insights
• Works consistently across Haiku, Sonnet, and Opus

Evaluation Files Copy Chapter

decision-meeting-prep.json Copy Section

Tests preparation for a decision-making meeting.

Scenario: Prep for database migration decision meeting
Key Behaviors:

• Searches Notion for migration context (specs, discussions, options)
• Fetches 2-3 relevant pages
• Enriches with Codex research (decision frameworks, migration best practices)
• Creates comprehensive internal pre-read with recommendation
• Creates clean, professional external agenda
• Clearly distinguishes Notion facts from Codex insights
• Cross-links both documents

status-meeting-prep.json Copy Section

Tests preparation for a status update or review meeting.

Scenario: Prep for project status review
Key Behaviors:

• Gathers project metrics and progress from Notion
• Fetches relevant pages (roadmap, tasks, milestones)
• Adds Codex context (industry benchmarks, best practices)
• Creates internal pre-read with honest assessment
• Creates external agenda with structured flow
• Includes source citations using mention-page tags
• Time-boxes agenda items

Running Evaluations Copy Chapter

1. Enable the meeting-intelligence skill
2. Submit the query from the evaluation file
3. Verify the skill searches Notion first (not Codex research)
4. Check that TWO documents are created (internal + external)
5. Verify Codex enrichment adds value without replacing Notion content
6. Test with Haiku, Sonnet, and Opus

Expected Skill Behaviors Copy Chapter

Meeting Intelligence evaluations should verify:

Notion Context Gathering Copy Section

• Searches workspace for relevant context first
• Fetches specific pages (not generic)
• Extracts key information from Notion content
• Cites sources using mention-page tags

Codex Research Integration Copy Section

• Adds industry context, frameworks, or best practices
• Enrichment is relevant and valuable (not filler)
• Clearly distinguishes Notion facts from Codex insights
• Research complements (doesn't replace) Notion content

Two-Document Creation Copy Section

• Internal Pre-Read: Comprehensive, includes strategy, recommendations, detailed pros/cons
• External Agenda: Professional, focused on meeting flow, no internal strategy
• Both documents are clearly labeled
• Documents are cross-linked

Document Quality Copy Section

• Pre-read follows structure: Overview → Background → Current Status → Context & Insights → Discussion Points
• Agenda follows structure: Details → Objective → Agenda Items (with times) → Decisions → Actions → Resources
• Titles include date or meeting context
• Content is actionable and meeting-ready

Creating New Evaluations Copy Chapter

When adding Meeting Intelligence evaluations:

1. Test different meeting types - Decision, status, brainstorm, 1:1, sprint planning, retrospective
2. Vary complexity - Simple updates vs. complex strategic decisions
3. Test with/without Notion content - Rich workspace vs. minimal existing pages
4. Verify enrichment value - Is Codex research genuinely helpful?
5. Check internal/external distinction - Is sensitive info kept in pre-read only?

Example Success Criteria Copy Chapter

Good (specific, testable):

• "Creates TWO documents (internal pre-read + external agenda)"
• "Internal pre-read marked 'INTERNAL ONLY' or 'For team only'"
• "Cites at least 2-3 Notion pages using mention-page tags"
• "Agenda includes time allocations for each section"
• "Codex enrichment includes decision frameworks or best practices"

Bad (vague, untestable):

• "Creates meeting materials"
• "Gathers context effectively"
• "Prepares well"

Overview (`skills/.curated/notion-research-documentation/evaluations/README.md`) Copy Section

Research & Documentation Skill Evaluations

Evaluation scenarios for testing the Research & Documentation skill across different Codex models.

Purpose Copy Chapter

These evaluations ensure the Research & Documentation skill:

• Searches across Notion workspace effectively
• Synthesizes information from multiple sources
• Selects appropriate research report format
• Creates comprehensive documentation with proper citations
• Works consistently across Haiku, Sonnet, and Opus

Evaluation Files Copy Chapter

basic-research.json Copy Section

Tests basic research workflow with synthesis across multiple Notion pages.

Scenario: Research Q4 product roadmap and create summary
Key Behaviors:

• Searches Notion for roadmap-related pages
• Fetches multiple relevant pages (roadmap, product docs, meeting notes)
• Synthesizes information from different sources
• Selects appropriate format (Research Summary)
• Includes citations linking back to source pages
• Creates structured document with clear sections

research-to-database.json Copy Section

Tests creating research documentation in a Notion database with properties.

Scenario: Research competitor landscape and save to Research database
Key Behaviors:

• Searches for existing competitive intelligence in Notion
• Identifies Research database as target
• Fetches database schema to understand properties
• Creates page with correct property values (Research Type, Status, Date, etc.)
• Structures content with comparison format
• Includes source citations for both Notion pages and external research

Running Evaluations Copy Chapter

1. Enable the research-documentation skill
2. Submit the query from the evaluation file
3. Verify the skill searches Notion workspace comprehensively
4. Check that multiple source pages are fetched and synthesized
5. Verify appropriate format is selected (Research Summary, Comprehensive Report, Quick Brief, Comparison)
6. Confirm citations link back to sources
7. Test with Haiku, Sonnet, and Opus

Expected Skill Behaviors Copy Chapter

Research & Documentation evaluations should verify:

Notion Search & Synthesis Copy Section

• Searches workspace with relevant queries
• Fetches multiple source pages (3-5+)
• Synthesizes information across sources
• Identifies patterns and insights
• Handles conflicting information appropriately

Format Selection Copy Section

• Chooses correct format based on scope and depth:
  • Research Summary: Quick overview with key findings
  • Comprehensive Report: Deep analysis with multiple sections
  • Quick Brief: Fast facts and takeaways
  • Comparison: Side-by-side analysis
• Applies format structure consistently
• Uses appropriate sections and headings

Citation & Attribution Copy Section

• Includes citations for all Notion sources
• Uses mention-page tags: <mention-page url="...">
• Attributes findings to specific sources
• Distinguishes between Notion content and Codex research
• Links related documents

Document Quality Copy Section

• Title clearly indicates research topic and date
• Executive summary or key findings upfront
• Organized with clear hierarchy
• Actionable insights and recommendations
• Appropriate depth for the query

Creating New Evaluations Copy Chapter

When adding Research & Documentation evaluations:

1. Test different research types - Product research, competitive analysis, technical investigation, market research
2. Vary source count - Synthesis of 2-3 pages vs. 10+ pages
3. Test format selection - Does it choose the right format for the scope?
4. Include database targets - Not just standalone pages
5. Test citation accuracy - Are all sources properly attributed?
6. Cross-workspace search - Testing search across teamspaces if applicable

Example Success Criteria Copy Chapter

Good (specific, testable):

• "Searches Notion for 'roadmap' and 'Q4' and 'product'"
• "Fetches at least 3 different source pages"
• "Includes citation for each key finding using mention-page tags"
• "Creates page with title format 'Research: [Topic] - [Date]'"
• "Uses Research Summary format with sections: Executive Summary → Key Findings → Details → Recommendations → Sources"

Bad (vague, untestable):

• "Searches Notion effectively"
• "Creates comprehensive research"
• "Uses sources appropriately"
• "Good documentation"

Overview (`skills/.curated/notion-spec-to-implementation/evaluations/README.md`) Copy Section

Spec to Implementation Skill Evaluations

Evaluation scenarios for testing the Spec to Implementation skill across different Codex models.

Purpose Copy Chapter

These evaluations ensure the Spec to Implementation skill:

• Finds and parses specification pages accurately
• Breaks down specs into actionable implementation plans
• Creates tasks that Codex can implement with clear acceptance criteria
• Tracks progress and updates implementation status
• Works consistently across Haiku, Sonnet, and Opus

Evaluation Files Copy Chapter

basic-spec-implementation.json Copy Section

Tests basic workflow of turning a spec into an implementation plan.

Scenario: Implement user authentication feature from spec
Key Behaviors:

• Searches for and finds the authentication spec page
• Fetches spec and extracts requirements
• Parses requirements into phases (setup, core features, polish)
• Creates implementation plan page linked to original spec
• Breaks down into clear phases with deliverables
• Includes timeline and dependencies

spec-to-tasks.json Copy Section

Tests creating concrete tasks from a specification in a task database.

Scenario: Create tasks from API redesign spec
Key Behaviors:

• Finds spec page in Notion
• Extracts specific requirements and acceptance criteria
• Searches for or creates task database
• Fetches task database schema
• Creates multiple tasks with proper properties (Status, Priority, Sprint, etc.)
• Each task has clear title, description, and acceptance criteria
• Tasks have dependencies where appropriate
• Links all tasks back to original spec

Running Evaluations Copy Chapter

1. Enable the spec-to-implementation skill
2. Submit the query from the evaluation file
3. Verify the skill finds the spec page via search
4. Check that requirements are accurately parsed
5. Confirm implementation plan is created with phases
6. Verify tasks have clear, implementable acceptance criteria
7. Check that tasks link back to spec
8. Test with Haiku, Sonnet, and Opus

Expected Skill Behaviors Copy Chapter

Spec to Implementation evaluations should verify:

Spec Discovery & Parsing Copy Section

• Searches Notion for specification pages
• Fetches complete spec content
• Extracts all requirements accurately
• Identifies technical dependencies
• Understands acceptance criteria
• Notes any ambiguities or missing details

Implementation Planning Copy Section

• Creates implementation plan page
• Breaks work into logical phases:
  • Phase 1: Foundation/Setup
  • Phase 2: Core Implementation
  • Phase 3: Testing & Polish
• Includes timeline estimates
• Identifies dependencies between phases
• Links back to original spec

Task Creation Copy Section

• Finds or identifies task database
• Fetches database schema for property names
• Creates tasks with correct properties
• Each task has:
  • Clear, specific title
  • Context and description
  • Acceptance criteria (checklist format)
  • Appropriate priority and status
  • Link to spec page
• Tasks are right-sized (not too big, not too small)
• Dependencies between tasks are noted

Progress Tracking Copy Section

• Implementation plan includes progress markers
• Tasks can be updated as work progresses
• Status updates link to completed work
• Blockers or changes are noted

Creating New Evaluations Copy Chapter

When adding Spec to Implementation evaluations:

1. Test different spec types - Features, migrations, refactors, API changes, UI components
2. Vary complexity - Simple 1-phase vs. complex multi-phase implementations
3. Test task granularity - Does it create appropriately-sized tasks?
4. Include edge cases - Vague specs, conflicting requirements, missing details
5. Test database integration - Creating tasks in existing task databases with various schemas
6. Progress tracking - Updating implementation plans as tasks complete

Example Success Criteria Copy Chapter

Good (specific, testable):

• "Searches Notion for spec page using feature name"
• "Creates implementation plan with 3 phases: Setup → Core → Polish"
• "Creates 5-8 tasks in task database with properties: Task (title), Status, Priority, Sprint"
• "Each task has acceptance criteria in checklist format (- [ ] ...)"
• "Tasks link back to spec using mention-page tag"
• "Task titles are specific and actionable (e.g., 'Create login API endpoint' not 'Authentication')"

Bad (vague, untestable):

• "Creates good implementation plan"
• "Tasks are well-structured"
• "Breaks down spec appropriately"
• "Links to spec"

Overview (`skills/.curated/cloudflare-deploy/references/agents-sdk/README.md`) Copy Section

Cloudflare Agents SDK

Cloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.

Core Value Copy Chapter

Build stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.

When to Use Copy Chapter

• Persistent state + memory required
• Real-time WebSocket connections
• Long-running workflows (minutes/hours)
• Chat interfaces with AI models
• Scheduled/recurring tasks with state
• DB queries with agent state

What Type of Agent? Copy Chapter

Quick Start Copy Chapter

AI Chat Agent:

import { AIChatAgent } from "agents";
import { openai } from "@ai-sdk/openai";

export class ChatAgent extends AIChatAgent<Env> {
  async onChatMessage(onFinish) {
    return this.streamText({
      model: openai("gpt-4"),
      messages: this.messages,
      onFinish,
    });
  }
}

Base Agent:

import { Agent } from "agents";

export class MyAgent extends Agent<Env> {
  onStart() {
    this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;
  }
  
  async onRequest(request: Request) {
    return Response.json({ state: this.state });
  }
}

Reading Order Copy Chapter

Package Entry Points Copy Chapter

In This Reference Copy Chapter

• configuration.md - SDK setup, wrangler config, routing
• api.md - Agent classes, lifecycle, client hooks
• patterns.md - Common workflows, best practices
• gotchas.md - Common issues, limits

See Also Copy Chapter

• durable-objects - Agent infrastructure
• d1 - External database integration
• workers-ai - AI model integration
• vectorize - Vector search for RAG patterns

Overview (`skills/.curated/cloudflare-deploy/references/ai-gateway/README.md`) Copy Section

Cloudflare AI Gateway

Expert guidance for implementing Cloudflare AI Gateway - a universal gateway for AI model providers with analytics, caching, rate limiting, and routing capabilities.

When to Use This Reference Copy Chapter

• Setting up AI Gateway for any AI provider (OpenAI, Anthropic, Workers AI, etc.)
• Implementing caching, rate limiting, or request retry/fallback
• Configuring dynamic routing with A/B testing or model fallbacks
• Managing provider API keys securely with BYOK
• Adding security features (guardrails, DLP)
• Setting up observability with logging and custom metadata
• Debugging AI Gateway requests or optimizing configurations

Quick Start Copy Chapter

What's your setup?

• Using Vercel AI SDK → Pattern 1 (recommended) - see sdk-integration.md
• Using OpenAI SDK → Pattern 2 - see sdk-integration.md
• Cloudflare Worker + Workers AI → Pattern 3 - see sdk-integration.md
• Direct HTTP (any language) → Pattern 4 - see configuration.md
• Framework (LangChain, etc.) → See sdk-integration.md

Pattern 1: Vercel AI SDK (Recommended) Copy Chapter

Most modern pattern using official ai-gateway-provider package with automatic fallbacks.

import { createAiGateway } from 'ai-gateway-provider';
import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const gateway = createAiGateway({
  accountId: process.env.CF_ACCOUNT_ID,
  gateway: process.env.CF_GATEWAY_ID,
});

const openai = createOpenAI({ 
  apiKey: process.env.OPENAI_API_KEY 
});

// Single model
const { text } = await generateText({
  model: gateway(openai('gpt-4o')),
  prompt: 'Hello'
});

// Automatic fallback array
const { text } = await generateText({
  model: gateway([
    openai('gpt-4o'),              // Try first
    anthropic('claude-sonnet-4-5'), // Fallback
  ]),
  prompt: 'Hello'
});

Install: npm install ai-gateway-provider ai @ai-sdk/openai @ai-sdk/anthropic

Pattern 2: OpenAI SDK Copy Chapter

Drop-in replacement for OpenAI API with multi-provider support.

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat`,
  defaultHeaders: {
    'cf-aig-authorization': `Bearer ${cfToken}` // For authenticated gateways
  }
});

// Switch providers by changing model format: {provider}/{model}
const response = await client.chat.completions.create({
  model: 'openai/gpt-4o', // or 'anthropic/claude-sonnet-4-5'
  messages: [{ role: 'user', content: 'Hello!' }]
});

Pattern 3: Workers AI Binding Copy Chapter

For Cloudflare Workers using Workers AI.

export default {
  async fetch(request, env, ctx) {
    const response = await env.AI.run(
      '@cf/meta/llama-3-8b-instruct',
      { messages: [{ role: 'user', content: 'Hello!' }] },
      { 
        gateway: { 
          id: 'my-gateway',
          metadata: { userId: '123', team: 'engineering' }
        } 
      }
    );
    
    return Response.json(response);
  }
};

Headers Quick Reference Copy Chapter

In This Reference Copy Chapter

Reading Order Copy Chapter

Architecture Copy Chapter

AI Gateway acts as a proxy between your application and AI providers:

Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.)
         ↓
    Analytics, Caching, Rate Limiting, Logging

Key URL patterns:

• Unified API (OpenAI-compatible): https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions
• Provider-specific: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}
• Dynamic routes: Use route name instead of model: dynamic/{route-name}

Gateway Types Copy Chapter

1. Unauthenticated Gateway: Open access (not recommended for production)
2. Authenticated Gateway: Requires cf-aig-authorization header with Cloudflare API token (recommended)

Provider Authentication Options Copy Chapter

1. Unified Billing: Use AI Gateway billing to pay for inference (keyless mode - no provider API key needed)
2. BYOK (Store Keys): Store provider API keys in Cloudflare dashboard
3. Request Headers: Include provider API key in each request

Related Skills Copy Chapter

• Workers AI - For env.AI.run() details
• Agents SDK - For stateful AI patterns
• Vectorize - For RAG patterns with embeddings

Resources Copy Chapter

• Official Docs
• API Reference
• Provider Guides
• Discord Community

Overview (`skills/.curated/cloudflare-deploy/references/ai-search/README.md`) Copy Section

Cloudflare AI Search Reference

Expert guidance for implementing Cloudflare AI Search (formerly AutoRAG), Cloudflare's managed semantic search and RAG service.

Overview Copy Chapter

AI Search is a managed RAG (Retrieval-Augmented Generation) pipeline that combines:

• Automatic semantic indexing of your content
• Vector similarity search
• Built-in LLM generation

Key value propositions:

• Zero vector management - No manual embedding, indexing, or storage
• Auto-indexing - Content automatically re-indexed every 6 hours
• Built-in generation - Optional AI response generation from retrieved context
• Multi-source - Index from R2 buckets or website crawls

Data source options:

• R2 bucket - Index files from Cloudflare R2 (supports MD, TXT, HTML, PDF, DOC, CSV, JSON)
• Website - Crawl and index website content (requires Cloudflare-hosted domain)

Indexing lifecycle:

• Automatic 6-hour refresh cycle
• Manual "Force Sync" available (30s rate limit)
• Not designed for real-time updates

Quick Start Copy Chapter

1. Create AI Search instance in dashboard:

• Go to Cloudflare Dashboard → AI Search → Create
• Choose data source (R2 or website)
• Configure instance name and settings

2. Configure Worker:

// wrangler.jsonc
{
  "ai": {
    "binding": "AI"
  }
}

3. Use in Worker:

export default {
  async fetch(request, env) {
    const answer = await env.AI.autorag("my-search-instance").aiSearch({
      query: "How do I configure caching?",
      model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
    });
    
    return Response.json({ answer: answer.response });
  }
};

When to Use AI Search Copy Chapter

AI Search vs Vectorize Copy Section

AI Search vs Direct Workers AI Copy Section

search() vs aiSearch() Copy Section

Real-time Updates Consideration Copy Section

AI Search is NOT ideal if:

• Need real-time content updates (<6 hours)
• Content changes multiple times per hour
• Strict freshness requirements

AI Search IS ideal if:

• Content relatively stable (docs, policies, knowledge bases)
• 6-hour refresh acceptable
• Prefer zero-ops over real-time

Platform Limits Copy Chapter

Reading Order Copy Chapter

Navigate these references based on your task:

In This Reference Copy Chapter

• api.md - API endpoints, methods, TypeScript interfaces
• configuration.md - Setup, data sources, wrangler config
• patterns.md - Common patterns, decision guidance, code examples
• gotchas.md - Troubleshooting, code-level gotchas, limits

See Also Copy Chapter

• Cloudflare AI Search Docs
• Workers AI Docs
• Vectorize Docs

Overview (`skills/.curated/cloudflare-deploy/references/analytics-engine/README.md`) Copy Section

Cloudflare Workers Analytics Engine Reference

Expert guidance for implementing unlimited-cardinality analytics at scale using Cloudflare Workers Analytics Engine.

What is Analytics Engine? Copy Chapter

Time-series analytics database designed for high-cardinality data (millions of unique dimensions). Write data points from Workers, query via SQL API. Use for:

• Custom user-facing analytics dashboards
• Usage-based billing & metering
• Per-customer/per-feature monitoring
• High-frequency instrumentation without performance impact

Key Capability: Track metrics with unlimited unique values (e.g., millions of user IDs, API keys) without performance degradation.

Core Concepts Copy Chapter

Reading Order Copy Chapter

When to Use Analytics Engine Copy Chapter

Need to track metrics? → Yes
  ↓
Millions of unique dimension values? → Yes
    ↓
  Need real-time queries? → Yes
      ↓
    Use Analytics Engine ✓

Alternative scenarios:
- Low cardinality (<10k unique values) → Workers Analytics (free tier)
- Complex joins/relations → D1 Database
- Logs/debugging → Tail Workers (logpush)
- External tools → Send to external analytics (Datadog, etc.)

Quick Start Copy Chapter

1. Add binding to wrangler.jsonc:

{
  "analytics_engine_datasets": [
    { "binding": "ANALYTICS", "dataset": "my_events" }
  ]
}

2. Write data points (fire-and-forget, no await):

env.ANALYTICS.writeDataPoint({
  blobs: ["/api/users", "GET", "200"],
  doubles: [145.2, 1],  // latency_ms, count
  indexes: [customerId]
});

3. Query via SQL API (HTTP):

SELECT blob1, SUM(double2) AS total_requests
FROM my_events
WHERE index1 = 'customer_123'
  AND timestamp >= NOW() - INTERVAL '7' DAY
GROUP BY blob1
ORDER BY total_requests DESC

In This Reference Copy Chapter

• configuration.md - Setup, bindings, TypeScript types, limits
• api.md - writeDataPoint(), SQL API, query syntax
• patterns.md - Use cases, examples, anti-patterns
• gotchas.md - Sampling, index selection, troubleshooting

See Also Copy Chapter

• Cloudflare Analytics Engine Docs

Overview (`skills/.curated/cloudflare-deploy/references/api-shield/README.md`) Copy Section

Cloudflare API Shield Reference

Expert guidance for API Shield - comprehensive API security suite for discovery, protection, and monitoring.

Reading Order Copy Chapter

Feature Selection Copy Chapter

What protection do you need?

├─ Validate request/response structure → Schema Validation 2.0 (configuration.md)
├─ Verify auth tokens → JWT Validation (configuration.md)
├─ Client certificates → mTLS (configuration.md)
├─ Detect BOLA attacks → BOLA Detection (patterns.md)
├─ Track auth coverage → Auth Posture (patterns.md)
├─ Stop volumetric abuse → Abuse Detection (patterns.md)
└─ Discover shadow APIs → API Discovery (api.md)

In This Reference Copy Chapter

• configuration.md - Setup, session identifiers, rules, token/mTLS configs
• api.md - Endpoint management, discovery, validation APIs, GraphQL operations
• patterns.md - Common patterns, progressive rollout, OWASP mappings, workflows
• gotchas.md - Troubleshooting, false positives, performance, best practices

Quick Start Copy Chapter

API Shield: Enterprise-grade API security (Discovery, Schema Validation 2.0, JWT, mTLS, BOLA Detection, Auth Posture). Available as Enterprise add-on with preview access.

See Also Copy Chapter

• API Shield Docs
• API Reference
• OWASP API Security Top 10

Overview (`skills/.curated/cloudflare-deploy/references/api/README.md`) Copy Section

Cloudflare API Integration

Guide for working with Cloudflare's REST API - authentication, SDK usage, common patterns, and troubleshooting.

Quick Decision Tree Copy Chapter

How are you calling the Cloudflare API?
├─ From Workers runtime → Use bindings, not REST API (see ../bindings/)
├─ Server-side (Node/Python/Go) → Official SDK (see api.md)
├─ CLI/scripts → Wrangler or curl (see configuration.md)
├─ Infrastructure-as-code → See ../pulumi/ or ../terraform/
└─ One-off requests → curl examples (see api.md)

SDK Selection Copy Chapter

All SDKs are Stainless-generated from OpenAPI spec (consistent APIs).

Authentication Methods Copy Chapter

Always use API tokens for new projects.

Rate Limits Copy Chapter

Reading Order Copy Chapter

In This Reference Copy Chapter

• api.md - SDK client initialization, pagination, error handling, examples
• configuration.md - Environment variables, SDK config, Wrangler setup
• patterns.md - Real-world patterns, batch operations, workflows
• gotchas.md - Rate limits, SDK-specific issues, troubleshooting

See Also Copy Chapter

• Cloudflare API Docs
• Bindings Reference - Workers runtime bindings (preferred over REST API)
• Wrangler Reference - CLI tool for Cloudflare development

Overview (`skills/.curated/cloudflare-deploy/references/argo-smart-routing/README.md`) Copy Section

Cloudflare Argo Smart Routing Skill Reference

Overview Copy Chapter

Cloudflare Argo Smart Routing is a performance optimization service that detects real-time network issues and routes web traffic across the most efficient network path. It continuously monitors network conditions and intelligently routes traffic through the fastest, most reliable routes in Cloudflare's network.

Note on Smart Shield: Argo Smart Routing is being integrated into Cloudflare's Smart Shield product for enhanced DDoS protection and performance. Existing Argo customers maintain full functionality with gradual migration to Smart Shield features.

Quick Start Copy Chapter

Enable via cURL Copy Section

curl -X PATCH "https://api.cloudflare.com/client/v4/zones/{zone_id}/argo/smart_routing" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "on"}'

Enable via TypeScript SDK Copy Section

import Cloudflare from 'cloudflare';

const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN });

const result = await client.argo.smartRouting.edit({
  zone_id: 'your-zone-id',
  value: 'on',
});

console.log(`Argo enabled: ${result.value}`);

Core Concepts Copy Chapter

What It Does Copy Section

• Intelligent routing: Detects congestion, outages, packet loss in real-time
• Global optimization: Routes across 300+ Cloudflare data centers
• Automatic failover: Switches paths when issues detected (typically <1s)
• Works with existing setup: No origin changes required

Billing Model Copy Section

• Usage-based: Charged per GB of traffic (excluding DDoS/WAF mitigated traffic)
• Requires billing configuration before enabling
• Available on Enterprise+ plans (check zone eligibility)

When to Use Copy Section

• High-traffic production sites with global user base
• Latency-sensitive applications (APIs, real-time services)
• Sites behind Cloudflare proxy (orange-clouded DNS records)
• Combined with Tiered Cache for maximum performance gains

When NOT to Use Copy Section

• Development/staging environments (cost control)
• Low-traffic sites (<1TB/month) where cost may exceed benefit
• Sites with primarily single-region traffic

Should I Enable Argo? Copy Chapter

Reading Order by Task Copy Chapter

In This Reference Copy Chapter

• api.md - API endpoints, SDK methods, error handling, Python/TypeScript examples
• configuration.md - Terraform setup, environment config, billing configuration
• patterns.md - Tiered Cache integration, Spectrum TCP apps, billing management, validation patterns
• gotchas.md - Common errors, permission issues, limits, best practices

See Also Copy Chapter

• Cloudflare Argo Smart Routing Docs
• Cloudflare Smart Shield
• Spectrum Documentation
• Tiered Cache

Overview (`skills/.curated/cloudflare-deploy/references/bindings/README.md`) Copy Section

Cloudflare Bindings Skill Reference

Expert guidance on Cloudflare Workers Bindings - the runtime APIs that connect Workers to Cloudflare platform resources.

What Are Bindings? Copy Chapter

Bindings are how Workers access Cloudflare resources (storage, compute, services) via the env object. They're configured in wrangler.jsonc, type-safe via TypeScript, and zero-overhead at runtime.

Reading Order Copy Chapter

1. This file - Binding catalog and selection guide
2. api.md - TypeScript types and env access patterns
3. configuration.md - Complete wrangler.jsonc examples
4. patterns.md - Best practices and common patterns
5. gotchas.md - Critical pitfalls and troubleshooting

Binding Catalog Copy Chapter

Storage Bindings Copy Section

Compute Bindings Copy Section

Platform Bindings Copy Section

Configuration Bindings Copy Section

Quick Selection Guide Copy Chapter

Need persistent storage?

• Key-value < 25MB → KV
• Files/objects → R2
• Relational data → D1
• Real-time coordination → Durable Objects

Need AI/compute?

• LLM inference → Workers AI
• Scraping/PDFs → Browser Rendering
• Call another Worker → Service binding

Need async processing?

• Background jobs → Queues

Need config?

• Public values → Environment Variables
• Secrets → Secrets (never commit)

Quick Start Copy Chapter

1. Add binding to wrangler.jsonc:

{
  "kv_namespaces": [
    { "binding": "MY_KV", "id": "your-kv-id" }
  ]
}

2. Generate types:

npx wrangler types

3. Access in Worker:

export default {
  async fetch(request, env, ctx) {
    await env.MY_KV.put('key', 'value');
    return new Response('OK');
  }
}

Type Safety Copy Chapter

Bindings are fully typed via wrangler types. See api.md for details.

Limits Copy Chapter

• 64 bindings max per Worker (all types combined)
• See gotchas.md for per-binding limits

Key Concepts Copy Chapter

Zero-overhead access: Bindings compiled into Worker, no network calls to access
Type-safe: Full TypeScript support via wrangler types
Per-environment: Different IDs for dev/staging/production
Secrets vs Vars: Secrets encrypted at rest, never in config files

See Also Copy Chapter

• Cloudflare Docs: Bindings
• Wrangler Configuration

Overview (`skills/.curated/cloudflare-deploy/references/bot-management/README.md`) Copy Section

Cloudflare Bot Management

Enterprise-grade bot detection, protection, and mitigation using ML/heuristics, bot scores, JavaScript detections, and verified bot handling.

Overview Copy Chapter

Bot Management provides multi-tier protection:

• Free (Bot Fight Mode): Auto-blocks definite bots, no config
• Pro/Business (Super Bot Fight Mode): Configurable actions, static resource protection, analytics groupings
• Enterprise (Bot Management): Granular 1-99 scores, WAF integration, JA3/JA4 fingerprinting, Workers API, Advanced Analytics

Quick Start Copy Chapter

# Dashboard: Security > Bots
# Enterprise: Deploy rule template
(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block
(cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge

What Do You Need? Copy Chapter

├─ Initial setup → configuration.md
│   ├─ Free tier → "Bot Fight Mode"
│   ├─ Pro/Business → "Super Bot Fight Mode"
│   └─ Enterprise → "Bot Management for Enterprise"
├─ Workers API integration → api.md
├─ WAF rules → patterns.md
├─ Debugging → gotchas.md
└─ Analytics → api.md#bot-analytics

Reading Order Copy Chapter

Core Concepts Copy Chapter

Bot Scores: 1-99 (1 = definitely automated, 99 = definitely human). Threshold: <30 indicates bot traffic. Enterprise gets granular 1-99; Pro/Business get groupings only.

Detection Engines: Heuristics (known fingerprints, assigns score=1), ML (majority of detections, supervised learning on billions of requests), Anomaly Detection (optional, baseline traffic analysis), JavaScript Detections (headless browser detection).

Verified Bots: Allowlisted good bots (search engines, AI crawlers) verified via reverse DNS or Web Bot Auth. Access via cf.bot_management.verified_bot or cf.verified_bot_category.

Platform Limits Copy Chapter

Basic Patterns Copy Chapter

// Workers: Check bot score
export default {
  async fetch(request: Request): Promise<Response> {
    const botScore = request.cf?.botManagement?.score;
    if (botScore && botScore < 30 && !request.cf?.botManagement?.verifiedBot) {
      return new Response('Bot detected', { status: 403 });
    }
    return fetch(request);
  }
};

# WAF: Block definite bots
(cf.bot_management.score eq 1 and not cf.bot_management.verified_bot)

# WAF: Protect sensitive endpoints
(cf.bot_management.score lt 50 and http.request.uri.path in {"/login" "/checkout"} and not cf.bot_management.verified_bot)

In This Reference Copy Chapter

• configuration.md - Product tiers, WAF rule setup, JavaScript Detections, ML auto-updates
• api.md - Workers BotManagement interface, WAF fields, JA4 Signals
• patterns.md - E-commerce, API protection, mobile app allowlisting, SEO-friendly handling
• gotchas.md - False positives/negatives, score=0 issues, JSD limitations, CSP requirements

See Also Copy Chapter

• waf - WAF custom rules for bot enforcement
• workers - Workers request.cf.botManagement API
• api-shield - API-specific bot protection

Overview (`skills/.curated/cloudflare-deploy/references/browser-rendering/README.md`) Copy Section

Cloudflare Browser Rendering Skill Reference

Description: Expert knowledge for Cloudflare Browser Rendering - control headless Chrome on Cloudflare's global network for browser automation, screenshots, PDFs, web scraping, testing, and content generation.

When to use: Any task involving Cloudflare Browser Rendering including: taking screenshots, generating PDFs, web scraping, browser automation, testing web applications, extracting structured data, capturing page metrics, or automating browser interactions.

Decision Tree Copy Chapter

REST API vs Workers Bindings Copy Section

Use REST API when:

• One-off, stateless tasks (screenshot, PDF, content fetch)
• No Workers infrastructure yet
• Simple integrations from external services
• Need quick prototyping without deployment

Use Workers Bindings when:

• Complex browser automation workflows
• Need session reuse for performance
• Multiple page interactions per request
• Custom scripting and logic required
• Building production applications

Puppeteer vs Playwright Copy Section

Use Puppeteer: Need CDP protocol access, Chrome-specific features, migration from existing Puppeteer code
Use Playwright: Modern selector APIs, cross-browser patterns, faster development

Tier Limits Summary Copy Chapter

*Subject to fair-use policy. See gotchas.md for details.

Reading Order Copy Chapter

New to Browser Rendering:

1. configuration.md - Setup and deployment
2. patterns.md - Common use cases with examples
3. api.md - API reference
4. gotchas.md - Avoid common pitfalls

Specific task:

• Setup/deployment → configuration.md
• API reference/endpoints → api.md
• Example code/patterns → patterns.md
• Debugging/troubleshooting → gotchas.md

REST API users:

• Start with api.md REST API section
• Check gotchas.md for rate limits

Workers users:

• Start with configuration.md
• Review patterns.md for session management
• Reference api.md for Workers Bindings

In This Reference Copy Chapter

• configuration.md - Setup, deployment, wrangler config, compatibility
• api.md - REST API endpoints + Workers Bindings (Puppeteer/Playwright)
• patterns.md - Common patterns, use cases, real examples
• gotchas.md - Troubleshooting, best practices, tier limits, common errors

See Also Copy Chapter

• Cloudflare Docs

Overview (`skills/.curated/cloudflare-deploy/references/c3/README.md`) Copy Section

C3 (create-cloudflare)

Official CLI for scaffolding Cloudflare Workers and Pages projects with templates, TypeScript, and instant deployment.

Quick Start Copy Chapter

# Interactive (recommended for first-time)
npm create cloudflare@latest my-app

# Worker (API/WebSocket/Cron)
npm create cloudflare@latest my-api -- --type=hello-world --ts

# Pages (static/SSG/full-stack)
npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages

Platform Decision Tree Copy Chapter

What are you building?

├─ API / WebSocket / Cron / Email handler
│   └─ Workers (default) - no --platform flag needed
│       npm create cloudflare@latest my-api -- --type=hello-world

├─ Static site / SSG / Documentation
│   └─ Pages - requires --platform=pages
│       npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages

├─ Full-stack app (Next.js/Remix/SvelteKit)
│   ├─ Need Durable Objects, Queues, or Workers-only features?
│   │   └─ Workers (default)
│   └─ Otherwise use Pages for git integration and branch previews
│       └─ Add --platform=pages

└─ Convert existing project
    └─ npm create cloudflare@latest . -- --type=pre-existing --existing-script=./src/worker.ts

Critical: Pages projects require --platform=pages flag. Without it, C3 defaults to Workers.

Interactive Flow Copy Chapter

When run without flags, C3 prompts in this order:

1. Project name - Directory to create (defaults to current dir with .)
2. Application type - hello-world, web-app, demo, pre-existing, remote-template
3. Platform - workers (default) or pages (for web apps only)
4. Framework - If web-app: next, remix, astro, react-router, solid, svelte, etc.
5. TypeScript - yes (recommended) or no
6. Git - Initialize repository? yes or no
7. Deploy - Deploy now? yes or no (requires wrangler login)

Installation Methods Copy Chapter

# NPM
npm create cloudflare@latest

# Yarn
yarn create cloudflare

# PNPM
pnpm create cloudflare@latest

In This Reference Copy Chapter

Reading Order Copy Chapter

Post-Creation Copy Chapter

cd my-app

# Local dev with hot reload
npm run dev

# Generate TypeScript types for bindings
npm run cf-typegen

# Deploy to Cloudflare
npm run deploy

See Also Copy Chapter

• workers/README.md - Workers runtime, bindings, APIs
• workers-ai/README.md - AI/ML models
• pages/README.md - Pages-specific features
• wrangler/README.md - Wrangler CLI beyond initial setup
• d1/README.md - SQLite database
• r2/README.md - Object storage

Overview (`skills/.curated/cloudflare-deploy/references/cache-reserve/README.md`) Copy Section

Cloudflare Cache Reserve

Persistent cache storage built on R2 for long-term content retention

Smart Shield Integration Copy Chapter

Cache Reserve is part of Smart Shield, Cloudflare's comprehensive security and performance suite:

• Smart Shield Advanced tier: Includes 2TB Cache Reserve storage
• Standalone purchase: Available separately if not using Smart Shield
• Migration: Existing standalone customers can migrate to Smart Shield bundles

Decision: Already on Smart Shield Advanced? Cache Reserve is included. Otherwise evaluate standalone purchase vs Smart Shield upgrade.

Overview Copy Chapter

Cache Reserve is Cloudflare's persistent, large-scale cache storage layer built on R2. It acts as the ultimate upper-tier cache, storing cacheable content for extended periods (30+ days) to maximize cache hits, reduce origin egress fees, and shield origins from repeated requests for long-tail content.

Core Concepts Copy Chapter

What is Cache Reserve? Copy Section

• Persistent storage layer: Built on R2, sits above tiered cache hierarchy
• Long-term retention: 30-day default retention, extended on each access
• Automatic operation: Works seamlessly with existing CDN, no code changes required
• Origin shielding: Dramatically reduces origin egress by serving cached content longer
• Usage-based pricing: Pay only for storage + read/write operations

Cache Hierarchy Copy Section

Visitor Request
    ↓
Lower-Tier Cache (closest to visitor)
    ↓ (on miss)
Upper-Tier Cache (closest to origin)
    ↓ (on miss)
Cache Reserve (R2 persistent storage)
    ↓ (on miss)
Origin Server

How It Works Copy Section

1. On cache miss: Content fetched from origin �� written to Cache Reserve + edge caches simultaneously
2. On edge eviction: Content may be evicted from edge cache but remains in Cache Reserve
3. On subsequent request: If edge cache misses but Cache Reserve hits → content restored to edge caches
4. Retention: Assets remain in Cache Reserve for 30 days since last access (configurable via TTL)

When to Use Cache Reserve Copy Chapter

Need persistent caching?
├─ High origin egress costs → Cache Reserve ✓
├─ Long-tail content (archives, media libraries) → Cache Reserve ✓
├─ Already using Smart Shield Advanced → Included! ✓
├─ Video streaming with seeking (range requests) → ✗ Not supported
├─ Dynamic/personalized content → ✗ Use edge cache only
├─ Need per-request cache control from Workers → ✗ Use R2 directly
└─ Frequently updated content (< 10hr lifetime) → ✗ Not eligible

Asset Eligibility Copy Chapter

Cache Reserve only stores assets meeting ALL criteria:

• Cacheable per Cloudflare's standard rules
• Minimum 10-hour TTL (36000 seconds)
• Content-Length header present
• Original files only (not transformed images)

Eligibility Checklist Copy Section

Use this checklist to verify if an asset is eligible:

• Zone has Cache Reserve enabled
• Zone has Tiered Cache enabled (required)
• Asset TTL ≥ 10 hours (36,000 seconds)
• Content-Length header present on origin response
• No Set-Cookie header (or uses private directive)
• Vary header is NOT * (can be Accept-Encoding)
• Not an image transformation variant (original images OK)
• Not a range request (no HTTP 206 support)
• Not O2O (Orange-to-Orange) proxied request

All boxes must be checked for Cache Reserve eligibility.

Not Eligible Copy Section

• Assets with TTL < 10 hours
• Responses without Content-Length header
• Image transformation variants (original images are eligible)
• Responses with Set-Cookie headers
• Responses with Vary: * header
• Assets from R2 public buckets on same zone
• O2O (Orange-to-Orange) setup requests
• Range requests (video seeking, partial content downloads)

Quick Start Copy Chapter

# Enable via Dashboard
https://dash.cloudflare.com/caching/cache-reserve
# Click "Enable Storage Sync" or "Purchase" button

Prerequisites:

• Paid Cache Reserve plan or Smart Shield Advanced required
• Tiered Cache required for optimal performance

Essential Commands Copy Chapter

# Check Cache Reserve status
curl -X GET "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
  -H "Authorization: Bearer $API_TOKEN"

# Enable Cache Reserve
curl -X PATCH "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/cache/cache_reserve" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "on"}'

# Check asset cache status
curl -I https://example.com/asset.jpg | grep -i cache

In This Reference Copy Chapter

Files:

• configuration.md - Setup, API, SDKs, and Cache Rules
• api.md - Purging, monitoring, Workers integration
• patterns.md - Best practices, cost optimization, debugging
• gotchas.md - Common issues, limitations, troubleshooting

See Also Copy Chapter

• r2 - Cache Reserve built on R2 storage
• workers - Workers integration with Cache API

Overview (`skills/.curated/cloudflare-deploy/references/containers/README.md`) Copy Section

Cloudflare Containers Skill Reference

APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers

Use when working with Cloudflare Containers: deploying containerized apps on Workers platform, configuring container-enabled Durable Objects, managing container lifecycle, or implementing stateful/stateless container patterns.

Beta Status Copy Chapter

⚠️ Containers is currently in beta. API may change without notice. No SLA guarantees. Custom instance types added Jan 2026.

Core Concepts Copy Chapter

Container as Durable Object: Each container is a Durable Object with persistent identity. Accessed via getByName(id) or getRandom().

Image deployment: Images pre-fetched globally. Deployments use rolling strategy (not instant like Workers).

Lifecycle: cold start (2-3s) → running → sleepAfter timeout → stopped. No autoscaling - manual load balancing via getRandom().

Persistent identity, ephemeral disk: Container ID persists, but disk resets on stop. Use Durable Object storage for persistence.

Quick Start Copy Chapter

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
  defaultPort = 8080;
  sleepAfter = "30m";
}

export default {
  async fetch(request: Request, env: Env) {
    const container = env.MY_CONTAINER.getByName("instance-1");
    await container.startAndWaitForPorts();
    return container.fetch(request);
  }
};

Reading Order Copy Chapter

Routing Decision Tree Copy Chapter

How should requests reach containers?

• Same user/session → same container: Use getByName(sessionId) for session affinity
• Stateless, spread load: Use getRandom() for load balancing
• Job per container: Use getByName(jobId) + explicit lifecycle management
• Single global instance: Use getByName("singleton")

When to Use Containers vs Workers Copy Chapter

Use Containers when:

• Need stateful, long-lived processes (sessions, WebSockets, games)
• Running existing containerized apps (Node.js, Python, custom binaries)
• Need filesystem access or specific system dependencies
• Per-user/session isolation with dedicated compute

Use Workers when:

• Stateless HTTP handlers
• Sub-millisecond cold starts required
• Auto-scaling to zero critical
• Simple request/response patterns

In This Reference Copy Chapter

• configuration.md - Wrangler config, instance types, Container class properties, environment variables, account limits
• api.md - Container class API, startup methods, communication (HTTP/TCP/WebSocket), routing helpers, lifecycle hooks, scheduling, state inspection
• patterns.md - Routing patterns (session affinity, load balancing, singleton), WebSocket forwarding, graceful shutdown, Workflow/Queue integration
• gotchas.md - Critical gotchas (WebSocket, startup methods), common errors with solutions, specific limits, beta caveats

See Also Copy Chapter

• Durable Objects - Containers extend Durable Objects
• Workflows - Orchestrate container operations
• Queues - Trigger containers from queue messages
• Cloudflare Docs

Overview (`skills/.curated/cloudflare-deploy/references/cron-triggers/README.md`) Copy Section

Cloudflare Cron Triggers

Schedule Workers execution using cron expressions. Runs on Cloudflare's global network during underutilized periods.

Key Features Copy Chapter

• UTC-only execution - All schedules run on UTC time
• 5-field cron syntax - Quartz scheduler extensions (L, W, #)
• Global propagation - 15min deployment delay
• At-least-once delivery - Rare duplicate executions possible
• Workflow integration - Trigger long-running multi-step tasks
• Green Compute - Optional carbon-aware scheduling during low-carbon periods

Cron Syntax Copy Chapter

┌─────────── minute (0-59)
 │ ┌───────── hour (0-23)
 │ │ ┌─────── day of month (1-31)
 │ │ │ ┌───── month (1-12, JAN-DEC)
 │ │ │ │ ┌─── day of week (1-7, SUN-SAT, 1=Sunday)
 * * * * *

Special chars: * (any), , (list), - (range), / (step), L (last), W (weekday), # (nth)

Common Schedules Copy Chapter

*/5 * * * *        # Every 5 minutes
0 * * * *          # Hourly
0 2 * * *          # Daily 2am UTC (off-peak)
0 9 * * MON-FRI    # Weekdays 9am UTC
0 0 1 * *          # Monthly 1st midnight UTC
0 9 L * *          # Last day of month 9am UTC
0 10 * * MON#2     # 2nd Monday 10am UTC
*/10 9-17 * * MON-FRI  # Every 10min, 9am-5pm weekdays

Quick Start Copy Chapter

wrangler.jsonc:

{
  "name": "my-cron-worker",
  "triggers": {
    "crons": ["*/5 * * * *", "0 2 * * *"]
  }
}

Handler:

export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext,
  ): Promise<void> {
    console.log("Cron:", controller.cron);
    console.log("Time:", new Date(controller.scheduledTime));
    
    ctx.waitUntil(asyncTask(env)); // Non-blocking
  },
};

Test locally:

npx wrangler dev
curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"

Limits Copy Chapter

• Free: 3 triggers/worker, 10ms CPU
• Paid: Unlimited triggers, 50ms CPU
• Propagation: 15min global deployment
• Timezone: UTC only

Reading Order Copy Chapter

New to cron triggers? Start here:

1. This README - Overview and quick start
2. configuration.md - Set up your first cron trigger
3. api.md - Understand the handler API
4. patterns.md - Common use cases and examples

Troubleshooting? Jump to gotchas.md

In This Reference Copy Chapter

• configuration.md - wrangler config, env-specific schedules, Green Compute
• api.md - ScheduledController, noRetry(), waitUntil, testing patterns
• patterns.md - Use cases, monitoring, queue integration, Durable Objects
• gotchas.md - Timezone issues, idempotency, security, testing

See Also Copy Chapter

• workflows - Alternative for long-running scheduled tasks
• workers - Worker runtime documentation

Overview (`skills/.curated/cloudflare-deploy/references/d1/README.md`) Copy Section

Cloudflare D1 Database

Expert guidance for Cloudflare D1, a serverless SQLite database designed for horizontal scale-out across multiple databases.

Overview Copy Chapter

D1 is Cloudflare's managed, serverless database with:

• SQLite SQL semantics and compatibility
• Built-in disaster recovery via Time Travel (30-day point-in-time recovery)
• Horizontal scale-out architecture (10 GB per database)
• Worker and HTTP API access
• Pricing based on query and storage costs only

Architecture Philosophy: D1 is optimized for per-user, per-tenant, or per-entity database patterns rather than single large databases.

Quick Start Copy Chapter

# Create database
wrangler d1 create <database-name>

# Execute migration
wrangler d1 migrations apply <db-name> --remote

# Local development
wrangler dev

Core Query Methods Copy Chapter

// .all() - Returns all rows; .first() - First row or null; .first(col) - Single column value
// .run() - INSERT/UPDATE/DELETE; .raw() - Array of arrays (efficient)
const { results, success, meta } = await env.DB.prepare('SELECT * FROM users WHERE active = ?').bind(true).all();
const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();

Batch Operations Copy Chapter

// Multiple queries in single round trip (atomic transaction)
const results = await env.DB.batch([
  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1),
  env.DB.prepare('SELECT * FROM posts WHERE author_id = ?').bind(1),
  env.DB.prepare('UPDATE users SET last_access = ? WHERE id = ?').bind(Date.now(), 1)
]);

Sessions API (Paid Plans) Copy Chapter

// Create long-running session for analytics/migrations (up to 15 minutes)
const session = env.DB.withSession();
try {
  await session.prepare('CREATE INDEX idx_heavy ON large_table(column)').run();
  await session.prepare('ANALYZE').run();
} finally {
  session.close(); // Always close to release resources
}

Read Replication (Paid Plans) Copy Chapter

// Read from nearest replica for lower latency (automatic failover)
const user = await env.DB_REPLICA.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first();

// Writes always go to primary
await env.DB.prepare('UPDATE users SET last_login = ? WHERE id = ?').bind(Date.now(), userId).run();

Platform Limits Copy Chapter

Pricing: $5/month per database beyond free tier + $0.001 per 1K reads + $1 per 1M writes + $0.75/GB storage/month

CLI Commands Copy Chapter

# Database management
wrangler d1 create <db-name>
wrangler d1 list
wrangler d1 delete <db-name>

# Migrations
wrangler d1 migrations create <db-name> <migration-name>    # Create new migration file
wrangler d1 migrations apply <db-name> --remote             # Apply pending migrations
wrangler d1 migrations apply <db-name> --local              # Apply locally
wrangler d1 migrations list <db-name> --remote              # Show applied migrations

# Direct SQL execution
wrangler d1 execute <db-name> --remote --command="SELECT * FROM users"
wrangler d1 execute <db-name> --local --file=./schema.sql

# Backups & Import/Export
wrangler d1 export <db-name> --remote --output=./backup.sql  # Full export with schema
wrangler d1 export <db-name> --remote --no-schema --output=./data.sql  # Data only
wrangler d1 time-travel restore <db-name> --timestamp="2024-01-15T14:30:00Z"  # Point-in-time recovery

# Development
wrangler dev --persist-to=./.wrangler/state

Reading Order Copy Chapter

Start here: Quick Start above → configuration.md (setup) → api.md (queries)

Common tasks:

• First time setup: configuration.md → Run migrations
• Adding queries: api.md → Prepared statements
• Pagination/caching: patterns.md
• Production optimization: Read Replication + Sessions API (this file)
• Debugging: gotchas.md

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc setup, migrations, TypeScript types, ORMs, local dev
• api.md - Query methods (.all/.first/.run/.raw), batch, sessions, read replicas, error handling
• patterns.md - Pagination, bulk operations, caching, multi-tenant, sessions, analytics
• gotchas.md - SQL injection, limits by plan tier, performance, common errors

See Also Copy Chapter

• workers - Worker runtime and fetch handler patterns
• hyperdrive - Connection pooling for external databases

Overview (`skills/.curated/cloudflare-deploy/references/ddos/README.md`) Copy Section

Cloudflare DDoS Protection

Autonomous, always-on protection against DDoS attacks across L3/4 and L7.

Protection Types Copy Chapter

• HTTP DDoS (L7): Protects HTTP/HTTPS traffic, phase ddos_l7, zone/account level
• Network DDoS (L3/4): UDP/SYN/DNS floods, phase ddos_l4, account level only
• Adaptive DDoS: Learns 7-day baseline, detects deviations, 4 profile types (Origins, User-Agents, Locations, Protocols)

Plan Availability Copy Chapter

Actions & Sensitivity Copy Chapter

• Actions: block, managed_challenge, challenge, log (Enterprise Advanced only)
• Sensitivity: default (high), medium, low, eoff (essentially off)
• Override: By category/tag or individual rule ID
• Scope: Zone-level overrides take precedence over account-level

Reading Order Copy Chapter

See Also Copy Chapter

• waf - Application-layer security rules
• bot-management - Bot detection and mitigation

Overview (`skills/.curated/cloudflare-deploy/references/do-storage/README.md`) Copy Section

Cloudflare Durable Objects Storage

Persistent storage API for Durable Objects with SQLite and KV backends, PITR, and automatic concurrency control.

Overview Copy Chapter

DO Storage provides:

• SQLite-backed (recommended) or KV-backed
• SQL API + synchronous/async KV APIs
• Automatic input/output gates (race-free)
• 30-day point-in-time recovery (PITR)
• Transactions and alarms

Use cases: Stateful coordination, real-time collaboration, counters, sessions, rate limiters

Billing: Charged by request, GB-month storage, and rowsRead/rowsWritten for SQL operations

Quick Start Copy Chapter

export class Counter extends DurableObject {
  sql: SqlStorage;
  
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sql = ctx.storage.sql;
    this.sql.exec('CREATE TABLE IF NOT EXISTS data(key TEXT PRIMARY KEY, value INTEGER)');
  }
  
  async increment(): Promise<number> {
    const result = this.sql.exec(
      'INSERT INTO data VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = value + 1 RETURNING value',
      'counter', 1
    ).one();
    return result?.value || 1;
  }
}

Storage Backends Copy Chapter

Core APIs Copy Chapter

• SQL API (ctx.storage.sql): Full SQLite with extensions (FTS5, JSON, math)
• Sync KV (ctx.storage.kv): Synchronous key-value (SQLite only)
• Async KV (ctx.storage): Asynchronous key-value (both backends)
• Transactions (transactionSync(), transaction())
• PITR (getBookmarkForTime(), onNextSessionRestoreBookmark())
• Alarms (setAlarm(), alarm() handler)

Reading Order Copy Chapter

New to DO storage: configuration.md → api.md → patterns.md → gotchas.md
Building features: patterns.md → api.md → gotchas.md
Debugging issues: gotchas.md → api.md
Writing tests: testing.md

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc migrations, SQLite vs KV setup, RPC binding
• api.md - SQL exec/cursors, KV methods, storage options, transactions, alarms, PITR
• patterns.md - Schema migrations, caching, rate limiting, batch processing, parent-child coordination
• gotchas.md - Concurrency gates, INTEGER precision, transaction rules, SQL limits
• testing.md - vitest-pool-workers setup, testing DOs with SQL/alarms/PITR

See Also Copy Chapter

• durable-objects - DO fundamentals and coordination patterns
• workers - Worker runtime for DO stubs
• d1 - Shared database alternative to per-DO storage

Overview (`skills/.curated/cloudflare-deploy/references/durable-objects/README.md`) Copy Section

Cloudflare Durable Objects

Expert guidance for building stateful applications with Cloudflare Durable Objects.

Reading Order Copy Chapter

1. First time? Read this overview + Quick Start
2. Setting up? See Configuration
3. Building features? Use decision trees below → Patterns
4. Debugging issues? Check Gotchas
5. Deep dive? API and DO Storage

Overview Copy Chapter

Durable Objects combine compute with storage in globally-unique, strongly-consistent packages:

• Globally unique instances: Each DO has unique ID for multi-client coordination
• Co-located storage: Fast, strongly-consistent storage with compute
• Automatic placement: Objects spawn near first request location
• Stateful serverless: In-memory state + persistent storage
• Single-threaded: Serial request processing (no race conditions)

Rules of Durable Objects Copy Chapter

Critical rules preventing most production issues:

1. One alarm per DO - Schedule multiple events via queue pattern
2. ~1K req/s per DO max - Shard for higher throughput
3. Constructor runs every wake - Keep initialization light; use lazy loading
4. Hibernation clears memory - In-memory state lost; persist critical data
5. Use ctx.waitUntil() for cleanup - Ensures completion after response sent
6. No setTimeout for persistence - Use setAlarm() for reliable scheduling

Core Concepts Copy Chapter

Class Structure Copy Section

All DOs extend DurableObject base class with constructor receiving DurableObjectState (storage, WebSockets, alarms) and Env (bindings).

Lifecycle States Copy Section

[Not Created] → [Active] ⇄ [Hibernated] → [Evicted]
                   ↓
              [Destroyed]

• Not Created: DO ID exists but instance never spawned
• Active: Processing requests, in-memory state valid, billed per GB-hour
• Hibernated: WebSocket connections open but zero compute, zero cost
• Evicted: Removed from memory; next request triggers cold start
• Destroyed: Data deleted via migration or manual deletion

Accessing from Workers Copy Section

Workers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).

RPC vs fetch() decision:

├─ New project + compat ≥2024-04-03 → RPC (type-safe, simpler)
├─ Need HTTP semantics (headers, status) → fetch()
├─ Proxying requests to DO → fetch()
└─ Legacy compatibility → fetch()

See Patterns: RPC vs fetch() for examples.

ID Generation Copy Section

• idFromName(): Deterministic, named coordination (rate limiting, locks)
• newUniqueId(): Random IDs for sharding high-throughput workloads
• idFromString(): Derive from existing IDs
• Jurisdiction option: Data locality compliance

Storage Options Copy Section

Which storage API?

├─ Structured data, relations, transactions → SQLite (recommended)
├─ Simple KV on SQLite DO → ctx.storage.kv (sync KV)
└─ Legacy KV-only DO → ctx.storage (async KV)

• SQLite (recommended): Structured data, transactions, 10GB/DO
• Synchronous KV API: Simple key-value on SQLite objects
• Asynchronous KV API: Legacy/advanced use cases

See DO Storage for deep dive.

Special Features Copy Section

• Alarms: Schedule future execution per-DO (1 per DO - use queue pattern for multiple)
• WebSocket Hibernation: Zero-cost idle connections (memory cleared on hibernation)
• Point-in-Time Recovery: Restore to any point in 30 days (SQLite only)

Quick Start Copy Chapter

import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject<Env> {
  async increment(): Promise<number> {
    const result = this.ctx.storage.sql.exec(
      `INSERT INTO counters (id, value) VALUES (1, 1)
       ON CONFLICT(id) DO UPDATE SET value = value + 1
       RETURNING value`
    ).one();
    return result.value;
  }
}

// Worker access
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const id = env.COUNTER.idFromName("global");
    const stub = env.COUNTER.get(id);
    const count = await stub.increment();
    return new Response(`Count: ${count}`);
  }
};

Decision Trees Copy Chapter

What do you need? Copy Section

├─ Coordinate requests (rate limit, lock, session)
│   → idFromName(identifier) → [Patterns: Rate Limiting/Locks](./patterns.md)
│
├─ High throughput (>1K req/s)
│   → Sharding with newUniqueId() or hash → [Patterns: Sharding](./patterns.md)
│
├─ Real-time updates (WebSocket, chat, collab)
│   → WebSocket hibernation + room pattern → [Patterns: Real-time](./patterns.md)
│
├─ Background work (cleanup, notifications, scheduled tasks)
│   → Alarms + queue pattern (1 alarm/DO) → [Patterns: Multiple Events](./patterns.md)
│
└─ User sessions with expiration
    → Session pattern + alarm cleanup → [Patterns: Session Management](./patterns.md)

Which access pattern? Copy Section

├─ New project + typed methods → RPC (compat ≥2024-04-03)
├─ Need HTTP semantics → fetch()
├─ Proxying to DO → fetch()
└─ Legacy compat → fetch()

See Patterns: RPC vs fetch() for examples.

Which storage? Copy Section

├─ Structured data, SQL queries, transactions → SQLite (recommended)
├─ Simple KV on SQLite DO → ctx.storage.kv (sync API)
└─ Legacy KV-only DO → ctx.storage (async API)

See DO Storage for complete guide.

Essential Commands Copy Chapter

npx wrangler dev              # Local dev with DOs
npx wrangler dev --remote     # Test against prod DOs
npx wrangler deploy           # Deploy + auto-apply migrations

Resources Copy Chapter

Docs: https://developers.cloudflare.com/durable-objects/
API Reference: https://developers.cloudflare.com/durable-objects/api/
Examples: https://developers.cloudflare.com/durable-objects/examples/

In This Reference Copy Chapter

• Configuration - wrangler.jsonc setup, migrations, bindings, environments
• API - Class structure, ctx methods, alarms, WebSocket hibernation
• Patterns - Sharding, rate limiting, locks, real-time, sessions
• Gotchas - Limits, hibernation caveats, common errors

See Also Copy Chapter

• DO Storage - SQLite, KV, transactions (detailed storage guide)
• Workers - Core Workers runtime features
• WebSockets - WebSocket APIs and patterns

Overview (`skills/.curated/cloudflare-deploy/references/email-routing/README.md`) Copy Section

Cloudflare Email Routing Skill Reference

Overview Copy Chapter

Cloudflare Email Routing enables custom email addresses for your domain that route to verified destination addresses. It's free, privacy-focused (no storage/access), and includes Email Workers for programmatic email processing.

Available to all Cloudflare customers using Cloudflare as authoritative nameserver.

Quick Start Copy Chapter

// Basic email handler
export default {
  async email(message, env, ctx) {
    // CRITICAL: Must consume stream before response
    const parser = new PostalMime.default();
    const email = await parser.parse(await message.raw.arrayBuffer());
    
    // Process email
    console.log(`From: ${message.from}, Subject: ${email.subject}`);
    
    // Forward or reject
    await message.forward("[email protected]");
  }
} satisfies ExportedHandler<Env>;

Reading Order Copy Chapter

Start here based on your goal:

1. New to Email Routing? → configuration.md → patterns.md
2. Adding Workers? → api.md § Worker Runtime API → patterns.md
3. Sending emails? → api.md § SendEmail Binding
4. Managing via API? → api.md § REST API Operations
5. Debugging issues? → gotchas.md

Decision Tree Copy Chapter

Need to receive emails?
├─ Simple forwarding only? → Dashboard rules (configuration.md)
├─ Complex logic/filtering? → Email Workers (api.md + patterns.md)
└─ Parse attachments/body? → postal-mime library (patterns.md § Parse Email)

Need to send emails?
├─ From Worker? → SendEmail binding (api.md § SendEmail)
└─ From external app? → Use external SMTP/API service

Having issues?
├─ Email not arriving? → gotchas.md § Mail Authentication
├─ Worker crashing? → gotchas.md § Stream Consumption
└─ Forward failing? → gotchas.md § Destination Verification

Key Concepts Copy Chapter

Routing Rules: Pattern-based forwarding configured via Dashboard/API. Simple but limited.

Email Workers: Custom TypeScript handlers with full email access. Handles complex logic, parsing, storage, rejection.

SendEmail Binding: Outbound email API for Workers. Transactional email only (no marketing/bulk).

ForwardableEmailMessage: Runtime interface for incoming emails. Provides headers, raw stream, forward/reject methods.

In This Reference Copy Chapter

• configuration.md - Setup, deployment, wrangler config
• api.md - REST API + Worker runtime API + types
• patterns.md - Common patterns with working examples
• gotchas.md - Critical pitfalls, troubleshooting, limits

Architecture Copy Chapter

Internet → MX Records → Cloudflare Email Routing
                            ├─ Routing Rules (dashboard)
                            └─ Email Worker (your code)
                                ├─ Forward to destination
                                ├─ Reject with reason
                                ├─ Store in R2/KV/D1
                                └─ Send outbound (SendEmail)

See Also Copy Chapter

• Cloudflare Docs: Email Routing
• Cloudflare Docs: Email Workers
• postal-mime npm package

Overview (`skills/.curated/cloudflare-deploy/references/email-workers/README.md`) Copy Section

Cloudflare Email Workers

Process incoming emails programmatically using Cloudflare Workers runtime.

Overview Copy Chapter

Email Workers enable custom email processing logic at the edge. Build spam filters, auto-responders, ticket systems, notification handlers, and more using the same Workers runtime you use for HTTP requests.

Key capabilities:

• Process inbound emails with full message access
• Forward to verified destinations
• Send replies with proper threading
• Parse MIME content and attachments
• Integrate with KV, R2, D1, and external APIs

Quick Start Copy Chapter

Minimal ES Modules Handler Copy Section

export default {
  async email(message, env, ctx) {
    // Reject spam
    if (message.from.includes('spam.com')) {
      message.setReject('Blocked');
      return;
    }
    
    // Forward to inbox
    await message.forward('[email protected]');
  }
};

Core Operations Copy Section

Reading Order Copy Chapter

For comprehensive understanding, read files in this order:

1. README.md (this file) - Overview and quick start
2. configuration.md - Setup, deployment, bindings
3. api.md - Complete API reference
4. patterns.md - Real-world implementation examples
5. gotchas.md - Critical pitfalls and debugging

In This Reference Copy Chapter

Architecture Copy Chapter

Incoming Email → Email Routing → Email Worker
                                    ↓
                              Process + Decide
                                    ↓
                    ┌───────────────┼───────────────┐
                    ↓               ↓               ↓
                Forward          Reply          Reject

Event flow:

1. Email arrives at your domain
2. Email Routing matches route (e.g., [email protected])
3. Bound Email Worker receives ForwardableEmailMessage
4. Worker processes and takes action (forward/reply/reject)
5. Email delivered or rejected based on worker logic

Key Concepts Copy Chapter

Envelope vs Headers Copy Section

• Envelope addresses (message.from, message.to): SMTP transport addresses (trusted)
• Header addresses (parsed from body): Display addresses (can be spoofed)

Use envelope addresses for security decisions.

Single-Use Streams Copy Section

message.raw is a ReadableStream that can only be read once. Buffer to ArrayBuffer for multiple uses.

// Buffer first
const buffer = await new Response(message.raw).arrayBuffer();
const email = await PostalMime.parse(buffer);

See gotchas.md for details.

Verified Destinations Copy Section

forward() only works with addresses verified in the Cloudflare Email Routing dashboard. Add destinations before deployment.

Use Cases Copy Chapter

• Spam filtering: Block based on sender, content, or reputation
• Auto-responders: Send acknowledgment replies with threading
• Ticket creation: Parse emails and create support tickets
• Email archival: Store in KV, R2, or D1
• Notification routing: Forward to Slack, Discord, or webhooks
• Attachment processing: Extract files to R2 storage
• Multi-tenant routing: Route based on recipient subdomain
• Size filtering: Reject oversized attachments

Limits Copy Chapter

See gotchas.md for complete limits table.

Prerequisites Copy Chapter

Before deploying Email Workers:

1. Enable Email Routing in Cloudflare dashboard for your domain
2. Verify destination addresses for forwarding
3. Configure DMARC/SPF for sending domains (required for replies)
4. Set up wrangler.jsonc with SendEmail binding

See configuration.md for detailed setup.

Service Worker Syntax (Deprecated) Copy Chapter

Modern projects should use ES modules format shown above. Service Worker syntax (addEventListener('email', ...)) is deprecated but still supported.

See Also Copy Chapter

• Email Routing Documentation
• Workers Platform
• Wrangler CLI
• postal-mime on npm
• mimetext on npm

Overview (`skills/.curated/cloudflare-deploy/references/hyperdrive/README.md`) Copy Section

Hyperdrive

Accelerates database queries from Workers via connection pooling, edge setup, query caching.

Key Features Copy Chapter

• Connection Pooling: Persistent connections eliminate TCP/TLS/auth handshakes (~7 round-trips)
• Edge Setup: Connection negotiation at edge, pooling near origin
• Query Caching: Auto-cache non-mutating queries (default 60s TTL)
• Support: PostgreSQL, MySQL + compatibles (CockroachDB, Timescale, PlanetScale, Neon, Supabase)

Architecture Copy Chapter

Worker → Edge (setup) → Pool (near DB) → Origin
         ↓ cached reads
         Cache

Quick Start Copy Chapter

# Create config
npx wrangler hyperdrive create my-db \
  --connection-string="postgres://user:pass@host:5432/db"

# wrangler.jsonc
{
  "compatibility_flags": ["nodejs_compat"],
  "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
}

import { Client } from "pg";

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString,
    });
    await client.connect();
    const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
    await client.end();
    return Response.json(result.rows);
  },
};

When to Use Copy Chapter

✅ Global access to single-region DBs, high read ratios, popular queries, connection-heavy loads
❌ Write-heavy, real-time data (<1s), single-region apps close to DB

💡 Pair with Smart Placement for Workers making multiple queries - executes near DB to minimize latency.

Driver Choice Copy Chapter

Reading Order Copy Chapter

In This Reference Copy Chapter

• configuration.md - Setup, wrangler config, Smart Placement
• api.md - Binding APIs, query patterns, driver usage
• patterns.md - Use cases, ORMs, multi-query optimization
• gotchas.md - Limits, troubleshooting, connection management

See Also Copy Chapter

• smart-placement - Optimize multi-query Workers near databases
• d1 - Serverless SQLite alternative for edge-native apps
• workers - Worker runtime with database bindings

Overview (`skills/.curated/cloudflare-deploy/references/images/README.md`) Copy Section

Cloudflare Images Skill Reference

Cloudflare Images is an end-to-end image management solution providing storage, transformation, optimization, and delivery at scale via Cloudflare's global network.

Quick Decision Tree Copy Chapter

Need to:

• Transform in Worker? → api.md (Workers Binding API)
• Upload from Worker? → api.md (REST API)
• Upload from client? → patterns.md (Direct Creator Upload)
• Set up variants? → configuration.md
• Serve responsive images? → patterns.md
• Add watermarks? → patterns.md
• Fix errors? → gotchas.md

Reading Order Copy Chapter

For building image upload/transform feature:

1. configuration.md - Setup Workers binding
2. api.md - Learn transform API
3. patterns.md - Direct upload pattern
4. gotchas.md - Check limits and errors

For URL-based transforms:

1. configuration.md - Create variants
2. api.md - URL syntax
3. patterns.md - Responsive patterns

For troubleshooting:

1. gotchas.md - Error messages
2. gotchas.md - Size/format limits

Core Methods Copy Chapter

In This Reference Copy Chapter

• api.md - Complete API: Workers binding, REST endpoints, URL transforms
• configuration.md - Setup: wrangler.toml, variants, auth, signed URLs
• patterns.md - Patterns: responsive images, watermarks, format negotiation, caching
• gotchas.md - Troubleshooting: limits, errors, best practices

Key Features Copy Chapter

• Automatic Optimization - AVIF/WebP format negotiation
• On-the-fly Transforms - Resize, crop, blur, sharpen via URL or API
• Workers Binding - Transform images in Workers (2026 primary method)
• Direct Upload - Secure client-side uploads without backend proxy
• Global Delivery - Cached at 300+ Cloudflare data centers
• Watermarking - Overlay images programmatically

See Also Copy Chapter

• Official Docs
• Workers Examples

Overview (`skills/.curated/cloudflare-deploy/references/kv/README.md`) Copy Section

Cloudflare Workers KV

Globally-distributed, eventually-consistent key-value store optimized for high read volume and low latency.

Overview Copy Chapter

KV provides:

• Eventual consistency (60s global propagation)
• Read-optimized performance
• 25 MiB value limit per key
• Auto-replication to Cloudflare edge
• Metadata support (1024 bytes)

Use cases: Config storage, user sessions, feature flags, caching, A/B testing

When to Use KV Copy Chapter

Quick comparison:

Quick Start Copy Chapter

wrangler kv namespace create MY_NAMESPACE
# Add binding to wrangler.jsonc

// Write
await env.MY_KV.put("key", "value", { expirationTtl: 300 });

// Read
const value = await env.MY_KV.get("key");
const json = await env.MY_KV.get<Config>("config", "json");

Core Operations Copy Chapter

Consistency Model Copy Chapter

• Write visibility: Immediate in same location, ≤60s globally
• Read path: Eventually consistent
• Write rate: 1 write/second per key (429 on exceed)

Reading Order Copy Chapter

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc setup, namespace creation, TypeScript types
• api.md - KV methods, bulk operations, cacheTtl, content types
• patterns.md - Caching, sessions, rate limiting, A/B testing
• gotchas.md - Eventual consistency, concurrent writes, value limits

See Also Copy Chapter

• workers - Worker runtime for KV access
• d1 - Use D1 for strong consistency needs
• durable-objects - Strongly consistent alternative

Overview (`skills/.curated/cloudflare-deploy/references/miniflare/README.md`) Copy Section

Miniflare

Local simulator for Cloudflare Workers development/testing. Runs Workers in workerd sandbox implementing runtime APIs - no internet required.

Features Copy Chapter

• Full-featured: KV, Durable Objects, R2, D1, WebSockets, Queues
• Fully-local: test without internet, instant reload
• TypeScript-native: detailed logging, source maps
• Advanced testing: dispatch events without HTTP, simulate Worker connections

When to Use Copy Chapter

Decision tree for testing Workers:

Need to test Workers?
│
├─ Unit tests for business logic only?
│  └─ getPlatformProxy (Vitest/Jest) → [patterns.md](./patterns.md#getplatformproxy)
│     Fast, no HTTP, direct binding access
│
├─ Integration tests with full runtime?
│  ├─ Single Worker?
│  │  └─ Miniflare API → [Quick Start](#quick-start)
│  │     Full control, programmatic access
│  │
│  ├─ Multiple Workers + service bindings?
│  │  └─ Miniflare workers array → [configuration.md](./configuration.md#multiple-workers)
│  │     Shared storage, inter-worker calls
│  │
│  └─ Vitest test runner integration?
│     └─ vitest-pool-workers → [patterns.md](./patterns.md#vitest-pool-workers)
│        Full Workers env in Vitest
│
└─ Local dev server?
   └─ wrangler dev (not Miniflare)
      Hot reload, automatic config

Use Miniflare for:

• Integration tests with full Worker runtime
• Testing bindings/storage locally
• Multiple Workers with service bindings
• Programmatic event dispatch (fetch, queue, scheduled)

Use getPlatformProxy for:

• Fast unit tests of business logic
• Testing without HTTP overhead
• Vitest/Jest environments

Use Wrangler for:

• Local development workflow
• Production deployments

Setup Copy Chapter

npm i -D miniflare

Requires ES modules in package.json:

{"type": "module"}

Quick Start Copy Chapter

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  modules: true,
  script: `
    export default {
      async fetch(request, env, ctx) {
        return new Response("Hello Miniflare!");
      }
    }
  `,
});

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // Hello Miniflare!
await mf.dispose();

Reading Order Copy Chapter

New to Miniflare? Start here:

1. Quick Start - Running in 2 minutes
2. When to Use - Choose your testing approach
3. patterns.md - Testing patterns (getPlatformProxy, Vitest, node:test)
4. configuration.md - Configure bindings, storage, multiple workers

Troubleshooting:

• gotchas.md - Common errors and debugging

API reference:

• api.md - Complete method reference

See Also Copy Chapter

• wrangler - CLI tool that embeds Miniflare for wrangler dev
• workerd - Runtime that powers Miniflare
• workers - Workers runtime API documentation

Overview (`skills/.curated/cloudflare-deploy/references/network-interconnect/README.md`) Copy Section

Cloudflare Network Interconnect (CNI)

Private, high-performance connectivity to Cloudflare's network. Enterprise-only.

Connection Types Copy Chapter

Direct: Physical fiber in shared datacenter. 10/100 Gbps. You order cross-connect.

Partner: Virtual via Console Connect, Equinix, Megaport, etc. Managed via partner SDN.

Cloud: AWS Direct Connect or GCP Cloud Interconnect. Magic WAN only.

Dataplane Versions Copy Chapter

v1 (Classic): GRE tunnel support, VLAN/BFD/LACP, asymmetric MTU (1500↓/1476↑), peering support.

v2 (Beta): No GRE, 1500 MTU both ways, no VLAN/BFD/LACP yet, ECMP instead.

Use Cases Copy Chapter

• Magic Transit DSR: DDoS protection, egress via ISP (v1/v2)
• Magic Transit + Egress: DDoS + egress via CF (v1/v2)
• Magic WAN + Zero Trust: Private backbone (v1 needs GRE, v2 native)
• Peering: Public routes at PoP (v1 only)
• App Security: WAF/Cache/LB (v1/v2 over Magic Transit)

Prerequisites Copy Chapter

• Enterprise plan
• IPv4 /24+ or IPv6 /48+ prefixes
• BGP ASN for v1
• See locations PDF

Specs Copy Chapter

• /31 point-to-point subnets
• 10km max optical distance
• 10G: 10GBASE-LR single-mode
• 100G: 100GBASE-LR4 single-mode
• No SLA (free service)
• Backup Internet required

Throughput Copy Chapter

Timeline Copy Chapter

2-4 weeks typical. Steps: request → config review → order connection → configure → test → enable health checks → activate → monitor.

In This Reference Copy Chapter

• configuration.md - BGP, routing, setup
• api.md - API endpoints, SDKs
• patterns.md - HA, hybrid cloud, failover
• gotchas.md - Troubleshooting, limits

Reading Order by Task Copy Chapter

Automation Boundary Copy Chapter

API-Automatable:

• List/create/delete interconnects (Direct, Partner)
• List available slots
• Get interconnect status
• Download LOA PDF
• Create/update CNI objects (BGP config)
• Query settings

Requires Account Team:

• Initial request approval
• AWS Direct Connect setup (send LOA+VLAN to CF)
• GCP Cloud Interconnect final activation
• Partner interconnect acceptance (Equinix, Megaport)
• VLAN assignment (v1)
• Configuration document generation (v1)
• Escalations + troubleshooting support

Cannot Be Automated:

• Physical cross-connect installation (Direct)
• Partner portal operations (virtual circuit ordering)
• AWS/GCP portal operations
• Maintenance window coordination

See Also Copy Chapter

• tunnel - Alternative for private network connectivity
• spectrum - Layer 4 proxy for TCP/UDP traffic

Overview (`skills/.curated/cloudflare-deploy/references/observability/README.md`) Copy Section

Cloudflare Observability Skill Reference

Purpose: Comprehensive guidance for implementing observability in Cloudflare Workers, covering traces, logs, metrics, and analytics.

Scope: Cloudflare Observability features ONLY - Workers Logs, Traces, Analytics Engine, Logpush, Metrics & Analytics, and OpenTelemetry exports.

Decision Tree: Which File to Load? Copy Chapter

Use this to route to the correct file without loading all content:

├─ "How do I enable/configure X?"           → configuration.md
├─ "What's the API/method/binding for X?"   → api.md
├─ "How do I implement X pattern?"          → patterns.md
│   ├─ Usage tracking/billing               → patterns.md
│   ├─ Error tracking                       → patterns.md
│   ├─ Performance monitoring               → patterns.md
│   ├─ Multi-tenant tracking                → patterns.md
│   ├─ Tail Worker filtering                → patterns.md
│   └─ OpenTelemetry export                 → patterns.md
└─ "Why isn't X working?" / "Limits?"       → gotchas.md

Reading Order Copy Chapter

Load files in this order based on task:

Product Overview Copy Chapter

Workers Logs Copy Section

• What: Console output from Workers (console.log/warn/error)
• Access: Dashboard (Real-time Logs), Logpush, Tail Workers
• Cost: Free (included with all Workers)
• Retention: Real-time only (no historical storage in dashboard)

Workers Traces Copy Section

• What: Execution traces with timing, CPU usage, outcome
• Access: Dashboard (Workers Analytics → Traces), Logpush
• Cost: $0.10/1M spans (GA pricing starts March 1, 2026), 10M free/month
• Retention: 14 days included

Analytics Engine Copy Section

• What: High-cardinality event storage and SQL queries
• Access: SQL API, Dashboard (Analytics → Analytics Engine)
• Cost: $0.25/1M writes beyond 10M free/month
• Retention: 90 days (configurable up to 1 year)

Tail Workers Copy Section

• What: Workers that receive logs/traces from other Workers
• Use Cases: Log filtering, transformation, external export
• Cost: Standard Workers pricing

Logpush Copy Section

• What: Stream logs to external storage (S3, R2, Datadog, etc.)
• Access: Dashboard, API
• Cost: Requires Business/Enterprise plan

Pricing Summary (2026) Copy Chapter

In This Reference Copy Chapter

• configuration.md - Setup, deployment, configuration (Logs, Traces, Analytics Engine, Tail Workers, Logpush)
• api.md - API endpoints, methods, interfaces (GraphQL, SQL, bindings, types)
• patterns.md - Common patterns, use cases, examples (billing, monitoring, error tracking, exports)
• gotchas.md - Troubleshooting, best practices, limitations (common errors, performance gotchas, pricing)

See Also Copy Chapter

• Cloudflare Workers Docs
• Analytics Engine Docs
• Workers Traces Docs

Overview (`skills/.curated/cloudflare-deploy/references/pages-functions/README.md`) Copy Section

Cloudflare Pages Functions

Serverless functions on Cloudflare Pages using Workers runtime. Full-stack dev with file-based routing.

Quick Navigation Copy Chapter

Need to...

Decision Tree: Is This Pages Functions? Copy Chapter

Need serverless backend? 
├─ Yes, for a static site → Pages Functions
├─ Yes, standalone API → Workers
└─ Just static hosting → Pages (no functions)

Have existing Worker?
├─ Complex routing logic → Use _worker.js (Advanced Mode)
└─ Simple routes → Migrate to /functions (File-Based)

Framework-based?
├─ Next.js/SvelteKit/Remix → Uses _worker.js automatically
└─ Vanilla/HTML/React SPA → Use /functions

File-Based Routing Copy Chapter

/functions
  ├── index.js              → /
  ├── api.js                → /api
  ├── users/
  │   ├── index.js          → /users/
  │   ├── [user].js         → /users/:user
  │   └── [[catchall]].js   → /users/*
  └── _middleware.js        → runs on all routes

Rules:

• index.js → directory root
• Trailing slash optional
• Specific routes precede catch-alls
• Falls back to static if no match

Dynamic Routes Copy Chapter

Single segment [param] → string:

// /functions/users/[user].js
export function onRequest(context) {
  return new Response(`Hello ${context.params.user}`);
}
// Matches: /users/nevi

Multi-segment [[param]] → array:

// /functions/users/[[catchall]].js
export function onRequest(context) {
  return new Response(JSON.stringify(context.params.catchall));
}
// Matches: /users/nevi/foobar → ["nevi", "foobar"]

Key Features Copy Chapter

• Method handlers: onRequestGet, onRequestPost, etc.
• Middleware: _middleware.js for cross-cutting concerns
• Bindings: KV, D1, R2, Durable Objects, Workers AI, Service bindings
• TypeScript: Full type support via wrangler types command
• Advanced mode: Use _worker.js for custom routing logic

Reading Order Copy Chapter

New to Pages Functions? Start here:

1. README.md - Overview, routing, decision tree (you are here)
2. configuration.md - TypeScript setup, wrangler.jsonc, bindings
3. api.md - EventContext, handlers, bindings reference
4. patterns.md - Middleware, auth, CORS, rate limiting, caching
5. gotchas.md - Common errors, debugging, limits

Quick reference lookup:

• Bindings table → api.md
• Error diagnosis → gotchas.md
• TypeScript setup → configuration.md

See Also Copy Chapter

• pages - Pages platform overview and static site deployment
• workers - Workers runtime API reference
• d1 - D1 database integration with Pages Functions

Overview (`skills/.curated/cloudflare-deploy/references/pages/README.md`) Copy Section

Cloudflare Pages

JAMstack platform for full-stack apps on Cloudflare's global network.

Key Features Copy Chapter

• Git-based deploys: Auto-deploy from GitHub/GitLab
• Preview deployments: Unique URL per branch/PR
• Pages Functions: File-based serverless routing (Workers runtime)
• Static + dynamic: Smart asset caching + edge compute
• Smart Placement: Automatic function optimization based on traffic patterns
• Framework optimized: SvelteKit, Astro, Nuxt, Qwik, Solid Start

Deployment Methods Copy Chapter

1. Git Integration (Production) Copy Section

Dashboard → Workers & Pages → Create → Connect to Git → Configure build

2. Direct Upload Copy Section

npx wrangler pages deploy ./dist --project-name=my-project
npx wrangler pages deploy ./dist --project-name=my-project --branch=staging

3. C3 CLI Copy Section

npm create cloudflare@latest my-app
# Select framework → auto-setup + deploy

vs Workers Copy Chapter

• Pages: Static sites, JAMstack, frameworks, git workflow, file-based routing
• Workers: Pure APIs, complex routing, WebSockets, scheduled tasks, email handlers
• Combine: Pages Functions use Workers runtime, can bind to Workers

Quick Start Copy Chapter

# Create
npm create cloudflare@latest

# Local dev
npx wrangler pages dev ./dist

# Deploy
npx wrangler pages deploy ./dist --project-name=my-project

# Types
npx wrangler types --path='./functions/types.d.ts'

# Secrets
echo "value" | npx wrangler pages secret put KEY --project-name=my-project

# Logs
npx wrangler pages deployment tail --project-name=my-project

Resources Copy Chapter

• Pages Docs
• Functions API
• Framework Guides
• Discord #functions

Reading Order Copy Chapter

New to Pages? Start here:

1. README.md (you are here) - Overview & quick start
2. configuration.md - Project setup, wrangler.jsonc, bindings
3. api.md - Functions API, routing, context
4. patterns.md - Common implementations
5. gotchas.md - Troubleshooting & pitfalls

Quick reference? Jump to relevant file above.

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc, build, env vars, Smart Placement
• api.md - Functions API, bindings, context, advanced mode
• patterns.md - Full-stack patterns, framework integration
• gotchas.md - Build issues, limits, debugging, framework warnings

See Also Copy Chapter

• pages-functions - File-based routing, middleware
• d1 - SQL database for Pages Functions
• kv - Key-value storage for caching/state

Overview (`skills/.curated/cloudflare-deploy/references/pipelines/README.md`) Copy Section

Cloudflare Pipelines

ETL streaming platform for ingesting, transforming, and loading data into R2 with SQL transformations.

Overview Copy Chapter

Pipelines provides:

• Streams: Durable event buffers (HTTP/Workers ingestion)
• Pipelines: SQL-based transformations
• Sinks: R2 destinations (Iceberg tables or Parquet/JSON files)

Status: Open beta (Workers Paid plan)
Pricing: No charge beyond standard R2 storage/operations

Architecture Copy Chapter

Data Sources → Streams → Pipelines (SQL) → Sinks → R2
                 ↑          ↓                ↓
            HTTP/Workers  Transform     Iceberg/Parquet

Quick Start Copy Chapter

# Interactive setup (recommended)
npx wrangler pipelines setup

Minimal Worker example:

interface Env {
  STREAM: Pipeline;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const event = { user_id: "123", event_type: "purchase", amount: 29.99 };
    
    // Fire-and-forget pattern
    ctx.waitUntil(env.STREAM.send([event]));
    
    return new Response('OK');
  }
} satisfies ExportedHandler<Env>;

Which Sink Type? Copy Chapter

Need SQL queries on data?
  → R2 Data Catalog (Iceberg)
    ✅ ACID transactions, time-travel, schema evolution
    ❌ More setup complexity (namespace, table, catalog token)

Just file storage/archival?
  → R2 Storage (Parquet)
    ✅ Simple, direct file access
    ❌ No built-in SQL queries

Using external tools (Spark/Athena)?
  → R2 Storage (Parquet with partitioning)
    ✅ Standard format, partition pruning for performance
    ❌ Must manage schema compatibility yourself

Common Use Cases Copy Chapter

• Analytics pipelines: Clickstream, telemetry, server logs
• Data warehousing: ETL into queryable Iceberg tables
• Event processing: Mobile/IoT with enrichment
• Ecommerce analytics: User events, purchases, views

Reading Order Copy Chapter

New to Pipelines? Start here:

1. configuration.md - Setup streams, sinks, pipelines
2. api.md - Send events, TypeScript types, SQL functions
3. patterns.md - Best practices, integrations, complete example
4. gotchas.md - Critical warnings, troubleshooting

Task-based routing:

• Setup pipeline → configuration.md
• Send/query data → api.md
• Implement pattern → patterns.md
• Debug issue → gotchas.md

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc bindings, schema definition, sink options, CLI commands
• api.md - Pipeline binding interface, send() method, HTTP ingest, SQL function reference
• patterns.md - Fire-and-forget, schema validation with Zod, integrations, performance tuning
• gotchas.md - Silent validation failures, immutable pipelines, latency expectations, limits

See Also Copy Chapter

• r2 - R2 storage backend for sinks
• queues - Compare with Queues for async processing
• workers - Worker runtime for event ingestion

Overview (`skills/.curated/cloudflare-deploy/references/pulumi/README.md`) Copy Section

Cloudflare Pulumi Provider

Expert guidance for Cloudflare Pulumi Provider (@pulumi/cloudflare).

Overview Copy Chapter

Programmatic management of Cloudflare resources: Workers, Pages, D1, KV, R2, DNS, Queues, etc.

Packages:

• TypeScript/JS: @pulumi/cloudflare
• Python: pulumi-cloudflare
• Go: github.com/pulumi/pulumi-cloudflare/sdk/v6/go/cloudflare
• .NET: Pulumi.Cloudflare

Version: v6.x

Core Principles Copy Chapter

1. Use API tokens (not legacy API keys)
2. Store accountId in stack config
3. Match binding names across code/config
4. Use module: true for ES modules
5. Set compatibilityDate to lock behavior

Authentication Copy Chapter

import * as cloudflare from "@pulumi/cloudflare";

// API Token (recommended): CLOUDFLARE_API_TOKEN env
const provider = new cloudflare.Provider("cf", { apiToken: process.env.CLOUDFLARE_API_TOKEN });

// API Key (legacy): CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL env
const provider = new cloudflare.Provider("cf", { apiKey: process.env.CLOUDFLARE_API_KEY, email: process.env.CLOUDFLARE_EMAIL });

// API User Service Key: CLOUDFLARE_API_USER_SERVICE_KEY env
const provider = new cloudflare.Provider("cf", { apiUserServiceKey: process.env.CLOUDFLARE_API_USER_SERVICE_KEY });

Setup Copy Chapter

Pulumi.yaml:

name: my-cloudflare-app
runtime: nodejs
config:
  cloudflare:apiToken:
    value: ${CLOUDFLARE_API_TOKEN}

Pulumi..yaml:

config:
  cloudflare:accountId: "abc123..."

index.ts:

import * as pulumi from "@pulumi/pulumi";
import * as cloudflare from "@pulumi/cloudflare";
const accountId = new pulumi.Config("cloudflare").require("accountId");

Common Resource Types Copy Chapter

• Provider - Provider config
• WorkerScript - Worker
• WorkersKvNamespace - KV
• R2Bucket - R2
• D1Database - D1
• Queue - Queue
• PagesProject - Pages
• DnsRecord - DNS
• WorkerRoute - Worker route
• WorkersDomain - Custom domain

Key Properties Copy Chapter

• accountId - Required for most resources
• zoneId - Required for DNS/domain
• name/title - Resource identifier
• *Bindings - Connect resources to Workers

Reading Order Copy Chapter

In This Reference Copy Chapter

• configuration.md - Provider config, stack setup, Workers/bindings
• api.md - Resource types, Workers script, KV/D1/R2/queues/Pages
• patterns.md - Multi-env, secrets, CI/CD, stack management
• gotchas.md - State issues, deployment failures, limits

See Also Copy Chapter

• terraform - Alternative IaC for Cloudflare
• wrangler - CLI deployment alternative
• workers - Worker runtime documentation

Overview (`skills/.curated/cloudflare-deploy/references/queues/README.md`) Copy Section

Cloudflare Queues

Flexible message queuing for async task processing with guaranteed at-least-once delivery and configurable batching.

Overview Copy Chapter

Queues provide:

• At-least-once delivery guarantee
• Push-based (Worker) and pull-based (HTTP) consumers
• Configurable batching and retries
• Dead Letter Queues (DLQ)
• Delays up to 12 hours

Use cases: Async processing, API buffering, rate limiting, event workflows, deferred jobs

Quick Start Copy Chapter

wrangler queues create my-queue
wrangler queues consumer add my-queue my-worker

// Producer
await env.MY_QUEUE.send({ userId: 123, action: 'notify' });

// Consumer (with proper error handling)
export default {
  async queue(batch: MessageBatch, env: Env): Promise<void> {
    for (const msg of batch.messages) {
      try {
        await process(msg.body);
        msg.ack();
      } catch (error) {
        msg.retry({ delaySeconds: 60 });
      }
    }
  }
};

Critical Warnings Copy Chapter

Before using Queues, understand these production mistakes:

1. Uncaught errors retry ENTIRE batch (not just failed message). Always use per-message try/catch.
2. Messages not ack'd/retry'd will auto-retry forever until max_retries. Always explicitly handle each message.

See gotchas.md for detailed solutions.

Core Operations Copy Chapter

Architecture Copy Chapter

[Producer Worker] → [Queue] → [Consumer Worker/HTTP] → [Processing]

• Max 10,000 queues per account
• 5,000 msgs/second per queue
• 4-14 day retention (configurable)

Reading Order Copy Chapter

New to Queues? Start here:

1. configuration.md - Set up queues, bindings, consumers
2. api.md - Send messages, handle batches, ack/retry patterns
3. patterns.md - Real-world examples and integrations
4. gotchas.md - Critical warnings and troubleshooting

Task-based routing:

• Setup queue → configuration.md
• Send/receive messages → api.md
• Implement specific pattern → patterns.md
• Debug/troubleshoot → gotchas.md

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc setup, producer/consumer config, DLQ, content types
• api.md - Send/batch methods, queue handler, ack/retry rules, type-safe patterns
• patterns.md - Async tasks, buffering, rate limiting, D1/Workflows/DO integrations
• gotchas.md - Critical batch error handling, idempotency, error classification

See Also Copy Chapter

• workers - Worker runtime for producers/consumers
• r2 - Process R2 event notifications via queues
• d1 - Batch write to D1 from queue consumers

Overview (`skills/.curated/cloudflare-deploy/references/r2-data-catalog/README.md`) Copy Section

Cloudflare R2 Data Catalog Skill Reference

Expert guidance for Cloudflare R2 Data Catalog - Apache Iceberg catalog built into R2 buckets.

Reading Order Copy Chapter

New to R2 Data Catalog? Start here:

1. Read "What is R2 Data Catalog?" and "When to Use" below
2. configuration.md - Enable catalog, create tokens
3. patterns.md - PyIceberg setup and common patterns
4. api.md - REST API reference as needed
5. gotchas.md - Troubleshooting when issues arise

Quick reference? Jump to:

• Enable catalog on bucket
• PyIceberg connection pattern
• Permission errors

What is R2 Data Catalog? Copy Chapter

R2 Data Catalog is a managed Apache Iceberg REST catalog built directly into R2 buckets. It provides:

• Apache Iceberg tables - ACID transactions, schema evolution, time-travel queries
• Zero-egress costs - Query from any cloud/region without data transfer fees
• Standard REST API - Works with Spark, PyIceberg, Snowflake, Trino, DuckDB
• No infrastructure - Fully managed, no catalog servers to run
• Public beta - Available to all R2 subscribers, no extra cost beyond R2 storage

What is Apache Iceberg? Copy Section

Open table format for analytics datasets in object storage. Features:

• ACID transactions - Safe concurrent reads/writes
• Metadata optimization - Fast queries without full scans
• Schema evolution - Add/rename/delete columns without rewrites
• Time-travel - Query historical snapshots
• Partitioning - Organize data for efficient queries

When to Use Copy Chapter

Use R2 Data Catalog for:

• Log analytics - Store and query application/system logs
• Data lakes/warehouses - Analytical datasets queried by multiple engines
• BI pipelines - Aggregate data for dashboards and reports
• Multi-cloud analytics - Share data across clouds without egress fees
• Time-series data - Event streams, metrics, sensor data

Don't use for:

• Transactional workloads - Use D1 or external database instead
• Sub-second latency - Iceberg optimized for batch/analytical queries
• Small datasets (<1GB) - Setup overhead not worth it
• Unstructured data - Store files directly in R2, not as Iceberg tables

Architecture Copy Chapter

┌─────────────────────────────────────────────────┐
│  Query Engines                                  │
│  (PyIceberg, Spark, Trino, Snowflake, DuckDB)  │
└────────────────┬────────────────────────────────┘
                 │
                 │ REST API (OAuth2 token)
                 ▼
┌─────────────────────────────────────────────────┐
│  R2 Data Catalog (Managed Iceberg REST Catalog)│
│  • Namespace/table metadata                     │
│  • Transaction coordination                     │
│  • Snapshot management                          │
└────────────────┬────────────────────────────────┘
                 │
                 │ Vended credentials
                 ▼
┌─────────────────────────────────────────────────┐
│  R2 Bucket Storage                              │
│  • Parquet data files                           │
│  • Metadata files                               │
│  • Manifest files                               │
└─────────────────────────────────────────────────┘

Key concepts:

• Catalog URI - REST endpoint for catalog operations (e.g., https://<account-id>.r2.cloudflarestorage.com/iceberg/)
• Warehouse - Logical grouping of tables (typically same as bucket name)
• Namespace - Schema/database containing tables (e.g., logs, analytics)
• Table - Iceberg table with schema, data files, snapshots
• Vended credentials - Temporary S3 credentials catalog provides for data access

Limits Copy Chapter

Current Status Copy Chapter

Public Beta (as of Jan 2026)

• Available to all R2 subscribers
• No extra cost beyond standard R2 storage/operations
• Production-ready, but breaking changes possible
• Supports: namespaces, tables, snapshots, compaction, time-travel, table maintenance

Decision Tree: Is R2 Data Catalog Right For You? Copy Chapter

Start → Need analytics on object storage data?
         │
         ├─ No → Use R2 directly for object storage
         │
         └─ Yes → Dataset >1GB with structured schema?
                  │
                  ├─ No → Too small, use R2 + ad-hoc queries
                  │
                  └─ Yes → Need ACID transactions or schema evolution?
                           │
                           ├─ No → Consider simpler solutions (Parquet on R2)
                           │
                           └─ Yes → Need multi-cloud/multi-tool access?
                                    │
                                    ├─ No → D1 or external DB may be simpler
                                    │
                                    └─ Yes → ✅ Use R2 Data Catalog

Quick check: If you answer "yes" to all:

• Dataset >1GB and growing
• Structured/tabular data (logs, events, metrics)
• Multiple query tools or cloud environments
• Need versioning, schema changes, or concurrent access

→ R2 Data Catalog is a good fit.

In This Reference Copy Chapter

• configuration.md - Enable catalog, create API tokens, connect clients
• api.md - REST endpoints, operations, maintenance
• patterns.md - PyIceberg examples, common use cases
• gotchas.md - Troubleshooting, best practices, limitations

See Also Copy Chapter

• Cloudflare R2 Data Catalog Docs
• Apache Iceberg Docs
• PyIceberg Docs

Overview (`skills/.curated/cloudflare-deploy/references/r2-sql/README.md`) Copy Section

Cloudflare R2 SQL Skill Reference

Expert guidance for Cloudflare R2 SQL - serverless distributed query engine for Apache Iceberg tables.

Reading Order Copy Chapter

New to R2 SQL? Start here:

1. Read "What is R2 SQL?" and "When to Use" below
2. configuration.md - Enable catalog, create tokens
3. patterns.md - Wrangler CLI and integration examples
4. api.md - SQL syntax and query reference
5. gotchas.md - Limitations and troubleshooting

Quick reference? Jump to:

• Run a query via Wrangler
• SQL syntax reference
• ORDER BY limitations

What is R2 SQL? Copy Chapter

R2 SQL is Cloudflare's serverless distributed analytics query engine for querying Apache Iceberg tables in R2 Data Catalog. Features:

• Serverless - No clusters to manage, no infrastructure
• Distributed - Leverages Cloudflare's global network for parallel execution
• SQL interface - Familiar SQL syntax for analytics queries
• Zero egress fees - Query from any cloud/region without data transfer costs
• Open beta - Free during beta (standard R2 storage costs apply)

What is Apache Iceberg? Copy Section

Open table format for large-scale analytics datasets in object storage:

• ACID transactions - Safe concurrent reads/writes
• Metadata optimization - Fast queries without full table scans
• Schema evolution - Add/rename/drop columns without rewrites
• Partitioning - Organize data for efficient pruning

When to Use Copy Chapter

Use R2 SQL for:

• Log analytics - Query application/system logs with WHERE filters and aggregations
• BI dashboards - Generate reports from large analytical datasets
• Fraud detection - Analyze transaction patterns with GROUP BY/HAVING
• Multi-cloud analytics - Query data from any cloud without egress fees
• Ad-hoc exploration - Run SQL queries on Iceberg tables via Wrangler CLI

Don't use R2 SQL for:

• Workers/Pages runtime - R2 SQL has no Workers binding, use HTTP API from external systems
• Real-time queries (<100ms) - Optimized for analytical batch queries, not OLTP
• Complex joins/CTEs - Limited SQL feature set (no JOINs, subqueries, CTEs currently)
• Small datasets (<1GB) - Setup overhead not justified

Decision Tree: Need to Query R2 Data? Copy Chapter

Do you need to query structured data in R2?
├─ YES, data is in Iceberg tables
│  ├─ Need SQL interface? → Use R2 SQL (this reference)
│  ├─ Need Python API? → See r2-data-catalog reference (PyIceberg)
│  └─ Need other engine? → See r2-data-catalog reference (Spark, Trino, etc.)
│
├─ YES, but not in Iceberg format
│  ├─ Streaming data? → Use Pipelines to write to Data Catalog, then R2 SQL
│  └─ Static files? → Use PyIceberg to create Iceberg tables, then R2 SQL
│
└─ NO, just need object storage → Use R2 reference (not R2 SQL)

Architecture Overview Copy Chapter

Query Planner:

• Top-down metadata investigation with multi-layer pruning
• Partition-level, column-level, and row-group pruning
• Streaming pipeline - execution starts before planning completes
• Early termination with LIMIT - stops when result complete

Query Execution:

• Coordinator distributes work to workers across Cloudflare network
• Workers run Apache DataFusion for parallel query execution
• Parquet column pruning - reads only required columns
• Ranged reads from R2 for efficiency

Aggregation Strategies:

• Scatter-gather - simple aggregations (SUM, COUNT, AVG)
• Shuffling - ORDER BY/HAVING on aggregates via hash partitioning

Quick Start Copy Chapter

# 1. Enable R2 Data Catalog on bucket
npx wrangler r2 bucket catalog enable my-bucket

# 2. Create API token (Admin Read & Write)
# Dashboard: R2 → Manage API tokens → Create API token

# 3. Set environment variable
export WRANGLER_R2_SQL_AUTH_TOKEN=<your-token>

# 4. Run query
npx wrangler r2 sql query "my-bucket" "SELECT * FROM default.my_table LIMIT 10"

Important Limitations Copy Chapter

CRITICAL: No Workers Binding

• R2 SQL cannot be called directly from Workers/Pages code
• For programmatic access, use HTTP API from external systems
• Or query via PyIceberg, Spark, etc. (see r2-data-catalog reference)

SQL Feature Set:

• No JOINs, CTEs, subqueries, window functions
• ORDER BY supports aggregation columns (not just partition keys)
• LIMIT max 10,000 (default 500)
• See gotchas.md for complete limitations

In This Reference Copy Chapter

• configuration.md - Enable catalog, create API tokens
• api.md - SQL syntax, functions, operators, data types
• patterns.md - Wrangler CLI, HTTP API, Pipelines, PyIceberg
• gotchas.md - Limitations, troubleshooting, performance tips

See Also Copy Chapter

• r2-data-catalog - PyIceberg, REST API, external engines
• pipelines - Streaming ingestion to Iceberg tables
• r2 - R2 object storage fundamentals
• Cloudflare R2 SQL Docs
• R2 SQL Deep Dive Blog

Overview (`skills/.curated/cloudflare-deploy/references/r2/README.md`) Copy Section

Cloudflare R2 Object Storage

S3-compatible object storage with zero egress fees, optimized for large file storage and delivery.

Overview Copy Chapter

R2 provides:

• S3-compatible API (Workers API + S3 REST)
• Zero egress fees globally
• Strong consistency for writes/deletes
• Storage classes (Standard/Infrequent Access)
• SSE-C encryption support

Use cases: Media storage, backups, static assets, user uploads, data lakes

Quick Start Copy Chapter

wrangler r2 bucket create my-bucket --location=enam
wrangler r2 object put my-bucket/file.txt --file=./local.txt

// Upload
await env.MY_BUCKET.put(key, data, {
  httpMetadata: { contentType: 'image/jpeg' }
});

// Download
const object = await env.MY_BUCKET.get(key);
if (object) return new Response(object.body);

Core Operations Copy Chapter

Storage Classes Copy Chapter

• Standard: Frequent access, low latency reads
• InfrequentAccess: 30-day minimum storage, retrieval fees, lower storage cost

Event Notifications Copy Chapter

R2 integrates with Cloudflare Queues for reactive workflows:

// wrangler.jsonc
{
  "event_notifications": [{
    "queue": "r2-notifications",
    "actions": ["PutObject", "DeleteObject"]
  }]
}

// Consumer
async queue(batch: MessageBatch, env: Env) {
  for (const message of batch.messages) {
    const event = message.body; // { action, bucket, object, timestamps }
    if (event.action === 'PutObject') {
      // Process upload: thumbnail generation, virus scan, etc.
    }
  }
}

Reading Order Copy Chapter

First-time users: README → configuration.md → api.md → patterns.md
Specific tasks:

• Setup: configuration.md
• Client uploads: patterns.md (presigned URLs)
• Public static site: patterns.md (public access + custom domain)
• Processing uploads: README (event notifications) + queues reference
• Debugging: gotchas.md

In This Reference Copy Chapter

• configuration.md - Bindings, S3 SDK, CORS, lifecycles, token scopes
• api.md - Workers API, multipart, conditional requests, presigned URLs
• patterns.md - Streaming, caching, client uploads, public buckets
• gotchas.md - List truncation, etag format, stream length, S3 SDK region

See Also Copy Chapter

• workers - Worker runtime and fetch handlers
• kv - Metadata storage for R2 objects
• d1 - Store R2 URLs in relational database
• queues - Process R2 uploads asynchronously

Overview (`skills/.curated/cloudflare-deploy/references/realtime-sfu/README.md`) Copy Section

Cloudflare Realtime SFU Reference

Expert guidance for building real-time audio/video/data applications using Cloudflare Realtime SFU (Selective Forwarding Unit).

Reading Order Copy Chapter

In This Reference Copy Chapter

• configuration.md - Setup, deployment, environment variables, Wrangler config
• api.md - Sessions, tracks, endpoints, request/response patterns
• patterns.md - Architecture patterns, use cases, integration examples
• gotchas.md - Common issues, debugging, performance, security

Quick Start Copy Chapter

Cloudflare Realtime SFU: WebRTC infrastructure on global network (310+ cities). Anycast routing, no regional constraints, pub/sub model.

Core concepts:

• Sessions: WebRTC PeerConnection to Cloudflare edge
• Tracks: Audio/video/data channels you publish or subscribe to
• No rooms: Build presence layer yourself via track sharing (see patterns.md)

Mental model: Your client establishes one WebRTC session, publishes tracks (audio/video), shares track IDs via your backend, others subscribe to your tracks using track IDs + your session ID.

Choose Your Approach Copy Chapter

Recommendation: Start with PartyTracks for most production applications. See patterns.md for PartyTracks examples.

SFU vs RealtimeKit Copy Chapter

• Realtime SFU: WebRTC infrastructure (this reference). Build your own signaling, presence, UI.
• RealtimeKit: SDK layer on top of SFU. Includes React hooks, state management, UI components. Part of Cloudflare AI platform.

Use SFU directly when you need custom signaling or non-React framework. Use RealtimeKit for faster development with React.

Setup Copy Chapter

Dashboard: https://dash.cloudflare.com/?to=/:account/calls

Get CALLS_APP_ID and CALLS_APP_SECRET from dashboard, then see configuration.md for deployment.

See Also Copy Chapter

• Orange Meets Demo
• Orange Source
• Calls Examples
• API Reference
• RealtimeKit Docs

Overview (`skills/.curated/cloudflare-deploy/references/realtimekit/README.md`) Copy Section

Cloudflare RealtimeKit

Expert guidance for building real-time video and audio applications using Cloudflare RealtimeKit - a comprehensive SDK suite for adding customizable live video and voice to web or mobile applications.

Overview Copy Chapter

RealtimeKit is Cloudflare's SDK suite built on Realtime SFU, abstracting WebRTC complexity with fast integration, pre-built UI components, global performance (300+ cities), and production features (recording, transcription, chat, polls).

Use cases: Team meetings, webinars, social video, audio calls, interactive plugins

Core Concepts Copy Chapter

• App: Workspace grouping meetings, participants, presets, recordings. Use separate Apps for staging/production
• Meeting: Re-usable virtual room. Each join creates new Session
• Session: Live meeting instance. Created on first join, ends after last leave
• Participant: User added via REST API. Returns authToken for client SDK. Do not reuse tokens
• Preset: Reusable permission/UI template (permissions, meeting type, theme). Applied at participant creation
• Peer ID (id): Unique per session, changes on rejoin
• Participant ID (userId): Persistent across sessions

Quick Start Copy Chapter

1. Create App & Meeting (Backend) Copy Section

# Create app
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/apps' \
  -H 'Authorization: Bearer <api_token>' \
  -d '{"name": "My RealtimeKit App"}'

# Create meeting
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings' \
  -H 'Authorization: Bearer <api_token>' \
  -d '{"title": "Team Standup"}'

# Add participant
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings/<meeting_id>/participants' \
  -H 'Authorization: Bearer <api_token>' \
  -d '{"name": "Alice", "preset_name": "host"}'
# Returns: { authToken }

2. Client Integration Copy Section

React:

import { RtkMeeting } from '@cloudflare/realtimekit-react-ui';

function App() {
  return <RtkMeeting authToken="<participant_auth_token>" onLeave={() => {}} />;
}

Core SDK:

import RealtimeKitClient from '@cloudflare/realtimekit';

const meeting = new RealtimeKitClient({ authToken: '<token>', video: true, audio: true });
await meeting.join();

Reading Order Copy Chapter

RealtimeKit vs Realtime SFU Copy Chapter

RealtimeKit is built on Realtime SFU but abstracts WebRTC complexity with UI components and SDKs.

Which Package? Copy Chapter

Need pre-built meeting UI?

• React → @cloudflare/realtimekit-react-ui (<RtkMeeting>)
• Angular → @cloudflare/realtimekit-angular-ui
• HTML/Vanilla → @cloudflare/realtimekit-ui

Need custom UI?

• Core SDK → @cloudflare/realtimekit (RealtimeKitClient) - full control

Need raw WebRTC control?

• See realtime-sfu/ reference

In This Reference Copy Chapter

• Configuration - Setup, installation, wrangler config
• API - Meeting object, REST API, SDK methods
• Patterns - Common workflows, code examples
• Gotchas - Common issues, troubleshooting

See Also Copy Chapter

• Workers - Backend integration
• D1 - Meeting metadata storage
• R2 - Recording storage
• KV - Session management

Reference Links Copy Chapter

• Official Docs: https://developers.cloudflare.com/realtime/realtimekit/
• API Reference: https://developers.cloudflare.com/api/resources/realtime_kit/
• Examples: https://github.com/cloudflare/realtimekit-web-examples
• Dashboard: https://dash.cloudflare.com/?to=/:account/realtime/kit

Overview (`skills/.curated/cloudflare-deploy/references/sandbox/README.md`) Copy Section

Cloudflare Sandbox SDK

Secure isolated code execution in containers on Cloudflare's edge. Run untrusted code, manage files, expose services, integrate with AI agents.

Use cases: AI code execution, interactive dev environments, data analysis, CI/CD, code interpreters, multi-tenant execution.

Architecture Copy Chapter

• Each sandbox = Durable Object + Container
• Persistent across requests (same ID = same sandbox)
• Isolated filesystem/processes/network
• Configurable sleep/wake for cost optimization

Quick Start Copy Chapter

import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';

type Env = { Sandbox: DurableObjectNamespace<Sandbox>; };

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // CRITICAL: proxyToSandbox MUST be called first for preview URLs
    const proxyResponse = await proxyToSandbox(request, env);
    if (proxyResponse) return proxyResponse;

    const sandbox = getSandbox(env.Sandbox, 'my-sandbox');
    const result = await sandbox.exec('python3 -c "print(2 + 2)"');
    return Response.json({ output: result.stdout });
  }
};

wrangler.jsonc:

{
  "name": "my-sandbox-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01", // Use current date for new projects
  
  "containers": [{
    "class_name": "Sandbox",
    "image": "./Dockerfile",
    "instance_type": "lite",        // lite | standard | heavy
    "max_instances": 5
  }],
  
  "durable_objects": {
    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }]
  },
  
  "migrations": [{
    "tag": "v1",
    "new_sqlite_classes": ["Sandbox"]
  }]
}

Dockerfile:

FROM docker.io/cloudflare/sandbox:latest
RUN pip3 install --no-cache-dir pandas numpy matplotlib
EXPOSE 8080 3000  # Required for wrangler dev

Core APIs Copy Chapter

• getSandbox(namespace, id, options?) → Get/create sandbox
• sandbox.exec(command, options?) → Execute command
• sandbox.readFile(path) / writeFile(path, content) → File ops
• sandbox.startProcess(command, options) → Background process
• sandbox.exposePort(port, options) → Get preview URL
• sandbox.createSession(options) → Isolated session
• sandbox.wsConnect(request, port) → WebSocket proxy
• sandbox.destroy() → Terminate container
• sandbox.mountBucket(bucket, path, options) → Mount S3 storage

Critical Rules Copy Chapter

• ALWAYS call proxyToSandbox() first
• Same ID = reuse sandbox
• Use /workspace for persistent files
• normalizeId: true for preview URLs
• Retry on CONTAINER_NOT_READY

In This Reference Copy Chapter

• configuration.md - Config, CLI, environment setup
• api.md - Programmatic API, testing patterns
• patterns.md - Common workflows, CI/CD integration
• gotchas.md - Issues, limits, best practices

See Also Copy Chapter

• durable-objects - Sandbox runs on DO infrastructure
• containers - Container runtime fundamentals
• workers - Entry point for sandbox requests

Overview (`skills/.curated/cloudflare-deploy/references/secrets-store/README.md`) Copy Section

Cloudflare Secrets Store

Account-level encrypted secret management for Workers and AI Gateway.

Overview Copy Chapter

Secrets Store: Centralized, account-level secrets, reusable across Workers
Worker Secrets: Per-Worker secrets (wrangler secret put)

Architecture Copy Section

• Store: Container (1/account in beta)
• Secret: String ≤1024 bytes
• Scopes: Permission boundaries controlling access
  • workers: For Workers runtime access
  • ai-gateway: For AI Gateway access
  • Secrets must have correct scope for binding to work
• Bindings: Connect secrets via env object

Regional Availability: Global except China Network (unavailable)

Access Control Copy Section

• Super Admin: Full access
• Admin: Create/edit/delete secrets, view metadata
• Deployer: View metadata + bindings
• Reporter: View metadata only

API Token permissions: Account Secrets Store Edit/Read

Limits (Beta) Copy Section

• 100 secrets/account
• 1 store/account
• 1024 bytes max/secret
• Production secrets count toward limit

When to Use Copy Chapter

Use Secrets Store when:

• Multiple Workers share same credential
• Centralized management needed
• Compliance requires audit trail
• Team collaboration on secrets

Use Worker Secrets when:

• Secret unique to one Worker
• Simple single-Worker project
• No cross-Worker sharing needed

In This Reference Copy Chapter

Reading Order by Task Copy Section

Files Copy Section

• configuration.md - Wrangler commands, binding config
• api.md - Binding API, get/put/delete operations
• patterns.md - Rotation, encryption, access control
• gotchas.md - Security issues, limits, best practices

See Also Copy Chapter

• workers - Worker bindings integration
• wrangler - CLI secret management commands

Overview (`skills/.curated/cloudflare-deploy/references/smart-placement/README.md`) Copy Section

Cloudflare Workers Smart Placement

Automatic workload placement optimization to minimize latency by running Workers closer to backend infrastructure rather than end users.

Core Concept Copy Chapter

Smart Placement automatically analyzes Worker request duration across Cloudflare's global network and intelligently routes requests to optimal data center locations. Instead of defaulting to the location closest to the end user, Smart Placement can forward requests to locations closer to backend infrastructure when this reduces overall request duration.

When to Use Copy Section

Enable Smart Placement when:

• Worker makes multiple round trips to backend services/databases
• Backend infrastructure is geographically concentrated
• Request duration dominated by backend latency rather than network latency from user
• Running backend logic in Workers (APIs, data aggregation, SSR with DB calls)
• Worker uses fetch handler (not RPC methods)

Do NOT enable for:

• Workers serving only static content or cached responses
• Workers without significant backend communication
• Pure edge logic (auth checks, redirects, simple transformations)
• Workers without fetch event handlers
• Workers with RPC methods or named entrypoints (only fetch handlers are affected)
• Pages/Assets Workers with run_worker_first = true (degrades asset serving)

Decision Tree Copy Section

Does your Worker have a fetch handler?
├─ No → Smart Placement won't work (skip)
└─ Yes
   │
   Does it make multiple backend calls (DB/API)?
   ├─ No → Don't enable (won't help)
   └─ Yes
      │
      Is backend geographically concentrated?
      ├─ No (globally distributed) → Probably won't help
      └─ Yes or uncertain
         │
         Does it serve static assets with run_worker_first=true?
         ├─ Yes → Don't enable (will hurt performance)
         └─ No → Enable Smart Placement
            │
            After 15min, check placement_status
            ├─ SUCCESS → Monitor metrics
            ├─ INSUFFICIENT_INVOCATIONS → Need more traffic
            └─ UNSUPPORTED_APPLICATION → Disable (hurting performance)

Key Architecture Pattern Copy Section

Recommended: Split full-stack applications into separate Workers:

User → Frontend Worker (at edge, close to user)
         ↓ Service Binding
       Backend Worker (Smart Placement enabled, close to DB/API)
         ↓
       Database/Backend Service

This maintains fast, reactive frontends while optimizing backend latency.

Quick Start Copy Chapter

// wrangler.jsonc
{
  "placement": {
    "mode": "smart"  // or "off" to explicitly disable
  }
}

Deploy and wait 15 minutes for analysis. Check status via API or dashboard metrics.

To disable: Set "mode": "off" or remove placement field entirely (both equivalent).

Requirements Copy Chapter

• Wrangler 2.20.0+
• Analysis time: Up to 15 minutes after enabling
• Traffic requirements: Consistent traffic from multiple global locations
• Available on all Workers plans (Free, Paid, Enterprise)

Placement Status Values Copy Chapter

type PlacementStatus = 
  | undefined  // Not yet analyzed
  | 'SUCCESS'  // Successfully optimized
  | 'INSUFFICIENT_INVOCATIONS'  // Not enough traffic
  | 'UNSUPPORTED_APPLICATION';  // Made Worker slower (reverted)

CLI Commands Copy Chapter

# Deploy with Smart Placement
wrangler deploy

# Check placement status
curl -H "Authorization: Bearer $TOKEN" \
  https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
  | jq .result.placement_status

# Monitor
wrangler tail your-worker-name --header cf-placement

Reading Order Copy Chapter

First time? Start here:

1. This README - understand core concepts and when to use Smart Placement
2. configuration.md - set up wrangler.jsonc and understand limitations
3. patterns.md - see practical examples for your use case
4. api.md - monitor and verify Smart Placement is working
5. gotchas.md - troubleshoot common issues

Quick lookup:

• "Should I enable Smart Placement?" → See "When to Use" above
• "How do I configure it?" → configuration.md
• "How do I split frontend/backend?" → patterns.md
• "Why isn't it working?" → gotchas.md

In This Reference Copy Chapter

• configuration.md - wrangler.jsonc setup, mode values, validation rules
• api.md - Placement Status API, cf-placement header, monitoring
• patterns.md - Frontend/backend split, database workers, SSR patterns
• gotchas.md - Troubleshooting INSUFFICIENT_INVOCATIONS, performance issues

See Also Copy Chapter

• workers - Worker runtime and fetch handlers
• d1 - D1 database that benefits from Smart Placement
• durable-objects - Durable Objects with backend logic
• bindings - Service bindings for frontend/backend split

Overview (`skills/.curated/cloudflare-deploy/references/snippets/README.md`) Copy Section

Cloudflare Snippets Skill Reference

Description Copy Chapter

Expert guidance for Cloudflare Snippets ONLY - a lightweight JavaScript-based edge logic platform for modifying HTTP requests and responses. Snippets run as part of the Ruleset Engine and are included at no additional cost on paid plans (Pro, Business, Enterprise).

What Are Snippets? Copy Chapter

Snippets are JavaScript functions executed at the edge as part of Cloudflare's Ruleset Engine. Key characteristics:

• Execution time: 5ms CPU limit per request
• Size limit: 32KB per snippet
• Runtime: V8 isolate (subset of Workers APIs)
• Subrequests: 2-5 fetch calls depending on plan
• Cost: Included with Pro/Business/Enterprise plans

Snippets vs Workers Decision Matrix Copy Chapter

Rule of thumb: Use Snippets for modifications, Workers for applications.

Execution Model Copy Chapter

1. Request arrives at Cloudflare edge
2. Ruleset Engine evaluates snippet rules (filter expressions)
3. If rule matches, snippet executes within 5ms limit
4. Modified request/response continues through pipeline
5. Response returned to client

Snippets execute synchronously in the request path - performance is critical.

Reading Order Copy Chapter

1. configuration.md - Start here: setup, deployment methods (Dashboard/API/Terraform)
2. api.md - Core APIs: Request, Response, headers, request.cf properties
3. patterns.md - Real-world examples: geo-routing, A/B tests, security headers
4. gotchas.md - Troubleshooting: common errors, performance tips, API limitations

In This Reference Copy Chapter

• configuration.md - Setup, deployment, configuration
• api.md - API endpoints, methods, interfaces
• patterns.md - Common patterns, use cases, examples
• gotchas.md - Troubleshooting, best practices, limitations

Quick Start Copy Chapter

// Snippet: Add security headers
export default {
  async fetch(request) {
    const response = await fetch(request);
    const newResponse = new Response(response.body, response);
    newResponse.headers.set("X-Frame-Options", "DENY");
    newResponse.headers.set("X-Content-Type-Options", "nosniff");
    return newResponse;
  }
}

Deploy via Dashboard (Rules → Snippets) or API/Terraform. See configuration.md for details.

See Also Copy Chapter

• Cloudflare Docs

Overview (`skills/.curated/cloudflare-deploy/references/spectrum/README.md`) Copy Section

Cloudflare Spectrum Skill Reference

Overview Copy Chapter

Cloudflare Spectrum provides security and acceleration for ANY TCP or UDP-based application. It's a global Layer 4 (L4) reverse proxy running on Cloudflare's edge nodes that routes MQTT, email, file transfer, version control, games, and more through Cloudflare to mask origins and protect from DDoS attacks.

When to Use Spectrum: When your protocol isn't HTTP/HTTPS (use Cloudflare proxy for HTTP). Spectrum handles everything else: SSH, gaming, databases, MQTT, SMTP, RDP, custom protocols.

Plan Capabilities Copy Chapter

Decision Tree Copy Chapter

What are you trying to do?

1. Create/manage Spectrum app

   • Via Dashboard → See Cloudflare Dashboard
   • Via API → See api.md - REST endpoints
   • Via SDK → See api.md - TypeScript/Python/Go examples
   • Via IaC → See configuration.md - Terraform/Pulumi

2. Protect specific protocol

   • SSH → See patterns.md
   • Gaming (Minecraft, etc) → See patterns.md
   • MQTT/IoT → See patterns.md
   • SMTP/Email → See patterns.md
   • Database → See patterns.md
   • RDP → See patterns.md

3. Choose origin type

   • Direct IP (single server) → See configuration.md
   • CNAME (hostname) → See configuration.md
   • Load balancer (HA/failover) → See configuration.md

Reading Order Copy Chapter

1. Start with patterns.md for your specific protocol
2. Then configuration.md for your origin type
3. Check gotchas.md before going to production
4. Use api.md for programmatic access

See Also Copy Chapter

• Cloudflare Docs

Overview (`skills/.curated/cloudflare-deploy/references/static-assets/README.md`) Copy Section

Cloudflare Static Assets Skill Reference

Expert guidance for deploying and configuring static assets with Cloudflare Workers. This skill covers configuration patterns, routing architectures, asset binding usage, and best practices for SPAs, SSG sites, and full-stack applications.

Quick Start Copy Chapter

// wrangler.jsonc
{
  "name": "my-app",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "assets": {
    "directory": "./dist"
  }
}

// src/index.ts
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    return env.ASSETS.fetch(request);
  }
};

Deploy: wrangler deploy

When to Use Workers Static Assets vs Pages Copy Chapter

Decision tree:

• Need custom routing logic? → Workers Static Assets
• Pure static site or SSG? → Pages
• API routes + SPA? → Workers Static Assets
• Framework (Next, Nuxt, Remix)? → Pages

Reading Order Copy Chapter

1. configuration.md - Setup, wrangler.jsonc options, routing patterns
2. api.md - ASSETS binding API, request/response handling
3. patterns.md - Common patterns (SPA, API routes, auth, A/B testing)
4. gotchas.md - Limits, errors, performance tips

In This Reference Copy Chapter

• configuration.md - Setup, deployment, configuration
• api.md - API endpoints, methods, interfaces
• patterns.md - Common patterns, use cases, examples
• gotchas.md - Troubleshooting, best practices, limitations

See Also Copy Chapter

• Cloudflare Workers Docs
• Static Assets Docs
• Cloudflare Pages

Overview (`skills/.curated/cloudflare-deploy/references/stream/README.md`) Copy Section

Cloudflare Stream

Serverless live and on-demand video streaming platform with one API.

Overview Copy Chapter

Cloudflare Stream provides video upload, storage, encoding, and delivery without managing infrastructure. Runs on Cloudflare's global network.

Key Features Copy Section

• On-demand video: Upload, encode, store, deliver
• Live streaming: RTMPS/SRT ingestion with ABR
• Direct creator uploads: End users upload without API keys
• Signed URLs: Token-based access control
• Analytics: Server-side metrics via GraphQL
• Webhooks: Processing notifications
• Captions: Upload or AI-generate subtitles
• Watermarks: Apply branding to videos
• Downloads: Enable MP4 offline viewing

Core Concepts Copy Chapter

Video Upload Methods Copy Section

1. API Upload (TUS protocol): Direct server upload
2. Upload from URL: Import from external source
3. Direct Creator Uploads: User-generated content (recommended)

Playback Options Copy Section

1. Stream Player (iframe): Built-in, optimized player
2. Custom Player (HLS/DASH): Video.js, HLS.js integration
3. Thumbnails: Static or animated previews

Access Control Copy Section

• Public: No restrictions
• requireSignedURLs: Token-based access
• allowedOrigins: Domain restrictions
• Access Rules: Geo/IP restrictions in tokens

Live Streaming Copy Section

• RTMPS/SRT ingest from OBS, FFmpeg
• Automatic recording to on-demand
• Simulcast to YouTube, Twitch, etc.
• WebRTC support for browser streaming

Quick Start Copy Chapter

Upload video via API

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/video.mp4"}'

Embed player

<iframe
  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/iframe"
  style="border: none;"
  height="720" width="1280"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>

Create live input

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"recording": {"mode": "automatic"}}'

Limits Copy Chapter

• Max file size: 30 GB
• Max frame rate: 60 fps (recommended)
• Supported formats: MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime

Pricing Copy Chapter

• $5/1000 min stored
• $1/1000 min delivered

Resources Copy Chapter

• Dashboard: https://dash.cloudflare.com/?to=/:account/stream
• API Docs: https://developers.cloudflare.com/api/resources/stream/
• Stream Docs: https://developers.cloudflare.com/stream/

Reading Order Copy Chapter

In This Reference Copy Chapter

• configuration.md - Setup, environment variables, wrangler config
• api.md - On-demand video upload, playback, management APIs
• api-live.md - Live streaming (RTMPS/SRT/WebRTC), simulcast
• patterns.md - Full-stack flows, state management, best practices
• gotchas.md - Error codes, troubleshooting, limits

See Also Copy Chapter

• workers - Deploy Stream APIs in Workers
• pages - Integrate Stream with Pages
• workers-ai - AI-generate captions

Overview (`skills/.curated/cloudflare-deploy/references/tail-workers/README.md`) Copy Section

Cloudflare Tail Workers

Specialized Workers that consume execution events from producer Workers for logging, debugging, analytics, and observability.

When to Use This Reference Copy Chapter

• Implementing observability/logging for Cloudflare Workers
• Processing Worker execution events, logs, exceptions
• Building custom analytics or error tracking
• Configuring real-time event streaming
• Working with tail handlers or tail consumers

Core Concepts Copy Chapter

What Are Tail Workers? Copy Section

Tail Workers automatically process events from producer Workers (the Workers being monitored). They receive:

• HTTP request/response info
• Console logs (console.log/error/warn/debug)
• Uncaught exceptions
• Execution outcomes (ok, exception, exceededCpu, etc.)
• Diagnostic channel events

Key characteristics:

• Invoked AFTER producer finishes executing
• Capture entire request lifecycle including Service Bindings and Dynamic Dispatch sub-requests
• Billed by CPU time, not request count
• Available on Workers Paid and Enterprise tiers

Alternative: OpenTelemetry Export Copy Section

Before using Tail Workers, consider OpenTelemetry:

For batch exports to observability tools (Sentry, Grafana, Honeycomb):

• OTEL export sends logs/traces in batches (more efficient)
• Built-in integrations with popular platforms
• Lower overhead than Tail Workers
• Use Tail Workers only for custom real-time processing

Decision Tree Copy Chapter

Need observability for Workers?
├─ Batch export to known tools (Sentry/Grafana/Honeycomb)?
│  └─ Use OpenTelemetry export (not Tail Workers)
├─ Custom real-time processing needed?
│  ├─ Aggregated metrics?
│  │  └─ Use Tail Worker + Analytics Engine
│  ├─ Error tracking?
│  │  └─ Use Tail Worker + external service
│  ├─ Custom logging/debugging?
│  │  └─ Use Tail Worker + KV/HTTP endpoint
│  └─ Complex event processing?
│     └─ Use Tail Worker + Durable Objects
└─ Quick debugging?
   └─ Use `wrangler tail` (different from Tail Workers)

Reading Order Copy Chapter

1. configuration.md - Set up Tail Workers
2. api.md - Handler signature, types, redaction
3. patterns.md - Common use cases and integrations
4. gotchas.md - Pitfalls and debugging tips

Quick Example Copy Chapter