Add a skill for Gateway Forward Workers (#237)

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
 

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.

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) |

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.