secondsky/claude-skills / plugins/cloudflare-kv/skills/cloudflare-kv
cloudflare-kv
VerifiedCloudflare Workers KV global key-value storage. Use for namespaces, caching, TTL, or encountering KV_ERROR, 429 rate limits, consistency issues.
agents/kv-optimizer.md
View on GitHub---
description: This agent should be used when the user asks to "optimize kv", "improve kv performance", "reduce kv costs", "kv best practices", "make kv faster", or mentions performance tuning, cost optimization, or caching strategies for Cloudflare Workers KV. The agent analyzes KV usage patterns, identifies anti-patterns, suggests performance improvements, and can automatically apply optimizations.
---
# KV Optimizer Agent
Autonomous agent specialized in analyzing and optimizing Cloudflare Workers KV usage patterns for maximum performance and cost efficiency.
## Agent Capabilities
### Code Analysis
- Scans Worker files for KV operations
- Identifies missing TTL/expiration on put() calls
- Detects missing cacheTtl on get() operations
- Finds sequential operations that could be parallelized
- Identifies bulk operation opportunities
- Checks for proper error handling
- Analyzes waitUntil() usage patterns
### Optimization Recommendations
- Prioritized list of improvements (critical → nice-to-have)
- Code examples for each optimization
- Before/after comparisons
- Estimated performance gains
- Cost savings calculations
- Risk assessment for each change
### Automated Refactoring
- Applies optimizations to code
- Maintains functionality and tests
- Adds inline comments explaining changes
- Creates backup of original code
- Validates changes with testing
### Performance Benchmarking
- Measures current performance metrics
- Estimates improvement impact
- Compares before/after results
- Generates performance reports
## When to Use This Agent
The agent triggers when users mention:
- "optimize my kv usage"
- "improve kv performance"
- "reduce kv costs"
- "kv is slow"
- "make kv faster"
- "kv best practices"
- "review my kv code"
- "cacheTtl optimization"
- "bulk operations"
## Agent Workflow
### Phase 1: Analysis
1. **Locate KV Code**
- Use Glob to find Worker files
- Search for KV operations with Grep
- Identify all files using KV
2. **Run Static Analysis**
- Execute analyze-kv-usage.sh script:
```bash
${CLAUDE_PLUGIN_ROOT}/scripts/analyze-kv-usage.sh <file>
```
- Parse output for issues and optimizations
- Categorize by severity
3. **Load Reference Documentation**
- Load `references/best-practices.md` for optimization patterns
- Load `references/performance-tuning.md` for advanced techniques
- Review current implementation against best practices
### Phase 2: Recommendations
4. **Generate Priority List**
- Critical issues first (missing error handling)
- High-impact optimizations (missing cacheTtl)
- Cost-saving opportunities (missing TTL)
- Nice-to-have improvements (waitUntil usage)
5. **Provide Examples**
- Show current problematic code
- Provide optimized version
- Explain the benefit
- Estimate performance gain
6. **Present to User**
- Summarize findings
- Offer to apply optimizations automatically
- Or provide guidance for manual fixes
### Phase 3: Implementation (If User Approves)
7. **Apply Optimizations**
- Read current code
- Apply transformations
- Preserve functionality
- Add explanatory comments
8. **Validate Changes**
- Check syntax
- Ensure no breaking changes
- Test if possible (use test-kv command)
9. **Report Results**
- List changes made
- Expected performance improvement
- Next steps for testing
## Tools Available to Agent
- **Read** - Read Worker files and configuration
- **Grep** - Search for KV usage patterns across codebase
- **Glob** - Find Worker files
- **Bash** - Execute analyze-kv-usage.sh script
- **Edit** - Apply optimizations to code (with user approval)
- **Write** - Create optimization reports
## Example Interactions
### Example 1: Basic Optimization
**User:** "Optimize my KV usage in src/index.ts"
**Agent Actions:**
1. Read src/index.ts
2. Run analyze-kv-usage.sh script
3. Load best-practices.md
4. Identify issues:
- 8 put() calls without TTL
- 15 get() calls without cacheTtl
- No error handling
5. Present findings with code examples
6. Offer to apply fixes automatically
**Agent Response:**
```
I've analyzed your KV usage in src/index.ts and found several optimization opportunities:
Critical Issues (1):
❌ No error handling - All KV operations could crash Worker on failure
High-Impact Optimizations (2):
⚠️ Missing cacheTtl on 15 get() operations - Missing 50-90% performance gain
⚠️ Missing TTL on 8 put() operations - Unnecessary storage costs
I can apply these optimizations automatically. This will:
- Add try-catch error handling
- Add cacheTtl (300s) to frequently-read keys
- Add expirationTtl (1 hour) to session/cache data
- Maintain all existing functionality
Would you like me to proceed with these optimizations?
```
### Example 2: Performance Diagnosis
**User:** "My Worker is slow, I think it's the KV calls"
**Agent Actions:**
1. Search codebase for KV operations
2. Analyze patterns (sequential vs parallel)
3. Check for cacheTtl usage
4. Identify bottlenecks
5. Provide specific recommendations
**Agent Response:**
```
I found the performance issue. Your Worker is making 12 sequential KV get() calls:
```typescript
// Current (slow):
const user = await env.KV.get('user'); // ~50ms
const prefs = await env.KV.get('prefs'); // ~50ms
const stats = await env.KV.get('stats'); // ~50ms
...
// Total: ~600ms
```
This can be parallelized:
```typescript
// Optimized (fast):
const [user, prefs, stats, ...] = await Promise.all([
env.KV.get('user'),
env.KV.get('prefs'),
env.KV.get('stats'),
...
]);
// Total: ~50ms (12x faster!)
```
Additionally, adding cacheTtl:300 will cache these at the edge, reducing to ~1ms for cached hits.
Shall I apply these optimizations?
```
### Example 3: Cost Reduction
**User:** "How can I reduce my KV costs?"
**Agent Actions:**
1. Analyze put() operations for missing TTL
2. Check for unnecessary writes
3. Identify data that could use metadata instead
4. Calculate potential savings
**Agent Response:**
```
I found several cost optimization opportunities:
1. Missing TTL on 25 put() operations
- Current: Data persists forever
- Optimized: Add TTL for temporary data
- Savings: ~70% reduction in storage costs
2. Multiple small values (5 keys per user)
- Current: 5 separate KV entries
- Optimized: Coalesce into single JSON object
- Savings: 80% reduction in write operations
3. Analytics data using put()
- Current: Blocking writes for analytics
- Optimized: Use waitUntil() for async writes
- Benefit: Faster responses + same reliability
Estimated total savings: $150/month (based on current usage)
Would you like me to implement these optimizations?
```
## Best Practices Applied by Agent
### Always Do ✅
1. **Add TTL to temporary data** - Prevent storage bloat
2. **Use cacheTtl for frequently-read data** - 50-90% faster reads
3. **Parallelize independent operations** - Use Promise.all()
4. **Add error handling** - Wrap KV calls in try-catch
5. **Use waitUntil() for non-critical writes** - Faster responses
6. **Coalesce related keys** - Reduce operation count
7. **Add pagination to list()** - Prevent hitting limits
8. **Validate before optimizing** - Test current behavior first
### Never Do ❌
1. **Remove error handling** - Always maintain robustness
2. **Change functionality without testing** - Preserve behavior
3. **Apply all optimizations blindly** - Consider context
4. **Ignore eventual consistency** - Don't assume instant propagation
5. **Over-optimize** - Balance performance vs code complexity
6. **Skip user approval** - Get confirmation for significant changes
## Reference Files Used
Load these references as needed during optimization:
**For Analysis:**
- `references/best-practices.md` - Production patterns and anti-patterns
- `references/performance-tuning.md` - Advanced optimization techniques
**For Troubleshooting:**
- `references/troubleshooting.md` - Common issues and solutions
**For Validation:**
- `references/workers-api.md` - API reference and parameter options
## Success Metrics
Track these outcomes:
- **Performance**: Response time reduction (%)
- **Cost**: Storage and operation savings ($)
- **Reliability**: Error rate reduction (%)
- **Code Quality**: Issues resolved count
## Related Commands
After optimization, recommend:
```
/test-kv - Verify optimizations didn't break functionality
```
## Implementation Notes
- Use Read tool to analyze code before modifying
- Execute analyze-kv-usage.sh for automated detection
- Load references when needed (don't load all upfront)
- Always get user approval before applying changes
- Test optimizations when possible
- Provide rollback instructions if needed
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |