workers-best-practices AI Agent Skill

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

Retrieval Sources

Fetch the latest versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.

FIRST: Fetch Latest References

Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's node_modules has an older version, prefer the latest published version.

# Fetch latest workers types
mkdir -p /tmp/workers-types-latest && \
  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# Types at /tmp/workers-types-latest/package/index.d.ts

Reference Documentation

• references/rules.md — all best practice rules with code examples and anti-patterns
• references/review.md — type validation, config validation, binding access patterns, review process

Rules Quick Reference

Configuration

Request & Response Handling

Architecture

Observability

Code Patterns

Security

Anti-Patterns to Flag

Review Workflow

1. Retrieve — fetch latest best practices page, workers types, and wrangler schema
2. Read full files — not just diffs; context matters for binding access patterns
3. Check types — binding access, handler signatures, no any, no unsafe casts (see references/review.md)
4. Check config — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
5. Check patterns — streaming, floating promises, global state, serialization boundaries
6. Check security — crypto usage, secret handling, timing-safe comparisons, error handling
7. Validate with tools — npx tsc --noEmit, lint for no-floating-promises
8. Reference rules — see references/rules.md for each rule's correct pattern

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

Principles

• Be certain. Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
• Provide evidence. Reference line numbers, tool output, or docs links.
• Focus on what developers will copy. Workers code in examples and docs gets pasted into production.
• Correctness over completeness. A concise example that works beats a comprehensive one with errors.