# add-compat-flag

> Claude/Codex skill by [@cloudflare](https://omgskills.com/library/cloudflare/index.md) · 8.4k stars · Updated 2026-08-04

Step-by-step guide for adding a new compatibility flag to workerd, including capnp schema, C++ usage, testing, and documentation requirements.

## Install

```sh
git clone https://github.com/cloudflare/workerd /tmp/workerd && ln -s /tmp/workerd/.opencode/skills/add-compat-flag ~/.claude/skills/add-compat-flag
```

## From 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.

## Links

- HTML page: https://omgskills.com/skills/cloudflare/workerd/add-compat-flag/
- GitHub: https://github.com/cloudflare/workerd
- Author: [@cloudflare](https://omgskills.com/library/cloudflare/index.md)

## More from this repo

- [bazel-test-hygiene](https://omgskills.com/skills/cloudflare/workerd/bazel-test-hygiene/index.md) — Mandatory rules for running bazel tests during development.
   - [@cloudflare](https://omgskills.com/library/cloudflare/index.md) · 8.7k stars
- [commit-categories](https://omgskills.com/skills/cloudflare/workerd/commit-categories/index.md) — Commit categorization rules for changelogs and "what's new" summaries.
   - [@cloudflare](https://omgskills.com/library/cloudflare/index.md) · 8.7k stars
- [dad-jokes](https://omgskills.com/skills/cloudflare/workerd/dad-jokes/index.md) — After completing any task that took more than ~5 tool calls, or after long-running builds/tests finish, load this skill...
   - [@cloudflare](https://omgskills.com/library/cloudflare/index.md) · 8.7k stars