Python Workers Skill

A Claude Code skill for building Cloudflare Workers in Python.

Python Workers run on Pyodide (CPython compiled to WebAssembly) inside V8 isolates. This creates a unique set of challenges — the JS/Python FFI boundary, JsProxy conversion, async-only HTTP, cold start management, and package compatibility — that this skill addresses.

Install

npx skills add adewale/python-workers-skill

What's Covered

FFI boundary — to_js() / .to_py() conversion, dict_converter, None vs null vs undefined, type-compatibility matrix, binary data handling
All bindings — D1, KV, R2, Queues, Vectorize, Workers AI, Durable Objects (storage, alarms, WebSockets), Workflows, Service Bindings
Static Assets — routing, run_worker_first, why this matters more for Python (cold starts)
Testing — HAS_PYODIDE guard, mock bindings, Pyodide fakes, three-tier strategy
Configuration — wrangler.jsonc, compatibility flags, packages, .dev.vars, CPU limits
18 gotchas — with error signatures and fixes
Anti-patterns — raw JsProxy in business logic, dict without dict_converter, module-level PRNG, and more

Files

skills/python-workers/                     # The installable skill
├── SKILL.md                               # Skill definition, decision trees, anti-patterns
└── references/python-workers/
    ├── README.md                          # Runtime overview, quick start, project structure
    ├── api.md                             # Handlers, Response, FFI, bindings, Workflows
    ├── configuration.md                   # wrangler.jsonc, packages, flags, testing setup
    ├── gotchas.md                         # 18 Python-specific issues
    └── patterns.md                        # FFI boundary, D1 conversion, Static Assets, DOs, testing
BEST_PRACTICES.md                          # Human-readable mirror (for review/feedback)
tests/                                     # Evals
└── evals.json

Reading Order

Task	Start With	Then Read
First Python Worker	README.md	configuration.md → api.md
Add FastAPI	api.md (ASGI Bridge)	patterns.md (request.js_object)
Debug JsProxy error	gotchas.md (#6, #9)	patterns.md (FFI Boundary)
Set up testing	patterns.md (Testing)	configuration.md (Test Setup)
Add Static Assets	patterns.md (Static Assets)	configuration.md (wrangler.jsonc)
Use Durable Objects	patterns.md (Durable Objects)	api.md (Handlers)
Check package compatibility	configuration.md (Packages)	gotchas.md (#13)
Something isn't working	gotchas.md (Quick Reference table)	patterns.md

All files are in skills/python-workers/references/python-workers/.

Contributing

BEST_PRACTICES.md mirrors the skill's contents in a readable format. If you spot something wrong, outdated, or missing, open an issue or submit a PR.

Sources

Built from production experience with planet_cf and tasche, the official Cloudflare Python Workers docs, and cloudflare/python-workers-examples.

adewale/python-workers-skill