autoskills Documentation

Technical Documentation: midudev/autoskills

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Scans your project, detects your tech stack, and installs curated AI agent skills automatically.

npx autoskills

How it works Copy Chapter

1. Run npx autoskills in your project root
2. Your package.json, Gradle files, and config files are scanned to detect technologies
3. The best matching AI agent skills are selected from the audited autoskills registry
4. Only the selected skill files are downloaded from the registry and verified before writing them locally

That's it. No config needed.

Security model Copy Chapter

autoskills does not install directly from random upstream repositories at runtime.

Skills are synced by maintainers into the repository-local autoskills registry, reviewed by AI for prompt-injection and supply-chain attacks (a fast model triages every change and a stronger one decides on anything suspicious), and recorded with SHA-256 hashes in a manifest. Skills that are safe but worth a heads-up are shown with a security warning before you install them. When you run autoskills, the CLI downloads only the skills your project needs from that curated registry, verifies every file against the manifest, and writes a skills-lock.json entry with the installed source and bundle hash.

This keeps the package small while avoiding live downloads from third-party skill sources during installation.

Options Copy Chapter

-y, --yes       Skip confirmation prompt
--dry-run       Show what would be installed without installing
--clear-cache   Clear the downloaded skills cache
-a, --agent     Install for specific IDEs only (e.g. cursor claude-code)
-v, --verbose   Show install trace and error details
-h, --help      Show help message

Run npx autoskills ui to browse the skills installed in your project in a local web desk.

Supported Technologies Copy Chapter

Built to work across modern frontend, backend, mobile, cloud, and media stacks.

• Frameworks & UI: React, Next.js, Vue, Nuxt, Svelte, Angular, Astro, Tailwind CSS, shadcn/ui, GSAP, Three.js
• Languages & Runtimes: TypeScript, Node.js, Go, Bun, Dart
• Backend & APIs: Express, Hono, NestJS, Spring Boot
• Mobile & Desktop: Expo, React Native, Flutter, SwiftUI, Android, Kotlin Multiplatform, Tauri, Electron
• Data & Storage: Supabase, Neon, Prisma, Drizzle ORM, Zod, React Hook Form
• Auth & Billing: Better Auth, Clerk, Stripe
• Testing: Vitest, Playwright
• Cloud & Infrastructure: Vercel, Vercel AI SDK, Cloudflare, Durable Objects, Cloudflare Agents, Cloudflare AI, AWS, Azure, Terraform
• Tooling: Turborepo, Vite, oxlint
• Media & AI: Remotion, ElevenLabs

Requirements Copy Chapter

Node.js >= 22.6

License Copy Chapter

CC BY-NC 4.0 — midudev

Overview (`packages/autoskills/README.md`) Copy Section

autoskills

Auto-detect and install the best AI agent skills for your project. One command, zero config.

npx autoskills

autoskills scans your project, detects the technologies you use, and installs curated AI agent skills that make Cursor, Claude Code, and other AI coding assistants actually understand your stack.

Quick Start Copy Chapter

Run it in your project root:

npx autoskills

That's it. It will:

1. Scan your package.json, config files, and project structure
2. Detect every technology in your stack
3. Show an interactive selector with the best skills for your project
4. Install them in parallel with live progress
5. Generate CLAUDE.md automatically when Claude Code is one of the target agents

Skip the prompt Copy Section

npx autoskills -y

Preview without installing Copy Section

npx autoskills --dry-run

Browse installed skills Copy Section

npx autoskills ui

Opens a local desk (bound to 127.0.0.1) to browse the skills installed in the current project.

Claude Code summary Copy Section

If claude-code is auto-detected or passed with -a, autoskills writes a CLAUDE.md file in your project root summarizing the markdown files installed under .claude/skills.

Options Copy Chapter

autoskills ui also accepts --port <number> and --no-open.

Supported Technologies Copy Chapter

autoskills detects 50+ technologies from your package.json, lockfiles, Gradle files, and config files:

Frameworks & Libraries Copy Section

Styling & UI Copy Section

Runtimes & Tooling Copy Section

Backend & Data Copy Section

Authentication Copy Section

Cloud & Deploy Copy Section

AI Copy Section

Other Copy Section

Web Frontend Detection Copy Section

Even without a framework, autoskills scans your file tree for web frontend signals (.html, .css, .scss, .vue, .svelte, .jsx, .tsx, .twig, .blade.php, etc.) and installs skills for frontend design, accessibility, and SEO.

Combo Detection Copy Chapter

When multiple technologies are used together, autoskills detects technology combos and adds specialized skills for the combination:

• Next.js + Supabase — Supabase Postgres best practices for Next.js
• Next.js + Vercel AI SDK — AI SDK patterns with Next.js
• Next.js + Playwright — E2E testing best practices for Next.js
• React + shadcn/ui — shadcn component patterns with React
• Tailwind CSS + shadcn/ui — Tailwind v4 + shadcn integration
• React Native + Expo — Native UI patterns
• React Hook Form + Zod — Form validation patterns with Zod schemas
• GSAP + React — GSAP animation patterns in React
• Cloudflare + Vite — Vinext migration guide
• Node.js + Express — Express server patterns

How It Works Copy Chapter

