From be9f5e1e940fcf8567ff723cc03b8a8448c4082f Mon Sep 17 00:00:00 2001 From: aj <108435297+grstnhbr@users.noreply.github.com> Date: Thu, 15 Oct 2026 12:03:47 -0500 Subject: [PATCH] Add a skill for Gateway Forward Workers (#237) --- README.md | 5 +++-- skills/cloudflare-one/SKILL.md | 2 ++ skills/cloudflare/SKILL.md | 1 + skills/gateway-workers/SKILL.md | 38 +++++++++++++++++++++++++++++++++ 4 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 skills/gateway-workers/SKILL.md diff --git a/README.md b/README.md index 9b1d64c..4a5c4a8 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Start a new Codex session after installation. ### Claude Code -Install using the [plugin marketplace](https://code.claude.com/docs/en/discover-plugins#add-from-github): +Install using the [plugin marketplace](https://code.claude.com/docs/en/plugins/install#add-a-marketplace): ``` /plugin marketplace add cloudflare/skills @@ -58,7 +58,7 @@ Clone this repo and copy the skill folders into the appropriate directory for yo | Cursor | `~/.cursor/skills/` | [docs](https://cursor.com/docs/context/skills) | | OpenCode | `~/.config/opencode/skills/` | [docs](https://opencode.ai/docs/skills/) | | OpenAI Codex | `~/.codex/skills/` | [docs](https://developers.openai.com/codex/skills/) | -| Pi | `~/.pi/agent/skills/` | [docs](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#skills) | +| Pi | `~/.pi/agent/skills/` | [docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md) | ## Skills @@ -84,6 +84,7 @@ Skills are contextual and auto-loaded based on your conversation. When a request | web-perf | Auditing Core Web Vitals (FCP, LCP, TBT, CLS), render-blocking resources, network chains | | cloudflare-one | Designing, configuring, troubleshooting, or reviewing [Cloudflare One](https://developers.cloudflare.com/cloudflare-one/) deployments across Access, Gateway, WARP, Tunnel, Magic WAN, DLP, CASB, posture, and identity | | cloudflare-one-migrations | Migration assessments, policy mapping, rollout plans, and gap analysis for Zscaler, Palo Alto, legacy VPN/SWG, and SASE migrations to Cloudflare One | +| gateway-workers | Writing and reviewing Workers invoked by the Forward action in Gateway HTTP policies | ## MCP Servers diff --git a/skills/cloudflare-one/SKILL.md b/skills/cloudflare-one/SKILL.md index 7b5b8c9..13e052b 100644 --- a/skills/cloudflare-one/SKILL.md +++ b/skills/cloudflare-one/SKILL.md @@ -52,6 +52,8 @@ Use these to avoid jumping straight to configuration. Ask only the prompts relev - TLS inspection: root CA deployment path, certificate-pinned applications, compliance exceptions, and FIPS requirements. Retrieve [TLS decryption](https://developers.cloudflare.com/cloudflare-one/traffic-policies/http-policies/tls-decryption/index.md) docs before enabling. - DLP: sensitive data types, channels to inspect, TLS inspection readiness, DLP profiles, payload logging requirements, and false-positive tolerance. Retrieve [DLP](https://developers.cloudflare.com/cloudflare-one/data-loss-prevention/index.md) docs before creating enforcement. +For writing or reviewing Workers invoked by the HTTP Forward action, use the [gateway-workers skill](../gateway-workers/SKILL.md). + ### CASB, Device Posture, and Risk - CASB: SaaS vendors, admin access level, scan policy, org size, remediation owner, and whether inline protection is also required. Retrieve [CASB findings](https://developers.cloudflare.com/cloudflare-one/cloud-and-saas-findings/manage-findings/index.md) docs before recommending remediation. diff --git a/skills/cloudflare/SKILL.md b/skills/cloudflare/SKILL.md index f5dbfd5..4094874 100644 --- a/skills/cloudflare/SKILL.md +++ b/skills/cloudflare/SKILL.md @@ -80,6 +80,7 @@ Find the row closest to the user's task. Products can appear in multiple rows, a | Connect Workers to private services | Workers VPC | Access services in private networks from a Worker | [Workers VPC docs](https://developers.cloudflare.com/workers-vpc/index.md) | | Require employee login before accessing an internal app | Access | Put identity-based access policies in front of an internal application | `cloudflare-one` skill; [Access docs](https://developers.cloudflare.com/cloudflare-one/access-controls/index.md) | | Protect access to internal applications and networks | Cloudflare One | Apply identity and network access policies | `cloudflare-one` skill; [Cloudflare One docs](https://developers.cloudflare.com/cloudflare-one/index.md) | +| Transform permitted Gateway HTTP traffic with a Worker | Gateway Forward + Workers | Apply custom request or response logic to traffic passing through Gateway | [gateway-workers skill](../gateway-workers/SKILL.md) | | Migrate existing access and network security configurations | Cloudflare One | The task is a supported migration to Cloudflare One | `cloudflare-one-migrations` skill; [Cloudflare One docs](https://developers.cloudflare.com/cloudflare-one/index.md) | | Proxy a TCP or UDP application | Spectrum | Protect and accelerate non-HTTP application traffic | [Spectrum docs](https://developers.cloudflare.com/spectrum/index.md) | | Connect a network directly to Cloudflare | Network Interconnect | Dedicated network connectivity is required | [Network Interconnect docs](https://developers.cloudflare.com/network-interconnect/index.md) | diff --git a/skills/gateway-workers/SKILL.md b/skills/gateway-workers/SKILL.md new file mode 100644 index 0000000..07c568d --- /dev/null +++ b/skills/gateway-workers/SKILL.md @@ -0,0 +1,38 @@ +--- +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.