cloudflare-kv
Use when persisting tool data in Cloudflare KV - Describes bindings, key naming, and function conventions.
When & Why to Use This Skill
This Claude skill provides a standardized framework for persisting tool data using Cloudflare KV, enabling agents to maintain state across sessions. It covers essential best practices for namespace bindings, isolated key naming conventions, and atomic access patterns to ensure reliable data consistency and long-term memory for AI tools.
Use Cases
- Cross-Session State Management: Persist tool-specific data such as counters, user preferences, or progress markers to maintain continuity across multiple agent interactions.
- Data Isolation in Shared Environments: Implement structured key-naming (e.g., tool-name:key) to prevent data collisions when multiple tools utilize the same Cloudflare KV namespace.
- Optimized Cloudflare Functions Integration: Streamline data access within Cloudflare Workers using standardized environment bindings and error-handling patterns for high-performance tool execution.
- Structured Context Storage: Serialize complex tool states into JSON blobs, allowing agents to retrieve and update structured information efficiently during multi-turn tasks.
| name | cloudflare-kv |
|---|---|
| description | "Use when persisting tool data in Cloudflare KV - Describes bindings, key naming, and function conventions." |
Cloudflare KV basics
- Cloudflare deploys a shared KV namespace bound as
TOOLS_KVfor all tools. Use the binding directly; do not create new namespaces per tool. - Structure keys as
<tool-name>:<key>so data stays isolated between tools. - Store small JSON blobs or strings. For structured data, serialize to JSON and document the schema in the tool README.
Access patterns
- Prefer atomic operations like
TOOLS_KV.get,put, anddelete. For counters, useTOOLS_KV.get+putwith retries or Workers KV atomic counters when available. - Always handle the
nullcase ongetto avoidundefineddata paths for first-time users. - Cache reads in memory during a single request when multiple lookups are required.
Cloudflare Functions
- Name or prefix Functions after the tool, e.g.
counter_incrementorcounter/functions/incrementso routes stay organized. - In Functions, read and write KV via the
env.TOOLS_KVbinding provided in the handler signature. - Return descriptive error messages and HTTP status codes for KV failures to simplify debugging.
Example
The counter tool stores its count in TOOLS_KV under the key counter:value. Reuse that pattern whenever you need shared state across sessions.