AutoGineer
Generated banner for Gateway Workers
Generated logo for Gateway Workers

Gateway Workers

CloudflareOfficialPublished by Cloudflare

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Build, debug, or review Cloudflare Workers invoked by the Forward action in Gateway HTTP policies, including the GatewayMiddleware entrypoint, Gateway types, context, and continuation.
— the description by Cloudflare

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to developing, debugging, and reviewing Cloudflare Workers designed to be invoked by the Forward action in Gateway HTTP policies. It covers the implementation of the GatewayMiddleware entrypoint, proper handling of Gateway context, and the specific requirements for request continuation or synthetic response generation within the Gateway environment.

What it does

  • Guides the implementation of the GatewayMiddleware class for RPC-based invocation.
  • Explains the distinction between Gateway context, execution context, and environment bindings.
  • Outlines the requirements for request continuation using the next() function.
  • Provides best practices for handling identity and device posture lookups.
  • Details limitations regarding HTTPS decryption, WebSockets, and VPC traffic.
  • Defines validation steps for testing Workers within the Gateway Forward policy path.

When to use it

  • When you need to transform, intercept, or generate synthetic responses for HTTP traffic managed by Gateway.
  • When implementing custom logic that requires access to Gateway-specific identity or posture data.
  • When debugging issues with existing Workers invoked by Gateway Forward policies.
  • When ensuring your Worker implementation adheres to the specific RPC contract required by Gateway.

Advantages

  • Ensures correct implementation of the GatewayMiddleware entrypoint.
  • Helps avoid common pitfalls like using fetch() for internal request continuation.
  • Provides clear guidance on handling identity and posture lookups safely.
  • Aligns development with Gateway's specific inspection and streaming limitations.

Usage examples

“How do I implement the GatewayMiddleware class for a new Forward policy?”
The agent provides a code template showing how to export the GatewayMiddleware class, implement the handle method, and correctly use the next() function for request continuation.
“Why is my Worker not being invoked by my Gateway policy?”
The agent guides you through checking the inspection order, verifying if HTTPS decryption is enabled, and confirming the policy is the first matching Forward policy.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/cloudflare/gateway-workers/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip gateway-workers.zip -d .agents/skills

Documentation by Cloudflare

Gateway Workers

Read the current Forward guide 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 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. 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.

  • 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 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: 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: Gateway policy design, traffic paths, identity, TLS, and rollout.

  • workers-best-practices: streaming, bindings, generated environment types, background work, observability, and runtime tests.

  • CLI selection: choose the existing cf-cli or wrangler skill for project setup and deployment.

Skill feedback

If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.

Files

references/skill-feedback.md

Skill feedback

GitHub issues are public: anyone can read an issue once it is posted. Never include sensitive information, and never post an issue until the user has seen the exact title and body and approved it.

Use this when the user reports that the gateway-workers skill gave incorrect or outdated guidance, is missing information, or could be improved. This is about the skill (agent instructions), not about Cloudflare products.

What not to include

The issue is drafted from the conversation, so remove the following before drafting and describe the problem in general terms instead:

  • Credentials, API tokens, secrets, and passwords

  • Account IDs, zone IDs, and other resource identifiers

  • Customer or personal data, such as names, email addresses, and IP addresses

  • Internal hostnames and URLs

  • Private code, configuration, and logs

Steps

  1. Ask permission – Ask the user if they would like to submit feedback to the skill maintainers. If they decline, move on.

  2. Draft the issue – Fill in the table below from the conversation and use it as the issue body. Always identify which specific file and section caused the problem. Leave out everything listed in What not to include.

  3. Review with the user – Show the user the exact title and body, then ask a yes/no question, such as "Post this as a public issue on cloudflare/skills?" Submit only after the user answers yes. If they ask for changes, apply them and ask again. If they answer no, do not post. Agreeing to send feedback in step 1 is not approval of the text.

  4. Submit – Create a GitHub issue on the cloudflare/skills repository with the approved draft as the body, for example with gh issue create --repo cloudflare/skills. The title must follow this format: skill-feedback: gateway-workers: <summary of the problem>.

  5. Share the result – Share the issue URL with the user after submission. If submission fails, give the user the approved title and body, and this link to create the issue manually: https://github.com/cloudflare/skills/issues/new

Issue body

FieldValue
Typebug (incorrect guidance), outdated, missing, or improvement
Skillgateway-workers
SourceFile and section, e.g. SKILL.md > "Section name" or references/<file>.md > "Section name"
AgentThe agent and model in use, if known
TaskWhat the user was trying to do, e.g. "deploy a preview"
ExpectedWhat should have happened, e.g. "Create a Preview deployment"
ActualWhat the skill said or what happened, e.g. "Unknown option: --preview"
ImpactThe effect on the user, e.g. "Time spent finding the correct syntax"
Suggested fixHow the skill should change; leave blank if unsure

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Cloudflare
Publisher
Cloudflare (Official)
Source
cloudflare/skills · skills/gateway-workers · commit 6eb6c78
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Cloudflare.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download gateway-workers.zip