[PR #12] [CLOSED] refactor: unifying DO skill

kerem commented

2026-03-02 03:21:15 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/cloudflare/skills/pull/12
Author: @hiendaovinh
Created: 2/3/2026
Status: ❌ Closed

Base: main ← Head: consolidate-do

📝 Commits (1)

12a3744 refactor: unifying DO skill

📊 Changes

6 files changed (+153 additions, -320 deletions)

View changed files

📝 skills/cloudflare/references/durable-objects/README.md (+7 -4)
📝 skills/cloudflare/references/durable-objects/patterns.md (+106 -1)
📝 skills/cloudflare/references/durable-objects/testing.md (+15 -9)
📝 skills/cloudflare/references/durable-objects/workers-integration.md (+11 -5)
📝 skills/durable-objects/SKILL.md (+14 -15)
➖ skills/durable-objects/references/rules.md (+0 -286)

📄 Description

Hi, like mentioned earlier, Durable Objects are kinda duplicated between 2 skills: the root durable-objects and cloudflare skill.

So, I would like to propose a merge between those two. Start by maintaining the current durable-objects skill as a lite version of cloudflare/durable-objects.

Below are the plan from Opus 4.5 and the code change.

Plan: Unify Durable Objects Skills                                                                                                                                                                  
                                                                                                                                                                                                     
 Summary                                                                                                                                                                                             
                                                                                                                                                                                                     
 Consolidate durable-objects content into the cloudflare skill (authoritative source) while keeping a thin standalone skill for discoverability. This combines the best of both: cloudflare's error  
 reference/limits/decision trees with standalone's testing/workers-integration/concurrency content.                                                                                                  
                                                                                                                                                                                                     
 Current State                                                                                                                                                                                       
                                                                                                                                                                                                     
 Standalone skill (skills/durable-objects/):                                                                                                                                                         
 - Strengths: Testing (Vitest), Workers integration, concurrency explanation, schema migrations                                                                                                      
 - Files: SKILL.md, references/{rules.md, workers.md, testing.md}                                                                                                                                    
                                                                                                                                                                                                     
 Cloudflare skill (skills/cloudflare/references/durable-objects/):                                                                                                                                   
 - Strengths: Error reference, limits table, lifecycle states, decision trees                                                                                                                        
 - Files: README.md, configuration.md, api.md, patterns.md, gotchas.md                                                                                                                               
                                                                                                                                                                                                     
 Changes                                                                                                                                                                                             
                                                                                                                                                                                                     
 Phase 1: Add Missing Content to Cloudflare Skill                                                                                                                                                    
                                                                                                                                                                                                     
 1.1 Create testing.md (NEW)                                                                                                                                                                         
                                                                                                                                                                                                     
 File: skills/cloudflare/references/durable-objects/testing.md                                                                                                                                       
 - Source: skills/durable-objects/references/testing.md                                                                                                                                              
 - Content: Vitest setup, unit/integration tests, runInDurableObject(), runDurableObjectAlarm(), listDurableObjectIds()                                                                              
 - Add cross-reference to do-storage/testing.md for storage-specific tests                                                                                                                           
                                                                                                                                                                                                     
 1.2 Create workers-integration.md (NEW)                                                                                                                                                             
                                                                                                                                                                                                     
 File: skills/cloudflare/references/durable-objects/workers-integration.md                                                                                                                           
 - Source: skills/durable-objects/references/workers.md                                                                                                                                              
 - Content: Handler patterns, Zod validation, logging, CORS, secrets management                                                                                                                      
                                                                                                                                                                                                     
 1.3 Enhance patterns.md (MODIFY)                                                                                                                                                                    
                                                                                                                                                                                                     
 File: skills/cloudflare/references/durable-objects/patterns.md                                                                                                                                      
 - Add concurrency section from standalone rules.md:                                                                                                                                                 
   - Input/output gates                                                                                                                                                                              
   - Write coalescing (no await = atomic batch)                                                                                                                                                      
   - Race conditions with external I/O                                                                                                                                                               
   - blockConcurrencyWhile() misuse warning                                                                                                                                                          
 - Add schema migration pattern with PRAGMA user_version                                                                                                                                             
                                                                                                                                                                                                     
 1.4 Update README.md (MODIFY)                                                                                                                                                                       
                                                                                                                                                                                                     
 File: skills/cloudflare/references/durable-objects/README.md                                                                                                                                        
 - Add testing.md and workers-integration.md to "In This Reference" section                                                                                                                          
 - Update reading order to include testing step                                                                                                                                                      
                                                                                                                                                                                                     
 Phase 2: Convert Standalone to Thin Reference                                                                                                                                                       
                                                                                                                                                                                                     
 2.1 Simplify SKILL.md (MODIFY)                                                                                                                                                                      
                                                                                                                                                                                                     
 File: skills/durable-objects/SKILL.md                                                                                                                                                               
 - Keep: description (for discoverability), quick reference snippets, critical rules                                                                                                                 
 - Add: pointers to cloudflare skill for deep dives                                                                                                                                                  
 - Remove: detailed reference file pointers (will be deleted)                                                                                                                                        
                                                                                                                                                                                                     
 2.2 Delete Redundant Reference Files (DELETE)                                                                                                                                                       
                                                                                                                                                                                                     
 - skills/durable-objects/references/rules.md → merged into cloudflare patterns.md                                                                                                                   
 - skills/durable-objects/references/workers.md → moved to cloudflare workers-integration.md                                                                                                         
 - skills/durable-objects/references/testing.md → moved to cloudflare testing.md                                                                                                                     
                                                                                                                                                                                                     
 Files to Modify/Create                                                                                                                                                                              
 ┌────────┬─────────────────────────────────────────────────────────────────────┐                                                                                                                    
 │ Action │                                File                                 │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ CREATE │ skills/cloudflare/references/durable-objects/testing.md             │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ CREATE │ skills/cloudflare/references/durable-objects/workers-integration.md │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ MODIFY │ skills/cloudflare/references/durable-objects/README.md              │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ MODIFY │ skills/cloudflare/references/durable-objects/patterns.md            │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ MODIFY │ skills/durable-objects/SKILL.md                                     │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ DELETE │ skills/durable-objects/references/rules.md                          │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ DELETE │ skills/durable-objects/references/workers.md                        │                                                                                                                    
 ├────────┼─────────────────────────────────────────────────────────────────────┤                                                                                                                    
 │ DELETE │ skills/durable-objects/references/testing.md                        │                                                                                                                    
 └────────┴─────────────────────────────────────────────────────────────────────┘                                                                                                                    
 Execution Order                                                                                                                                                                                     
                                                                                                                                                                                                     
 1. Create cloudflare/.../durable-objects/testing.md                                                                                                                                                 
 2. Create cloudflare/.../durable-objects/workers-integration.md                                                                                                                                     
 3. Update cloudflare/.../durable-objects/README.md                                                                                                                                                  
 4. Update cloudflare/.../durable-objects/patterns.md                                                                                                                                                
 5. Update durable-objects/SKILL.md (thin reference)                                                                                                                                                 
 6. Delete standalone reference files                                                                                                                                                                
                                                                                                                                                                                                     
 Verification                                                                                                                                                                                        
                                                                                                                                                                                                     
 - Verify cloudflare skill has testing.md and workers-integration.md                                                                                                                                 
 - Verify patterns.md has concurrency section                                                                                                                                                        
 - Verify standalone SKILL.md points to cloudflare for deep dives                                                                                                                                    
 - Verify no broken internal references                                                                                                                                                              
 - Check that both skills can be invoked and load correctly

What do you think?

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/cloudflare/skills/pull/12 **Author:** [@hiendaovinh](https://github.com/hiendaovinh) **Created:** 2/3/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `consolidate-do` --- ### 📝 Commits (1) - [`12a3744`](https://github.com/cloudflare/skills/commit/12a3744e84a202c76a7f9410aa9151535584f9ef) refactor: unifying DO skill ### 📊 Changes **6 files changed** (+153 additions, -320 deletions) <details> <summary>View changed files</summary> 📝 `skills/cloudflare/references/durable-objects/README.md` (+7 -4) 📝 `skills/cloudflare/references/durable-objects/patterns.md` (+106 -1) 📝 `skills/cloudflare/references/durable-objects/testing.md` (+15 -9) 📝 `skills/cloudflare/references/durable-objects/workers-integration.md` (+11 -5) 📝 `skills/durable-objects/SKILL.md` (+14 -15) ➖ `skills/durable-objects/references/rules.md` (+0 -286) </details> ### 📄 Description Hi, like mentioned earlier, Durable Objects are kinda duplicated between 2 skills: the root durable-objects and cloudflare skill. So, I would like to propose a merge between those two. Start by maintaining the current durable-objects skill as a lite version of cloudflare/durable-objects. Below are the plan from Opus 4.5 and the code change. ``` Plan: Unify Durable Objects Skills Summary Consolidate durable-objects content into the cloudflare skill (authoritative source) while keeping a thin standalone skill for discoverability. This combines the best of both: cloudflare's error reference/limits/decision trees with standalone's testing/workers-integration/concurrency content. Current State Standalone skill (skills/durable-objects/): - Strengths: Testing (Vitest), Workers integration, concurrency explanation, schema migrations - Files: SKILL.md, references/{rules.md, workers.md, testing.md} Cloudflare skill (skills/cloudflare/references/durable-objects/): - Strengths: Error reference, limits table, lifecycle states, decision trees - Files: README.md, configuration.md, api.md, patterns.md, gotchas.md Changes Phase 1: Add Missing Content to Cloudflare Skill 1.1 Create testing.md (NEW) File: skills/cloudflare/references/durable-objects/testing.md - Source: skills/durable-objects/references/testing.md - Content: Vitest setup, unit/integration tests, runInDurableObject(), runDurableObjectAlarm(), listDurableObjectIds() - Add cross-reference to do-storage/testing.md for storage-specific tests 1.2 Create workers-integration.md (NEW) File: skills/cloudflare/references/durable-objects/workers-integration.md - Source: skills/durable-objects/references/workers.md - Content: Handler patterns, Zod validation, logging, CORS, secrets management 1.3 Enhance patterns.md (MODIFY) File: skills/cloudflare/references/durable-objects/patterns.md - Add concurrency section from standalone rules.md: - Input/output gates - Write coalescing (no await = atomic batch) - Race conditions with external I/O - blockConcurrencyWhile() misuse warning - Add schema migration pattern with PRAGMA user_version 1.4 Update README.md (MODIFY) File: skills/cloudflare/references/durable-objects/README.md - Add testing.md and workers-integration.md to "In This Reference" section - Update reading order to include testing step Phase 2: Convert Standalone to Thin Reference 2.1 Simplify SKILL.md (MODIFY) File: skills/durable-objects/SKILL.md - Keep: description (for discoverability), quick reference snippets, critical rules - Add: pointers to cloudflare skill for deep dives - Remove: detailed reference file pointers (will be deleted) 2.2 Delete Redundant Reference Files (DELETE) - skills/durable-objects/references/rules.md → merged into cloudflare patterns.md - skills/durable-objects/references/workers.md → moved to cloudflare workers-integration.md - skills/durable-objects/references/testing.md → moved to cloudflare testing.md Files to Modify/Create ┌────────┬─────────────────────────────────────────────────────────────────────┐ │ Action │ File │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ CREATE │ skills/cloudflare/references/durable-objects/testing.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ CREATE │ skills/cloudflare/references/durable-objects/workers-integration.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ MODIFY │ skills/cloudflare/references/durable-objects/README.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ MODIFY │ skills/cloudflare/references/durable-objects/patterns.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ MODIFY │ skills/durable-objects/SKILL.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ DELETE │ skills/durable-objects/references/rules.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ DELETE │ skills/durable-objects/references/workers.md │ ├────────┼─────────────────────────────────────────────────────────────────────┤ │ DELETE │ skills/durable-objects/references/testing.md │ └────────┴─────────────────────────────────────────────────────────────────────┘ Execution Order 1. Create cloudflare/.../durable-objects/testing.md 2. Create cloudflare/.../durable-objects/workers-integration.md 3. Update cloudflare/.../durable-objects/README.md 4. Update cloudflare/.../durable-objects/patterns.md 5. Update durable-objects/SKILL.md (thin reference) 6. Delete standalone reference files Verification - Verify cloudflare skill has testing.md and workers-integration.md - Verify patterns.md has concurrency section - Verify standalone SKILL.md points to cloudflare for deep dives - Verify no broken internal references - Check that both skills can be invoked and load correctly ``` What do you think? --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>