workers-best-practices

Review and write Cloudflare Workers code against current platform best practices.

1|Updated Jul 2, 2026
One-click install
npx skills add https://github.com/filippolmt/skills --skill workers-best-practices-filippolmt
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: workers-best-practices
Source: https://github.com/filippolmt/skills/tree/main/skills/workers-best-practices
Command: npx skills add https://github.com/filippolmt/skills --skill workers-best-practices-filippolmt

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Cloudflare Workers APIs, types, and configuration change frequently, so pre-trained knowledge is often outdated. This Skill grounds Workers code writing and review in the project's installed versions, generated types, and Wrangler compatibility settings, catching anti-patterns like buffered response bodies, hardcoded secrets, and floating promises before they reach production. ## Core Features & Use Cases - Anti-Pattern Detection: Flags 15+ concrete issues including unbounded body buffering, Math.random() for security tokens, module-level mutable state, and ctx.passThroughOnException() misuse. - Configuration Review: Verifies compatibility dates, nodejs_compat flags, generated binding types via wrangler types, and observability settings for logs and traces. - Platform API Validation: Checks handler signatures, binding access patterns (env.X vs this.env.X), and serialization boundaries across Queues, Workflows, Durable Objects, and WebSockets. - Use Case: When reviewing a pull request that adds a new Worker endpoint, the Skill checks that secrets use Wrangler secrets, background work uses ctx.waitUntil(), and large responses stream instead of buffering. ## Quick Start Review my Cloudflare Worker code in src/index.ts for best practice violations and outdated API usage.

Frequently Asked Questions about workers-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review Cloudflare Workers code for best practices?

Check the project's installed Wrangler version, generated types, and compatibility settings as the baseline, then verify API and configuration claims against current Cloudflare documentation. Flag anti-patterns like buffered unbounded bodies, hardcoded secrets, and floating promises.

What are common Cloudflare Workers anti-patterns to avoid?

Key anti-patterns include buffering large bodies with `await response.text()`, using `Math.random()` for security tokens, module-level mutable request state, destructuring `ctx` methods, and calling Cloudflare REST APIs when bindings are available.

How do I enable observability for Cloudflare Workers?

Set `observability.enabled` and `observability.traces.enabled` to `true` in wrangler.jsonc; the top-level setting alone does not enable traces. Use structured JSON logging and configure `head_sampling_rate` to control volume and cost.

Should I use wrangler.toml or wrangler.jsonc for Workers config?

Prefer wrangler.jsonc over wrangler.toml because newer features are JSON-only and JSONC supports comments for documenting configuration decisions. Flag wrangler.toml in new projects.

Why does my Worker fail with 'Cannot perform I/O on behalf of a different request'?

This error comes from module-level mutable state leaking across requests, since Workers reuse isolates. Pass request state explicitly through function arguments instead of assigning to module-scope variables.

When should I use Queues versus Workflows in Cloudflare Workers?

Use Queues for decoupling producers from consumers, fan-out, and simple single-step background jobs with at-least-once delivery. Use Workflows for multi-step durable execution where each step's result is persisted and only failed steps retry.