Source: cloudflare/skills · Maintainer: Cloudflare · License: Apache-2.0 · Checked: 24 October 2026
What is the Durable Objects skill?
The Durable Objects skill is durable-objects, Cloudflare's official Agent Skill for building, debugging and reviewing Durable Objects code. It gives your coding agent the core rules, the anti-patterns to avoid and a map of current Cloudflare docs, so stateful Workers code is modeled and stored correctly.
Its SKILL.md description reads: "Build, debug, or review Cloudflare Durable Objects code for persistent state and coordination."
Like other skills in the repo, it starts by distrusting the model's memory: "Your knowledge of Durable Objects APIs and configuration may be outdated. Prefer retrieval over pre-training for any Durable Objects task." As of 24 October 2026, its skills.sh page listed 108.8K installs (snapshot, 24 October 2026).
What does it do?
The skill loads when you create Durable Object classes, add RPC methods, alarms or WebSocket handlers, configure bindings and migrations, write tests or design sharding. The folder holds four files:
SKILL.md: when to use Durable Objects, a Wrangler config example, a basic class pattern, the critical rules, anti-patterns, stub creation, storage and alarms.references/rules.md: a short set of principles plus a table that sends each task (object boundaries, SQLite or legacy KV storage, migrations, data location, RPC, alarms, WebSocket hibernation, error handling) to the matching Cloudflare docs page.references/testing.md: how to choose and write tests with Cloudflare's Vitest integration.references/workers.md: Worker handlers, types, Wrangler config, request validation, logging, CORS and secrets.
When to use Durable Objects. The SKILL.md has a table of good fits, each with examples:
| Need | Example from the skill |
|---|---|
| Coordination | Chat rooms, multiplayer games, collaborative docs |
| Strong consistency | Inventory, booking systems, turn-based games |
| Per-entity storage | Multi-tenant SaaS, per-user data |
| Persistent connections | WebSockets, real-time notifications |
| Scheduled work per entity | Subscription renewals, game timeouts |
It is just as clear about poor fits: stateless request handling ("use plain Workers"), maximum global distribution needs, and high fan-out independent requests.
The seven critical rules, from the SKILL.md:
- Model around coordination atoms: one object per chat room, game or user, not one global object.
- Use
getByName()for deterministic routing, so the same input reaches the same instance. - Use SQLite storage by configuring
new_sqlite_classesin migrations. - Initialize in the constructor, using
blockConcurrencyWhile()for schema setup only. - Use RPC methods, not a
fetch()handler (compatibility date 2024-04-03 or later). - Persist first, cache second: write to storage before updating in-memory state.
- One alarm per object:
setAlarm()replaces any existing alarm.
Anti-patterns marked NEVER. A single global object handling all requests, blockConcurrencyWhile() on every request, critical state held only in memory, await between related storage writes (which "breaks atomicity"), and holding blockConcurrencyWhile() across fetch() or other external I/O.
The rest of SKILL.md is short TypeScript: a class that creates a SQLite table in its constructor and exposes an addItem RPC method, the three ways to create a stub (getByName, idFromString, newUniqueId), synchronous sql.exec next to the async KV API, and scheduling, handling and cancelling an alarm. For anything beyond that, the references point to Cloudflare's Rules of Durable Objects and the API pages.
How do you install it?
The cloudflare/skills README lists several routes. Pick one per agent.
Just this skill, with the skills CLI. This is the command on skills.sh:
npx skills add https://github.com/cloudflare/skills --skill durable-objects
Add -g for all projects. For Claude Code, the folder lands in .claude/skills/durable-objects/ in your project, or ~/.claude/skills/durable-objects/ globally, the standard Claude Code skill locations.
Claude Code plugin (every Cloudflare skill plus the MCP server). From the README:
/plugin marketplace add cloudflare/skills
/plugin install cloudflare@cloudflare
This also brings workers-best-practices and wrangler, which the Durable Objects work usually touches.
Codex plugin.
codex plugin marketplace add cloudflare/skills
codex plugin add cloudflare@cloudflare
Start a new Codex session afterward, as the README says.
Cursor, VS Code and manual copy. Cursor installs from its marketplace or as a remote rule pointing at cloudflare/skills; VS Code with GitHub Copilot installs from source after enabling chat.plugins.enabled; or clone the repo and copy the folder. See Codex skills and Cursor skills for where each agent looks.
How do you use it?
Describe the stateful thing you are building, or point the agent at existing code. Example prompts (suggestions, not quotes from the repo):
Build a Durable Object for a chat room: one object per room, messages in SQLite, history over RPC.Review src/counter.ts against Durable Objects best practices and list each problem with the fix.Add a 24-hour expiry to each booking hold using an alarm, and make sure rescheduling works.Our presence service uses one global Durable Object and slows down under load. Propose a sharding plan.Write Vitest tests that prove two rooms keep separate state and that the alarm clears expired holds.
For tests, the testing reference asks the agent to inspect your installed Vitest and Cloudflare packages first and to follow the matching guide; "adding a test does not by itself require migrating the suite." It points to Cloudflare's Testing Durable Objects example for RPC, routes, SQLite and alarms.
You need a Workers project with Wrangler. The skill holds no keys.
Tips and limits
- It routes more than it teaches.
rules.mdandtesting.mddeliberately keep signatures, limits and runnable examples in Cloudflare's docs. Give the agent web or MCP access, or it works from the short SKILL.md alone. - Check old classes before changing storage. The rules say to "inspect the backend of existing classes before selecting APIs," since older classes may use the legacy KV storage API.
- Plan for hibernation. For idle WebSocket servers the skill prefers hibernation and says to plan for state restoration; Cloudflare's WebSockets guide has the details.
- Access follows the Worker. The skill notes that Durable Objects have no separate roles or permissions; access follows the Worker that implements them.
- No scripts. All four files are Markdown.
- Audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk.
- License. Apache-2.0 lets you copy and change it; keep the license and notices when you redistribute.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its references/ files, and for a repo with many skills it shows a list, so you can add wrangler too. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Cloudflare.
Similar skills
- Cloudflare Agents SDK skill: stateful AI agents on Workers, built on the same platform features.
- Cloudflare Workers skill: runtime anti-patterns for the Worker that fronts your objects; it defers Durable Objects work to this skill.
- Wrangler skill: deploys, migrations, bindings and secrets from the CLI.
- Postgres best practices skill: if your state belongs in a central database instead.