Skip to main content
affpapa.org
RU EN
skill Claude Code CX Codex Cursor GitHub Copilot

gateway-workers — Claude Code skill: Cloudflare Workers in Gateway

Skill for building, debugging, and reviewing Cloudflare Workers triggered by Forward actions in Gateway HTTP policies. Work with GatewayMiddleware, context types, and request continuation.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add cloudflare/skills --skill gateway-workers -a claude-code
Open on GitHub

What gateway-workers does

gateway-workers provides a complete reference for writing Workers inside Cloudflare Gateway. The skill teaches you to export a GatewayMiddleware class extending WorkerEntrypoint, implement the handle(request, context, next) method, and return a Response. Gateway calls this method via RPC—a plain fetch() handler alone does not satisfy the Forward contract.

The second handle() argument is the Gateway context, which describes the original request and stays unchanged when the Worker modifies it. Distinguish it from this.ctx (Workers execution context) and this.env (bindings). Continue the user's request with next(request) at most once, or return a synthetic response without calling it. next() always targets the original destination; URL and host changes are ignored.

The skill flags key limitations: HTTPS requires decryption, WebSockets bypass the Worker, and matching VPC traffic is dropped. Only the first matching Forward policy invokes a Worker. Gateway inspects the final response, including synthetic ones. Handle HEAD requests and statuses 204, 205, 304 correctly—return no body for these.

What it helps with

  • Build a Worker that transforms or filters HTTP traffic in Gateway
  • Use Gateway context to check user identity and device posture
  • Return a synthetic response without continuing to the origin
  • Debug RPC invocation of GatewayMiddleware and validate types
  • Distinguish Gateway context from Workers context and bindings

Example prompts for the agent

  • Write a Worker for Gateway that checks device posture and blocks requests if posture does not meet policy
  • Help debug why `next()` ignores URL changes in the transformed request
  • Review a Worker for compliance with Gateway types and body handling rules for HEAD and 204 responses

How to install gateway-workers

1Skills CLI (Vercel)

npx skills add cloudflare/skills --skill gateway-workers -a claude-code

2Manually: put the files in place

~/.claude/skills/gateway-workers/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gateway-workers/

From the same set18

The whole set →
cloudflare cloudflare Helps coding agents pick the right Cloudflare products for applications, storage, and AI, while routing between cf CLI and Wrangler. Claude Code CX Codex Cursor +1 136,500installs wrangler cloudflare Runs and troubleshoots Wrangler CLI commands for Cloudflare Workers projects that use wrangler configuration files. Claude Code CX Codex Cursor +1 128,500installs workers-best-practices cloudflare Guides coding agents on production Cloudflare Workers standards, Wrangler typing, observability setup, and runtime anti-pattern checks. Claude Code CX Codex Cursor +1 124,900installs durable-objects cloudflare This skill helps build, debug, and review Cloudflare Durable Objects for state, coordination, and persistent connections. Claude Code CX Codex Cursor +1 109,700installs web-perf cloudflare Audit Core Web Vitals, diagnose rendering bottlenecks, and inspect network dependencies directly through your agent. Claude Code CX Codex Cursor +1 109,300installs agents-sdk cloudflare Helps build, debug, and review Cloudflare Agents SDK applications using the agents package and official documentation. Claude Code CX Codex Cursor +1 105,700installs cloudflare-email-service cloudflare A skill for Cloudflare Email Sending and Email Routing: it walks the agent through sending and receiving mail in Workers. Claude Code CX Codex Cursor +1 101,400installs cloudflare-one cloudflare Walks your agent through designing, configuring and troubleshooting Cloudflare One Zero Trust and SASE deployments. Useful when you need Access, Gateway or tunnel work done without digging through docs yourself. Claude Code CX Codex Cursor +1 92,200installs

Similar

legacy-modernizer https://github.com/Jeffallan Plans incremental legacy-code migration from dependency maps to facades, flags, and rollback steps. Use it when splitting a monolith or upgrading technology without a wholesale replacement. Claude Code CX Codex Cursor +1 4,300installs salesforce-developer https://github.com/Jeffallan Writes Apex classes, builds Lightning Web Components, optimizes SOQL queries, and sets up batch processing on Salesforce. Enforces governor limits and bulkifies code. Claude Code CX Codex Cursor +1 4,300installs firebase sickn33 Guides Firebase architecture, Firestore security rules, and Cloud Functions based on read-heavy query patterns and pricing limits. Claude Code CX Codex Cursor +1 1,600installs workflow Vercel Inc. Builds durable, resumable tasks with the Vercel Workflow SDK when operations must survive server restarts or pause for external events. Claude Code CX Codex Cursor +1 5,300installs mcp-developer https://github.com/Jeffallan A skill for building and debugging MCP servers and clients in TypeScript or Python, with tool schemas, transport setup and protocol checks in the inspector. Claude Code CX Codex Cursor +1 4,200installs django-expert https://github.com/Jeffallan Guides Django 5.0 and DRF development by enforcing indexed models, ORM query optimization with select_related, and JWT authentication. Claude Code CX Codex Cursor +1 4,200installs mcp-builder official anthropics This skill walks through building an MCP server in TypeScript or Python, from reading the protocol spec to writing tests and evaluation questions. Claude Code Claude.ai 130,949installs google-agents-cli-adk-code official Google A reference skill for building ADK agents with tools, callbacks, state, and workflows. Use it when an agent project needs concrete API patterns or code examples. Claude Code CX Codex Cursor +1 511,400installs

