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.