Skills are markdown files that teach AI assistants how to work with specific technologies, following best practices and patterns from the official maintainers. autoskills installs them from its own curated registry: maintainers sync them from their upstream repositories (the ones listed on skills.sh), an AI security review blocks anything that attacks the user or plants a serious vulnerability, and every file is recorded with a SHA-256 hash that the CLI verifies before writing it.

The detection runs entirely locally with zero network requests until installation begins.

Requirements Copy Chapter

• Node.js >= 22.6.0

License Copy Chapter

CC-BY-NC-4.0 — Created by @midudev

Overview (`packages/autoskills/skills-registry/composition-patterns/README.md`) Copy Section

React Composition Patterns

A structured repository for React composition patterns that scale. These
patterns help avoid boolean prop proliferation by using compound components,
lifting state, and composing internals.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)

Rules Copy Chapter

Component Architecture (CRITICAL) Copy Section

• architecture-avoid-boolean-props.md - Don't add boolean props to customize
  behavior
• architecture-compound-components.md - Structure as compound components with
  shared context

State Management (HIGH) Copy Section

• state-lift-state.md - Lift state into provider components
• state-context-interface.md - Define clear context interfaces
  (state/actions/meta)
• state-decouple-implementation.md - Decouple state management from UI

Implementation Patterns (MEDIUM) Copy Section

• patterns-children-over-render-props.md - Prefer children over renderX props
• patterns-explicit-variants.md - Create explicit component variants

Core Principles Copy Chapter

1. Composition over configuration — Instead of adding props, let consumers
   compose
2. Lift your state — State in providers, not trapped in components
3. Compose your internals — Subcomponents access context, not props
4. Explicit variants — Create ThreadComposer, EditComposer, not Composer
   with isThread

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • architecture- for Component Architecture
   • state- for State Management
   • patterns- for Implementation Patterns
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations

Impact Levels Copy Chapter

• CRITICAL - Foundational patterns, prevents unmaintainable code
• HIGH - Significant maintainability improvements
• MEDIUM - Good practices for cleaner code

Overview (`packages/autoskills/skills-registry/react-best-practices/README.md`) Copy Section

React Best Practices

A structured repository for creating and maintaining React Best Practices optimized for agents and LLMs.

Structure Copy Chapter

• rules/ - Individual rule files (one per rule)
  • _sections.md - Section metadata (titles, impacts, descriptions)
  • _template.md - Template for creating new rules
  • area-description.md - Individual rule files
• src/ - Build scripts and utilities
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)
• test-cases.json - Test cases for LLM evaluation (generated)

Getting Started Copy Chapter

1. Install dependencies:

   bash Copy

   pnpm install

2. Build AGENTS.md from rules:

   bash Copy

   pnpm build

3. Validate rule files:

   bash Copy

   pnpm validate

4. Extract test cases:

   bash Copy

   pnpm extract-tests

Creating a New Rule Copy Chapter

1. Copy rules/_template.md to rules/area-description.md
2. Choose the appropriate area prefix:
   • async- for Eliminating Waterfalls (Section 1)
   • bundle- for Bundle Size Optimization (Section 2)
   • server- for Server-Side Performance (Section 3)
   • client- for Client-Side Data Fetching (Section 4)
   • rerender- for Re-render Optimization (Section 5)
   • rendering- for Rendering Performance (Section 6)
   • js- for JavaScript Performance (Section 7)
   • advanced- for Advanced Patterns (Section 8)
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations
5. Run pnpm build to regenerate AGENTS.md and test-cases.json

Rule File Structure Copy Chapter

Each rule file should follow this structure:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description
tags: tag1, tag2, tag3
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```typescript
// Bad code example

Correct (description of what's right):

// Good code example

Optional explanatory text after examples.

Reference: Link

File Naming Convention Copy Chapter

• Files starting with _ are special (excluded from build)
• Rule files: area-description.md (e.g., async-parallel.md)
• Section is automatically inferred from filename prefix
• Rules are sorted alphabetically by title within each section
• IDs (e.g., 1.1, 1.2) are auto-generated during build

Impact Levels Copy Chapter

• CRITICAL - Highest priority, major performance gains
• HIGH - Significant performance improvements
• MEDIUM-HIGH - Moderate-high gains
• MEDIUM - Moderate performance improvements
• LOW-MEDIUM - Low-medium gains
• LOW - Incremental improvements

Scripts Copy Chapter

• pnpm build - Compile rules into AGENTS.md
• pnpm validate - Validate all rule files
• pnpm extract-tests - Extract test cases for LLM evaluation
• pnpm dev - Build and validate

Contributing Copy Chapter

When adding or modifying rules:

1. Use the correct filename prefix for your section
2. Follow the _template.md structure
3. Include clear bad/good examples with explanations
4. Add appropriate tags
5. Run pnpm build to regenerate AGENTS.md and test-cases.json
6. Rules are automatically sorted by title - no need to manage numbers!

Acknowledgments Copy Chapter

Originally created by @shuding at Vercel.

Overview (`packages/autoskills/skills-registry/react-hook-form/README.md`) Copy Section

React Hook Form Best Practices Skill

Corrective guidance for React Hook Form — the decisions that go wrong by default.

Overview Copy Chapter

This skill provides 35 rules across 7 categories. Every rule names a decision that a capable model gets wrong by default; rules that merely restated correct library behaviour were removed in 2.0.0. Verified against react-hook-form 7.82.0 (July 2026), with every code block type-checked under tsc --strict against the real package types.

Directory Structure Copy Section

react-hook-form/
├── SKILL.md                    # Entry point with quick reference
├── AGENTS.md                   # Compiled comprehensive guide (TOC over references/)
├── metadata.json               # Version, org, references
├── README.md                   # This file
├── assets/
│   └── templates/
│       └── _template.md        # Rule template
└── references/
    ├── _sections.md            # Category definitions and impact ordering
    ├── formcfg-*.md            # Form configuration rules (9)
    ├── sub-*.md                # Field subscription rules (7)
    ├── ctrl-*.md               # Controlled component rules (2)
    ├── valid-*.md              # Validation pattern rules (4)
    ├── formstate-*.md          # State management rules (6)
    ├── array-*.md              # Field array rules (4)
    └── integ-*.md              # Integration pattern rules (3)

Validating Copy Chapter

This skill is validated by the repo-level tooling, not by per-skill scripts:

npm run validate                                     # structural validation of every skill
node /path/to/dev-skill/scripts/validate-skill.js .  # discipline-aware validation of this skill

Creating a New Rule Copy Chapter

1. Choose the appropriate category prefix:

2. Create a new file: references/{prefix}-{slug}.md

3. Use the rule template from assets/templates/_template.md

4. Add the rule to the SKILL.md quick reference and to the AGENTS.md table of contents (entries are ordered alphabetically by title within each section).

Rule File Structure Copy Chapter

---
title: Rule Title Here
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: What the rule prevents or enables
tags: prefix, keyword1, keyword2
---

## Rule Title Here

Brief explanation of WHY this matters (1-3 sentences).

**Incorrect (description of problem):**

\`\`\`typescript
// Bad code with comment on key line
\`\`\`

**Correct (description of solution):**

\`\`\`typescript
// Good code with minimal diff from incorrect
\`\`\`

Reference: [Documentation Link](https://example.com)

File Naming Convention Copy Chapter

Rules follow the pattern: {prefix}-{slug}.md

• prefix: Category identifier from _sections.md (lowercase letters only)
• slug: Kebab-case description of the rule

Examples:

• formcfg-validation-mode.md
• sub-usewatch-over-watch.md
• ctrl-usecontroller-isolation.md

Impact Levels Copy Chapter

Companion Skill Copy Chapter

react-hook-form-audit is a static-analysis skill that detects violations of these rules in a Next.js App Router codebase and links each finding back to the corresponding file in references/.

Contributing Copy Chapter

1. Read existing rules in the same category for style consistency
2. Ensure incorrect/correct examples have minimal diff
3. Typecheck every example against the pinned react-hook-form version before committing
4. Include authoritative reference links
5. Run validation before submitting

Acknowledgments Copy Chapter

Based on official React Hook Form documentation, the library's shipped type definitions, and community best practices.

Overview (`packages/autoskills/skills-registry/tauri-v2/README.md`) Copy Section

Tauri v2+ Development Skill

Build cross-platform desktop and mobile apps with web frontends and Rust backends.

What This Skill Does Copy Chapter

Provides expert assistance for Tauri v2 application development, covering the full development lifecycle from project setup to cross-platform deployment. Specializes in Rust backend commands, IPC patterns, security configuration, and frontend-backend communication.

Core Capabilities Copy Section

• Implement Rust commands with #[tauri::command] and proper error handling
• Configure IPC patterns (invoke, events, channels) for frontend-backend communication
• Set up security capabilities and permissions for plugins and APIs
• Access exhaustive reference docs for plugins (fs, dialog, shell, store, etc.), updater/distribution signing, and advanced runtime (tray, sidecars, deep links)
• Build and deploy for desktop (macOS, Windows, Linux) and mobile (iOS, Android)
• Integrate Vite + TanStack Router frontends with Tauri backends
• Configure tauri.conf.json and Cargo.toml for cross-platform builds

Auto-Trigger Keywords Copy Chapter

Primary Keywords Copy Section

Exact terms that strongly trigger this skill:

• tauri
• tauri v2
• tauri.conf.json
• src-tauri
• #[tauri::command]
• tauri::invoke
• capabilities.json

Secondary Keywords Copy Section

Related terms that may trigger in combination:

• rust backend
• desktop app
• cross-platform app
• webview
• invoke command
• emit event
• app permissions
• bundle desktop

Error-Based Keywords Copy Section

Common error messages that should trigger this skill:

• "Command not found"
• "Permission denied" (in Tauri context)
• "Failed to invoke command"
• "Missing capability"
• "Cannot read property of undefined" (invoke result)
• "tauri build failed"
• "Missing Rust target"

Known Issues Prevention Copy Chapter

When to Use Copy Chapter

Use This Skill For Copy Section

• Creating new Tauri v2 projects or commands
• Configuring permissions and capabilities
• Setting up IPC (invoke, events, channels)
• Debugging command invocation issues
• Cross-platform build configuration
• Plugin integration and configuration
• Mobile (iOS/Android) deployment setup

Don't Use This Skill For Copy Section

• Tauri v1 development (use migration guide then this skill)
• Pure frontend development without Tauri integration
• Native mobile development (Swift/Kotlin directly)
• Backend API development without Tauri

Version Policy Copy Chapter

[!NOTE]
This skill targets Tauri v2+. Feature availability may vary across minor versions. When exact version timing matters, check the official Tauri changelog and release notes for tauri, @tauri-apps/api, @tauri-apps/cli, and relevant plugins.

Quick Usage Copy Chapter

# Create new Tauri project
npm create tauri-app@latest

# Add Tauri to existing project
npm install -D @tauri-apps/cli@latest
npx tauri init

# Development
npm run tauri dev

# Production build
npm run tauri build

# Add a plugin (e.g., fs, dialog, store)
cargo tauri add fs          # Adds tauri-plugin-fs to Cargo.toml + JS package
cargo tauri add dialog
cargo tauri add store

# Mobile development
cargo tauri android init    # One-time setup
cargo tauri android dev     # Run on Android
cargo tauri android build   # Release build

cargo tauri ios init        # One-time setup (macOS only)
cargo tauri ios dev         # Run on iOS simulator
cargo tauri ios build       # Release build

Token Efficiency Copy Chapter

Reference Documentation Copy Chapter

For deep-dive guidance on specific topics, see the following reference files:

See the References Index for a complete navigation guide.

File Structure Copy Chapter

tauri-v2/
├── SKILL.md        # Quick-start patterns, core rules, critical guidance
├── README.md       # This file - discovery and quick reference
└── references/     # Deep-dive reference documentation
    ├── README.md                          # Index and navigation
    ├── capabilities-reference.md          # Security model, permissions, scopes
    ├── ipc-patterns.md                    # Commands, events, channels decision framework
    ├── plugin-reference.md                # Exhaustive plugin install/register/permissions
    ├── updater-distribution-reference.md  # Signing, HTTPS, platform distribution
    └── advanced-runtime-reference.md      # Tray, sidecars, deep links, protocols

Dependencies Copy Chapter

*Last verified: 2026-04-02. Always check official changelog for feature timing.

Official Documentation Copy Chapter

• Tauri v2+ Documentation
• Commands Reference
• IPC Concepts
• Capabilities & Permissions
• Configuration Reference
• Plugin Directory

Related Skills Copy Chapter

• tanstack-start-expert - TanStack Router patterns for type-safe frontend routing
• react-component-architect - React component patterns for Tauri frontends
• go-google-style-expert - Alternative backend patterns (if using Go instead)

Companion Agent (Deprecated) Copy Chapter

The tauri-v2-expert agent at .claude/agents/specialized/tauri/tauri-v2-expert.md is deprecated/legacy. This skill is the preferred and actively maintained interface. Use this skill over the agent for all new Tauri v2 work.

License: MIT

Overview (`packages/autoskills/skills-registry/zod/README.md`) Copy Section

Zod Best Practices Skill

A comprehensive guide for using Zod effectively in TypeScript applications. This skill provides 42 rules across 8 categories, organized by impact to help AI agents and developers write better validation code.

Overview Copy Chapter

Zod is a TypeScript-first schema declaration and validation library. This skill covers best practices for:

• Schema Definition: Choosing correct types, avoiding z.any(), proper string validations
• Parsing & Validation: Using safeParse(), async validation, error handling
• Type Inference: Leveraging z.infer, distinguishing input/output types
• Error Handling: Custom messages, internationalization, form error display
• Object Schemas: strict/strip modes, partial updates, discriminated unions
• Schema Composition: Reusable schemas, intersections, recursive types
• Refinements & Transforms: Custom validation, data transformation
• Performance: Caching, Zod Mini, lazy loading, batch validation

Usage Copy Chapter

For Claude Code / AI Agents Copy Section

The skill is automatically loaded when working with Zod code. Reference specific rules:

See rules/parse-use-safeparse.md for safeParse best practices

For Developers Copy Section

Read SKILL.md for a quick reference, or AGENTS.md for the full compiled guide.

File Structure Copy Chapter

zod/
├── SKILL.md          # Quick reference with rule index
├── AGENTS.md         # Full compiled guide (all rules)
├── metadata.json     # Version, categories, references
├── README.md         # This file
└── rules/
    ├── _sections.md  # Category definitions
    ├── _template.md  # Rule template
    ├── schema-*.md   # Schema definition rules
    ├── parse-*.md    # Parsing rules
    ├── type-*.md     # Type inference rules
    ├── error-*.md    # Error handling rules
    ├── object-*.md   # Object schema rules
    ├── compose-*.md  # Composition rules
    ├── refine-*.md   # Refinement rules
    └── perf-*.md     # Performance rules

Rule Categories Copy Chapter

Key Principles Copy Chapter

1. Type Safety First: Always use z.infer, never duplicate types manually
2. Validate at Boundaries: Parse external data immediately at entry points
3. User-Friendly Errors: Provide custom messages, collect all issues
4. Single Source of Truth: Schema defines validation AND TypeScript types
5. Composition Over Duplication: Use extend, pick, omit, partial

References Copy Chapter

• Zod Official Documentation
• Zod v4 Release Notes
• Zod GitHub
• Zod Mini

Overview (`packages/autoskills/skills-registry/django-expert/references/README.md`) Copy Section

Django Expert - Reference Documentation

This directory contains comprehensive Django best practices documentation that
will be loaded into the active AI coding agent's context when needed.

Purpose Copy Chapter

Reference files provide detailed guidelines, patterns, and examples that would
make SKILL.md too long (>5k words). The agent will read these files as needed
based on the specific Django task at hand.

Recommended Reference Files Copy Chapter

Create the following markdown files in this directory to provide comprehensive Django guidance:

1. `models-and-orm.md` - Model Design & ORM Best Practices Copy Section

Topics to cover:

• Model field types and when to use each
• Database relationships (ForeignKey, ManyToMany, OneToOne)
• Model Meta options (ordering, indexes, constraints)
• Custom model methods and properties
• Model managers and custom querysets
• Database query optimization (select_related, prefetch_related, only, defer)
• Common ORM patterns and anti-patterns
• Migration best practices
• Database indexing strategies

Example structure:

# Django Models and ORM Best Practices

## Model Design Patterns

### Field Choices
- Use TextChoices or IntegerChoices for Django 3.0+
- Keep choices close to the model definition
[detailed examples...]

## Query Optimization

### N+1 Query Problem
[explanation and solutions...]

### Using select_related vs prefetch_related
[detailed guidance with examples...]

2. `views-and-urls.md` - Views, URLs, and Request Handling Copy Section

Topics to cover:

• Function-based views vs class-based views
• When to use generic CBVs (ListView, DetailView, CreateView, etc.)
• Custom mixins and view composition
• URL patterns and routing best practices
• Request/response handling
• Middleware usage
• Context processors
• Form handling in views
• Error handling and custom error pages

3. `drf-guidelines.md` - Django REST Framework Best Practices Copy Section

Topics to cover:

• Serializer patterns (ModelSerializer, nested serializers, write-only fields)
• ViewSets vs APIView vs function-based views
• Permissions and authentication
• Filtering, searching, and pagination
• Versioning strategies
• Custom actions and decorators
• Response formatting
• Error handling in APIs
• Testing DRF endpoints

4. `testing-strategies.md` - Testing Django Applications Copy Section

Topics to cover:

• Test organization and structure
• TestCase vs TransactionTestCase
• Factory patterns and fixtures
• Mocking external services
• Testing models, views, and APIs
• Testing permissions and authentication
• Database testing best practices
• Coverage and test performance
• Integration vs unit testing

5. `security-checklist.md` - Django Security Best Practices Copy Section

Topics to cover:

• CSRF protection
• XSS prevention
• SQL injection prevention
• Authentication and authorization
• Password handling and storage
• Secure settings for production
• HTTPS and SSL/TLS configuration
• Content Security Policy
• Rate limiting and throttling
• Security headers
• Common vulnerabilities and mitigations

6. `performance-optimization.md` - Performance and Scaling Copy Section

Topics to cover:

• Database query optimization
• Caching strategies (per-view cache, template fragment cache, low-level cache)
• Redis/Memcached integration
• Database connection pooling
• Async views and background tasks (Celery)
• Static file optimization
• Database indexing and query profiling
• Monitoring and profiling tools
• Pagination strategies for large datasets

How to Populate These Files Copy Chapter

1. Research: Gather Django best practices from official docs, style guides, and community resources
2. Structure: Use clear headings, code examples, and explanations
3. Examples: Include both good and bad examples with explanations
4. Keep Updated: Maintain version-specific guidance (note Django version compatibility)
5. Be Specific: Provide concrete examples rather than general statements

Example Reference File Copy Chapter

Here's an example of what a well-structured reference file looks like:

# Django REST Framework Guidelines

## Serializer Best Practices

### 1. Use ModelSerializer for Standard CRUD

For basic model serialization, always start with ModelSerializer:

```python
# Good
from rest_framework import serializers

class ProductSerializer(serializers.ModelSerializer):
    class Meta:
        model = Product
        fields = ['id', 'name', 'price', 'category']
        read_only_fields = ['id', 'created_at']

2. Nested Serializers for Relationships Copy Section

For related objects, use nested serializers or use depth:

# Option 1: Nested serializer (more control)
class OrderSerializer(serializers.ModelSerializer):
    items = OrderItemSerializer(many=True, read_only=True)

    class Meta:
        model = Order
        fields = ['id', 'items', 'total']

# Option 2: Auto-nesting with depth (simpler but less control)
class OrderSerializer(serializers.ModelSerializer):
    class Meta:
        model = Order
        fields = '__all__'
        depth = 1  # Be careful with performance

[Continue with more patterns...]

## Usage

Compatible agents automatically read these files when working on Django tasks.
You don't need to manually reference them—the active agent will determine which
references are needed based on the task.

## Notes

- Keep files focused on specific topics (don't create one giant file)
- Use code examples liberally
- Include both do's and don'ts
- Reference Django and DRF version numbers when relevant
- Link to official documentation for deep dives

---

### Overview (`packages/autoskills/skills-registry/tauri-v2/references/README.md`)

# Tauri v2 References

Deep-dive reference documentation for Tauri v2 development. Use these when the main [`SKILL.md`](../SKILL.md) quick-start isn't enough.

## Reference Files

| File | Description | Key Topics |
|------|-------------|------------|
| [`capabilities-reference.md`](capabilities-reference.md) | **Security & Permissions** | Capability files, permissions, scopes, v1 vs v2 model |
| [`ipc-patterns.md`](ipc-patterns.md) | **IPC Decision Framework** | Commands vs Events vs Channels, typed `Channel<T>` |
| [`plugin-reference.md`](plugin-reference.md) | **Official Plugins** | Registration, JS package, and required capability permissions |
| [`updater-distribution-reference.md`](updater-distribution-reference.md) | **Updater & Distribution** | Signing, HTTPS endpoints, macOS/Windows/Linux packaging |
| [`advanced-runtime-reference.md`](advanced-runtime-reference.md) | **Advanced Runtime** | `TrayIconBuilder`, sidecars, deep links, custom protocols |

## Navigation Guide

- **New to Tauri v2 security?** → Start with [`capabilities-reference.md`](capabilities-reference.md) to understand the mandatory capability model.
- **Choosing an IPC method?** → See [`ipc-patterns.md`](ipc-patterns.md) for the "Commands vs Events vs Channels" decision matrix.
- **Adding a plugin?** → Check [`plugin-reference.md`](plugin-reference.md) for the specific permission strings you MUST add to your capabilities.
- **Shipping to production?** → See [`updater-distribution-reference.md`](updater-distribution-reference.md) for mandatory signing and update server requirements.
- **Tray icons, sidecars, or deep links?** → See [`advanced-runtime-reference.md`](advanced-runtime-reference.md) for v2-specific implementations.

*Last verified: 2026-04-02. Check [official Tauri changelog](https://github.com/tauri-apps/tauri/blob/dev/crates/tauri/CHANGELOG.md) for updates.*

---

### Overview (`packages/autoskills/skills-registry/azure-deploy/references/recipes/README.md`)

# Recipes

Deployment recipes for different infrastructure approaches.

| Recipe | When to Use |
|--------|-------------|
| [AZD](azd/README.md) | Projects using Azure Developer CLI |
| [AZCLI](azcli/README.md) | Projects using Azure CLI scripts |
| [Bicep](bicep/README.md) | Projects using Bicep templates |
| [Terraform](terraform/README.md) | Projects using Terraform |
| [CI/CD](cicd/README.md) | Pipeline-based deployments |

---

### Overview (`packages/autoskills/skills-registry/azure-diagnostics/references/app-service/README.md`)

# App Service Troubleshooting

> **Request to "collect"/"gather" diagnostics?** Once the app name and resource
> group are known from the request or existing context, run the
> [`appservice-diagnostics`](../../scripts/appservice-diagnostics.sh) script
> ([PowerShell](../../scripts/appservice-diagnostics.ps1)) directly as your first action —
> don't verify the app/resource group exists with separate calls first, and don't substitute
> the individual commands below for it. It's read-only and reports clearly if the
> resource can't be found. Ask only for identifiers that remain missing. See "Combined
> Diagnostic Script" below for usage.

## Common Issues Matrix

| Symptom | Likely Cause | Action |
|---------|--------------|-----------|
| High CPU / memory | Runaway process, inefficient code | Use Process Explorer via Kudu, scale up |
| Deployment failure | Build error, locked files, quota | Check Kudu logs at `https://APP.scm.azurewebsites.net/api/deployments` to look for details on build errors, locked files or lack of storage quota |
| App crash / restart | Unhandled exception, OOM kill | Review Event Log and STDERR in Diagnose & Solve |
| Slow responses | Downstream dependency, no caching | Enable request tracing, check dependency calls |
| 502 / 503 errors | App not starting, port conflict | Check STDERR logs, verify startup command |
| TLS / domain errors | Certificate expired, DNS mismatch | `az webapp config ssl list`, verify CNAME |
| Health check failure | Endpoint not returning 200 | Verify health check path responds within 2 min |

---

## High CPU / Memory Diagnosis

**Diagnose:**
```bash
# Check app metrics
az monitor metrics list --resource APP_RESOURCE_ID \
  --metric "CpuPercentage,MemoryPercentage" --interval PT1M --output table

# View running processes via ARM Processes API (Entra ID auth)
az rest --method get \
  --uri "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/processes?api-version=2024-04-01"

Fix: Scale up (az appservice plan update -n <app-service-plan-name> -g <resource-group> --sku P1V3) or profile the app via Kudu Process Explorer at https://APP.scm.azurewebsites.net/ProcessExplorer/ to identify hot paths.

Deployment Failure Analysis Copy Chapter

Diagnose:

# List deployment history
az webapp deployment list -n APP -g RG --output table

# View deployment log for a specific deployment
az webapp log deployment show -n APP -g RG --deployment-id DEPLOY_ID

# Stream build logs from Kudu
az webapp log tail -n APP -g RG

KQL — Failed deployments:

// Replace <app-service-resource-id> with the full resource ID, for example:
// /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>
AppServicePlatformLogs
| where TimeGenerated > ago(24h)
| where Level == "Error" and _ResourceId == "<app-service-resource-id>"
| project TimeGenerated, Level, Message
| order by TimeGenerated desc

Common deployment failures:

Application Crash / Restart Diagnosis Copy Chapter

Diagnose:

# Check recent restarts via activity log
az monitor activity-log list -g RG --resource-id APP_RESOURCE_ID \
  --max-events 10 --query "[?operationName.value=='Microsoft.Web/sites/restart/action']"

# View STDERR/STDOUT (Linux)
az webapp log download -n APP -g RG --log-file logs.zip

KQL — App crashes and errors:

AppServiceConsoleLogs
| where TimeGenerated > ago(1h)
| where ResultDescription contains "error" or ResultDescription contains "fatal"
| project TimeGenerated, ResultDescription
| order by TimeGenerated desc
| take 50

Health check failures:

# Show health check config
az webapp show -n APP -g RG --query "siteConfig.healthCheckPath"

# Test the endpoint directly
curl -s -o /dev/null -w "%{http_code}" https://APP.azurewebsites.net/health

⚠️ Warning: If the health check fails on >50% of instances for 1 hour, the instance is replaced.

Slow Response Time Investigation Copy Chapter

Diagnose:

# Check average response time
az monitor metrics list --resource APP_RESOURCE_ID \
  --metric "HttpResponseTime" --interval PT5M --aggregation Average --output table

# Enable failed request tracing
az webapp log config -n APP -g RG --failed-request-tracing true

KQL — Slow requests with dependency analysis:

AppServiceHTTPLogs
| where TimeGenerated > ago(1h)
| where TimeTaken > 5000
| project TimeGenerated, CsUriStem, ScStatus, TimeTaken, CsHost
| order by TimeTaken desc
| take 20

Auto-Heal — Automatic mitigation:

# Configure auto-heal to recycle on slow requests
az webapp config set -n APP -g RG \
  --auto-heal-enabled true \
  --generic-configurations '{"autoHealRules":{"triggers":{"slowRequests":{"timeTaken":"00:00:30","count":10,"timeInterval":"00:02:00"}},"actions":{"actionType":"Recycle"}}}'

Custom Domain / TLS Certificate Issues Copy Chapter

Diagnose:

# List custom domains
az webapp config hostname list -g RG --webapp-name APP --output table

# List TLS certificates
az webapp config ssl list -g RG --output table

# Check SSL binding
az webapp config ssl show --certificate-name CERT -g RG

AZ CLI or MCP Tools for App Service Diagnostics Copy Chapter

💡 Tip: Start with mcp_azure_mcp_appservice (diagnose) — it automatically runs relevant detectors and surfaces the most likely root cause before you dig into logs manually.

Combined Diagnostic Script Copy Chapter

Use the appservice-diagnostics script
(PowerShell) to collect everything in one call.
It prints clearly labeled sections — app config, recent deployments, app settings, and
custom domains — and a summary line describing what it collected. Interpreting the output
remains your job.

..\..\scripts\appservice-diagnostics.ps1 -Name <app> -ResourceGroup <rg>

../../scripts/appservice-diagnostics.sh --name <app> --resource-group <rg>

Overview (`packages/autoskills/skills-registry/azure-diagnostics/references/container-apps/README.md`) Copy Section

Container Apps Troubleshooting

Request to "collect"/"gather" diagnostics? Once the app name and resource
group are known from the request or existing context, run the
containerapp-diagnostics script
(PowerShell) directly as your first action —
don't verify the app/resource group exists with separate calls first, and don't substitute
the individual commands below for it. It's read-only and reports clearly if the
resource can't be found. Ask only for identifiers that remain missing. See "Get All
Diagnostic Info" below for usage.

Common Issues Matrix Copy Section

Image Pull Failures Copy Section

Diagnose:

# Check registry configuration
az containerapp show --name APP -g RG --query "properties.configuration.registries"

# Check revision status
az containerapp revision list --name APP -g RG --output table

Fix:

az containerapp registry set \
  --name APP -g RG \
  --server ACR.azurecr.io \
  --identity system

ACR Tasks Disabled (Free Subscriptions) Copy Section

Symptom: az acr build fails with "ACR Tasks is not supported"

Fix: Build locally instead:

docker build -t ACR.azurecr.io/myapp:v1 .
az acr login --name ACR
docker push ACR.azurecr.io/myapp:v1

Cold Start Issues Copy Section

Symptom: First request very slow or times out

Fix:

az containerapp update --name APP -g RG --min-replicas 1

Health Probe Failures Copy Section

Symptom: Container keeps restarting

Check:

# View health probe config
az containerapp show --name APP -g RG --query "properties.configuration.ingress"

# Check if /health endpoint responds
curl https://APP.REGION.azurecontainerapps.io/health

Fix: Ensure app has health endpoint returning 200:

app.get('/health', (req, res) => res.sendStatus(200));

Port Mismatch Copy Section

Symptom: App starts but returns 502/503

Check:

az containerapp show --name APP -g RG --query "properties.configuration.ingress.targetPort"

Verify: App must listen on this exact port. Check:

• Dockerfile EXPOSE statement
• process.env.PORT or hardcoded port in app

View Logs Copy Section

# Stream logs (wait for replicas if scale-to-zero)
az containerapp logs show --name APP -g RG --follow

# Recent logs
az containerapp logs show --name APP -g RG --tail 100

# System logs (startup issues)
az containerapp logs show --name APP -g RG --type system

Get All Diagnostic Info Copy Section

Use the containerapp-diagnostics script
(PowerShell) to collect everything in one
call. It prints clearly labeled sections — revisions, registry config, ingress config, and
recent logs — and a summary line describing what it collected. Interpreting the output
remains your job.

..\..\scripts\containerapp-diagnostics.ps1 -Name <app> -ResourceGroup <rg>

../../scripts/containerapp-diagnostics.sh --name <app> --resource-group <rg>

Overview (`packages/autoskills/skills-registry/azure-diagnostics/references/functions/README.md`) Copy Section

Function Apps Troubleshooting

Find Linked App Insights / Log Analytics Copy Chapter

Preferred: Use Azure Resource Graph Copy Section

A single ARG query returns the App Insights name, instrumentation key, connection string, and Log Analytics workspace for a given function app:

az graph query -q "
resources | where type =~ 'microsoft.web/sites' and name == '<func-app-name>'
| project funcName=name, rg=resourceGroup
| join kind=inner (resources | where type =~ 'microsoft.insights/components' | project appiName=name, rg=resourceGroup, instrumentationKey=properties.InstrumentationKey, connectionString=properties.ConnectionString, workspaceId=properties.WorkspaceResourceId) on rg
| project funcName, appiName, instrumentationKey, connectionString, workspaceId
" -o json

💡 Tip: This join matches by resource group. If App Insights is in a different resource group, use the CLI fallback below.

Fallback: CLI Commands Copy Section

Step 1: Get the App Insights connection string from app settings

az functionapp config appsettings list \
  --name <func-app-name> -g <rg-name> \
  --query "[?name=='APPLICATIONINSIGHTS_CONNECTION_STRING' || name=='APPINSIGHTS_INSTRUMENTATIONKEY']"

Step 2: Find the App Insights resource by instrumentation key

az monitor app-insights component show \
  --query "[?instrumentationKey=='<key>'] | [0].{name:name, rg:resourceGroup, workspaceId:workspaceResourceId}"

Step 3: Find the Log Analytics workspace

az monitor app-insights component show --app <appinsights-name> -g <rg-name> \
  --query "workspaceResourceId" -o tsv

Confirm logs are flowing Copy Section

Query App Insights traces table to verify the function app is sending telemetry:

az monitor app-insights query --apps <appinsights-name> -g <rg-name> \
  --analytics-query "traces | where operation_Name != '' | take 1 | project timestamp, operation_Name, message"

For FunctionAppLogs (available in Log Analytics only, not App Insights), query the workspace directly:

az monitor log-analytics query -w <workspace-guid> \
  --analytics-query "FunctionAppLogs | where _ResourceId contains '<func-app-name>' | take 5 | project TimeGenerated, FunctionName, Message, Level"

⚠️ Classic App Insights: Some function apps use classic App Insights without a linked Log Analytics workspace (workspaceId is null). In this case, FunctionAppLogs is not available — use the traces, requests, and exceptions tables via az monitor app-insights query instead. As a last resort, az webapp log tail --name <func-app-name> -g <rg-name> can stream live logs directly.

If results are returned, logs are flowing. If empty, verify the APPLICATIONINSIGHTS_CONNECTION_STRING app setting matches this App Insights instance.

⚠️ Always prefer querying App Insights or Log Analytics for function app logs. az webapp log tail can stream live logs directly but App Insights provides richer data, historical queries, and correlation across requests.

💡 Tip: App Insights logs can be delayed by a few minutes. If you don't see recent data, wait 3-5 minutes and query again.

Check Recent Deployments Copy Chapter

Correlate issues with recent deployments by listing deployment history:

az rest --method get \
  --uri "/subscriptions/<subscription-id>/resourceGroups/<rg-name>/providers/Microsoft.Web/sites/<func-app-name>/deployments?api-version=2023-12-01"

Compare deployment timestamps against when errors started appearing in App Insights to identify if a deployment caused the issue.

Trigger & Durable Function Troubleshooting Copy Chapter

• Trigger & Binding Troubleshooting - HTTP, Timer, Queue, Blob, Service Bus, and Cosmos DB trigger diagnostics, plus Flex Consumption specifics and SDK conflicts.
• Durable Functions Troubleshooting - stuck orchestrations, non-determinism violations, timeout/cancellation patterns, and task hub conflicts.

Overview (`packages/autoskills/skills-registry/azure-diagnostics/troubleshooting/messaging/README.md`) Copy Section

Azure Messaging Troubleshooting

Diagnose and resolve issues with Azure Event Hubs and Service Bus SDKs.

Routing Copy Chapter

SDK Troubleshooting by Language Copy Chapter

• Event Hubs: Python | Java | JS | .NET
• Service Bus: Python | Java | JS | .NET

Common Issues Copy Chapter

MCP Tools Copy Chapter

Overview (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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": ""}]
}

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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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 (`packages/autoskills/skills-registry/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/<bucket>)
• 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