Questions about gateway-workers

How do I install gateway-workers in Claude Code?

Run npx skills add cloudflare/skills --skill gateway-workers -a claude-code and point to ~/.claude/skills/gateway-workers/SKILL.md when prompted. For other platforms use the appropriate flag: -a codex for Codex, -a cursor for Cursor, -a gemini-cli for Gemini CLI. GitHub Copilot installs via gh skill install cloudflare/skills gateway-workers.

What does gateway-workers do?

The skill teaches you to write Workers that Gateway invokes on permitted HTTP traffic through the Forward action. A Worker can transform requests, return a synthetic response, or check user identity via context.

What is the difference between `next(request)` and `fetch()` in a Worker?

next() continues the request to the original destination; URL changes are ignored and it cannot redirect or retry. fetch() sends an independent subrequest to another address and does not inherit the user's Gateway policies.

Source text

SKILL.md · Apache-2.0 
---
name: gateway-workers
description: Build, debug, or review Cloudflare Workers invoked by the Forward action in Gateway HTTP policies, including the GatewayMiddleware entrypoint, Gateway types, context, and continuation.
---

# Gateway Workers

Read the current [Forward guide](https://developers.cloudflare.com/cloudflare-one/traffic-controls/integrate-workers/forward-traffic/index.md) before implementing a Worker. It defines how Gateway invokes Workers on permitted HTTP traffic. Retrieve the relevant page below rather than copying setup, API payloads, or limits into the project from memory.

## Workflow

1. Inspect the existing Worker and choose a [Worker template](https://developers.cloudflare.com/cloudflare-one/traffic-controls/integrate-workers/worker-templates/index.md) for the required transformation, synthetic response, or background task.
2. Export a named `GatewayMiddleware` class extending `WorkerEntrypoint` from `cloudflare:workers`. Implement `handle(request, context, next)` and return a `Response`. Gateway calls this method through RPC. A default `fetch()` handler alone does not implement the Forward contract.
3. For TypeScript, follow the chosen template's current package installation and type-import instructions.
4. Use the second argument for [Gateway context](https://developers.cloudflare.com/cloudflare-one/traffic-controls/integrate-workers/available-context/index.md). It describes the original request and stays unchanged when the Worker modifies the request. Keep it distinct from `this.ctx` (Workers execution context) and `this.env` (bindings).
5. Continue the user's request with `next(request)` at most once, or return a synthetic response without calling it. `next()` always targets the original destination. Changes to the destination URL or host are ignored, and it cannot redirect, retry, or fan out. Use `fetch()` to send a request to a different destination. It creates an independent subrequest that does not inherit the user's Gateway policies or egress configuration.

## Context

Use the published types and context reference for field names and availability. Treat a falsy identity (`!identity`) as anonymous and guard optional posture values. Call `await context.identity()` or `await context.devicePosture()` only when needed. Both getters can reject. Catch lookup failures separately from missing values and decide how to handle each when the Worker depends on them. Use Gateway-provided identity rather than client-supplied identity headers.

## Gateway behavior

- Only the first matching Forward policy invokes a Worker. Worker invocation does not confirm successful body inspection. Follow the Forward guide's [inspection order](https://developers.cloudflare.com/cloudflare-one/traffic-controls/integrate-workers/forward-traffic/index.md#how-it-works).
- Gateway inspects the final response, including synthetic responses. Modified request bytes are not inspected again before reaching the origin.
- Review the Forward guide's [limitations](https://developers.cloudflare.com/cloudflare-one/traffic-controls/integrate-workers/forward-traffic/index.md#known-limitations) before choosing traffic: HTTPS requires decryption, WebSockets bypass the Worker, and matching Workers VPC traffic is dropped. Worker invocation failures fail closed.

## Validation

Type-check against the installed Gateway types and test the named RPC entrypoint, including zero or one continuation call and the context values the Worker uses. Then test a permitted request through a scoped Gateway Forward policy. A direct request to a default `fetch()` handler does not validate the Gateway path. Follow the chosen template's test procedure and the Forward guide's troubleshooting steps.

Check the [response and streaming rules](https://developers.cloudflare.com/cloudflare-one/traffic-controls/integrate-workers/forward-traffic/index.md#known-limitations): return a final status from `200` to `599`, return no body for HEAD requests or statuses `204`, `205`, and `304`, and stream bodies rather than buffering them.

## Related skills

- [cloudflare-one](../cloudflare-one/SKILL.md): Gateway policy design, traffic paths, identity, TLS, and rollout.
- [workers-best-practices](../workers-best-practices/SKILL.md): streaming, bindings, generated environment types, background work, observability, and runtime tests.
- [CLI selection](../cloudflare/SKILL.md#choose-the-cli): choose the existing `cf-cli` or `wrangler` skill for project setup and deployment.

© cloudflare · Apache-2.0 · cloudflare/skills

See also

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor