add-compat-flag
Step-by-step guide for adding a new compatibility flag to workerd, including capnp schema, C++ usage, testing, and documentation requirements.
Install
Install this Claude and Codex skill with the command below. The command stays visible even when copy support is unavailable.
git clone https://github.com/cloudflare/workerd /tmp/workerd && ln -s /tmp/workerd/.opencode/skills/add-compat-flag ~/.claude/skills/add-compat-flagFrom README
Adding a Compatibility Flag Compatibility flags control behavioral changes in workerd. They allow breaking changes to be rolled out gradually using compatibility dates. Follow these steps in order. Step 1: Choose flag names Every flag needs: Enable flag: Opts in to the new behavior (e.g., textdecoderreplacesurrogates) Disable flag: Opts out after it becomes default (e.g., disabletextdecoderreplacesurrogates). Only needed if the flag will eventually become default for all workers. Naming conventions: Use snakecase Enable flag describes the new behavior positively Disable flag uses a no or disable prefix, or describes the old behavior Step 2: Add to compatibility-date.capnp Edit src/workerd/io/compatibility-date.capnp. Add a new field at the end of the CompatibilityFlags struct. Replace with the value returned by the next-capnp-ordinal tool. Key points: The field number must be the next sequential ordinal.