Skip to content
Workers Best Practices

Workers Best Practices Skill

by Cloudflare cloudflare/skills skills/workers-best-practices

Production review rules for Cloudflare Workers — compatibility dates, observability wiring, and the runtime anti-patterns that only bite at the edge.

GitHub Docs
DevelopmentDevOps & Infrastructure
Released
Apache-2.0

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from cloudflare/skills.

$ npx skills add cloudflare/skills --skill workers-best-practices

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/workers-best-practices/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/cloudflare/skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/workers-best-practices ~/.claude/skills/workers-best-practices

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/workers-best-practices/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • Anti-pattern table pairing each mistake with its runtime consequence
  • Catches the traces flag that the top-level observability setting misses
  • Keeps compatibility_date current for new and existing Workers
  • Retrieval-first: verifies APIs and limits against live docs, not memory

Workers code that looks correct in review can still fail in production, because the failure modes are runtime-specific: a buffered response body that exhausts an isolate's memory, async work started but never awaited, a compatibility date frozen years in the past. This official Cloudflare skill is the checklist for writing, reviewing and configuring Workers meant to carry real traffic.

It opens with a stance rather than a rule: prefer retrieval over pre-training. The project's installed package versions, generated types and Wrangler compatibility settings are the baseline for existing code, and claims about APIs, limits and runtime behaviour are verified against current Cloudflare documentation instead of recalled. Three reference files carry the detail — configuration and observability, runtime patterns, and platform API checks — and the skill directs the agent to read only the one the task needs.

Two operational defaults are called out. Compatibility dates should be current, set to today's date for new Workers and reviewed periodically for existing ones against the flags they already run under. Observability should be switched on before production: both observability.enabled and observability.traces.enabled, since the top-level setting alone does not turn on traces — a detail that silently costs teams their tracing.

The anti-pattern table is where the skill earns its place in a code review. Unbounded await response.text() buffering should be streaming. Hardcoded secrets belong in Wrangler secrets. Math.random() for security-sensitive tokens or IDs should be crypto.randomUUID() or crypto.getRandomValues(). Each entry pairs the mistake with its consequence and the preferred pattern, so the agent can flag it with a reason attached. Apache-2.0, and the longest-running skill in Cloudflare's collection.

SKILL.md

The instructions your agent loads, as published by Cloudflare.

SKILL.md
name
workers-best-practices
description
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.

Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. Prefer retrieval over pre-training when writing or reviewing Workers code.

Use the project's installed versions, generated types, and Wrangler compatibility settings as the baseline for existing code. Retrieve relevant Cloudflare documentation to verify API, configuration, runtime behavior, and limit claims.

References

Read the sections relevant to the task:

ReferenceWhen to use it
[Configuration and observability](references/configuration.md)Compatibility dates, bindings, generated types, secrets, logs, and traces
[Runtime patterns](references/runtime-patterns.md)Streaming, promise lifetime, request state, service calls, security, and runtime tests
[Platform API checks](references/platform-apis.md)Handler signatures, platform classes, binding access, and serialization

For missing evidence, consult Workers best practices or find the affected product in the Cloudflare docs directory. Use the installed Wrangler schema for config fields. A newer type package does not supersede the project's configured target.

Keep Compatibility Dates Current

Use today's date for new Workers. Encourage periodic updates for existing Workers, reviewing compatibility changes and running relevant tests. Assess existing behavior against its configured date and flags; see [compatibility guidance](references/configuration.md#keep-compatibility_date-current).

Enable Observability

Enable Workers Logs and Traces when creating or preparing a Worker for production. Set observability.enabled and observability.traces.enabled to true; the top-level setting alone does not enable traces. Use structured JSON logging and configure sampling for the workload. During reviews, flag missing logs or traces. See the [configuration example](references/configuration.md#enable-workers-logs-and-traces).

Anti-Patterns to Flag
Anti-patternConsequence and preferred pattern
await response.text() or similar buffering on unbounded dataCan exhaust Worker memory; [stream large or unbounded bodies](references/runtime-patterns.md#stream-request-and-response-bodies).
Hardcoded secrets in source or configLeaks credentials through version control; use Wrangler secrets.
Math.random() for security-sensitive tokens or IDsPredictable values; use crypto.randomUUID() or crypto.getRandomValues().
Async work started without awaiting, returning, or attaching it to ctx.waitUntil()Work can be dropped and errors missed; tie it to the request or background-work lifetime.
Module-level mutable request stateLeaks data across requests and can cause I/O ownership errors; pass request state explicitly.
Cloudflare REST API calls for operations available through Worker bindingsAdds network and authentication overhead; use the available binding.
ctx.passThroughOnException() used as general error handlingCan conceal Worker failures by forwarding to the origin; use explicit error handling and structured error responses.
Hand-written Env that duplicates Wrangler bindingsCan drift from configuration; generate binding types with wrangler types.
Direct string comparison of secret valuesCan expose timing differences; use the [Web Crypto comparison pattern](references/runtime-patterns.md#use-web-crypto-for-secure-token-generation).
Destructuring ctx methods, such as const { waitUntil } = ctxLoses the receiver; call ctx.waitUntil(...).
any on Env or handler parametersHides binding and handler contract errors; use the project's generated and platform types.
as unknown as T to force a platform type matchHides incompatibilities; fix the underlying contract.
implements used in place of extending a platform base classDoes not inherit runtime behavior, this.ctx, or this.env; use the appropriate base class.
Unbound env.X in a platform class methodBindings are available through this.env.X; see [binding access patterns](references/platform-apis.md#binding-access--the-most-common-error).
Applying one serialization rule across Queues, Workflow steps, storage, and WebSocketsCan reject valid payloads or accept unsupported ones; check the [specific API and encoding](references/platform-apis.md#serialization-boundaries).
Validation

Use the project's existing checks for affected Workers behavior: type-check binding or handler contract changes, and run relevant runtime tests for behavior changes. Preserve required repository checks; a narrow edit does not require a full Workers audit.

Scope

This skill covers Workers-specific best practices and code review. For related topics:

  • Durable Objects: load the durable-objects skill
  • Workflows: see Rules of Workflows
  • Wrangler CLI commands: load the wrangler skill
Install

Related Skills

See all Workers Best Practices alternatives

Skill: Cloudflare Email Service

by Cloudflare

Wire up Cloudflare Email Sending and Email Routing — the send_email binding, the inbound email() handler, and the deliverability setup that keeps mail out of spam.

Development

Skill: Turnstile Spin

by Cloudflare

Turns “set up Turnstile” into a working end-to-end bot check — widget, frontend snippets, canonical server-side siteverify, and a real validation pass before it reports success.

DevelopmentSecurity
Browse all skills →