agentleFS
pabloirracionalpabloirracional/claude-skills/skills/reviewing-cloudflare-workers-code/SKILL.md

reviewing-cloudflare-workers-code

Skill0 starsChanged 4 months agoMITView on GitHub

Reviews and writes Cloudflare Workers code against production constraints, verified with a real local Workers runtime (Miniflare) - including a corrected finding about what nodejs_compat actually covers. Use whenever the user is building, deploying, or debugging a Cloudflare Worker, or mentions wrangler, KV, R2, D1, or edge functions.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Secrets: read from env, set via wrangler secret put - never hardcoded or committed in .env.

    line 15
  2. Distinctive:

    If the user needs long-running background work, mention Durable Objects or Queues rather than trying to force it into a single …

    line 48

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Reviewing Cloudflare Workers code

Reviews Workers code for correctness under real edge runtime constraints - tested against Miniflare (Cloudflare's actual local Workers runtime), not assumed from general JS knowledge.

Workflow

  1. Check runtime assumptions - Workers don't have Node.js APIs by default. See the tested, corrected finding below on exactly what nodejs_compat does and doesn't cover.
  2. Review bindings: KV, R2, D1, Queues should be declared and typed via the Env interface - confirmed working pattern below.
  3. Check cold-start sensitive code: move heavy synchronous setup inside the request handler where possible.
  4. Secrets: read from env, set via wrangler secret put - never hardcoded or committed in .env.
  5. Local dev vs deploy: Miniflare (local) accurately emulates KV; some bindings (R2, D1 in certain configurations) may behave differently locally vs deployed - confirm on a real deploy for anything binding-sensitive before calling it done.

Tested: KV binding works end-to-end

Real Miniflare instance, a Worker that writes to KV then reads it back in a separate request:

await env.MY_KV.put('hello', 'world from KV');
// ...separate request...
const value = await env.MY_KV.get('hello');

Confirmed result: world from KV - round-trip works correctly through Miniflare's local KV emulation.

Tested and corrected: what nodejs_compat actually covers

Initial assumption going in: "nodejs_compat lets Node built-ins work." Testing showed this is not quite right - it depends entirely on which built-in.

node:fs - fails even WITH nodejs_compat enabled:

service core:user:: Uncaught Error: No such module "node:fs".

This isn't a missing flag - Workers run on an edge runtime with no filesystem at all. nodejs_compat polyfills Node.js APIs, it doesn't invent a disk that doesn't exist. Any code depending on fs needs a fundamentally different approach (KV/R2 for storage), not a compat flag.

node:buffer - fails without the flag, works with it:

  • Without nodejs_compat: Unable to resolve "no-compat-buffer.mjs" dependency "node:buffer": no matching module rules.
  • With nodejs_compat + a recent compatibilityDate (2024-09-23 used in testing): Buffer worked: aGVsbG8= - Buffer.from('hello').toString('base64') executed correctly.

Practical rule this gives: when reviewing code that imports a Node built-in, don't just check "is nodejs_compat set" - check whether that specific built-in is one that's actually polyfilled (buffer, events, path, process, partial crypto, and others) versus one that's structurally impossible on the platform (fs, and anything else assuming local disk or OS-level process access). Flag fs usage as "needs a different approach," not "needs a flag."

Also confirmed: the compat flag alone wasn't sufficient in testing - it needed pairing with an explicit compatibilityDate recent enough to include the relevant polyfill. An old or missing compatibilityDate can silently disable nodejs_compat behavior that the flag name suggests should be active.

Notes

  • If the user needs long-running background work, mention Durable Objects or Queues rather than trying to force it into a single request-response Worker.
  • This was tested with Miniflare's Node API directly (not the wrangler dev CLI) - behavior should match, since Miniflare is the same engine Wrangler uses locally, but always confirm against a real wrangler dev/deploy for anything binding-configuration-sensitive.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.