Agent skill

workers-binding-validator

Automatically validates Cloudflare Workers binding configuration, ensuring code references match wrangler.toml setup and TypeScript interfaces are accurate

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/workers-binding-validator-hirefrank-hirefrank-marketplac

SKILL.md

Workers Binding Validator SKILL

Activation Patterns

This SKILL automatically activates when:

  • env parameter is used in Workers code
  • wrangler.toml file is modified
  • TypeScript Env interface is defined or updated
  • New binding references are added to code
  • Binding configuration patterns are detected

Expertise Provided

Binding Configuration Validation

  • Binding Consistency: Ensures code references match wrangler.toml configuration
  • TypeScript Interface Validation: Validates Env interface matches actual bindings
  • Binding Type Accuracy: Ensures correct binding types (KV, R2, D1, Durable Objects)
  • Remote Binding Validation: Checks remote binding configuration for development
  • Secret Binding Verification: Validates secret vs environment variable bindings

Specific Checks Performed

❌ Critical Binding Mismatches

typescript
// These patterns trigger immediate alerts:
// Code references binding that doesn't exist in wrangler.toml
const user = await env.USER_DATA.get(id);  // USER_DATA not configured

// TypeScript interface doesn't match wrangler.toml
interface Env {
  USERS: KVNamespace;     // Code expects USERS
  // wrangler.toml has USER_DATA (mismatch!)
}

✅ Correct Binding Patterns

typescript
// These patterns are validated as correct:
// Matching wrangler.toml and TypeScript interface
interface Env {
  USER_DATA: KVNamespace;  // Matches wrangler.toml binding name
  API_BUCKET: R2Bucket;    // Correct R2 binding type
}

// Proper usage in code
const user = await env.USER_DATA.get(id);
const object = await env.API_BUCKET.get(key);

Integration Points

Complementary to Existing Components

  • binding-context-analyzer agent: Handles complex binding analysis, SKILL provides immediate validation
  • workers-runtime-validator SKILL: Complements runtime checks with binding validation
  • cloudflare-security-checker SKILL: Ensures secret bindings are properly configured

Escalation Triggers

  • Complex binding architecture questions → binding-context-analyzer agent
  • Migration between binding types → cloudflare-architecture-strategist agent
  • Binding performance issues → edge-performance-oracle agent

Validation Rules

P1 - Critical (Will Fail at Runtime)

  • Missing Bindings: Code references bindings not in wrangler.toml
  • Type Mismatches: Wrong binding types in TypeScript interface
  • Name Mismatches: Different names in code vs configuration
  • Missing Env Interface: No TypeScript interface for bindings

P2 - High (Configuration Issues)

  • Remote Binding Missing: Development bindings without remote = true
  • Secret vs Var Confusion: Secrets in [vars] section or vice versa
  • Incomplete Interface: Missing bindings in TypeScript interface

P3 - Medium (Best Practices)

  • Binding Documentation: Missing JSDoc comments for bindings
  • Binding Organization: Poor organization of related bindings

Remediation Examples

Fixing Missing Bindings

typescript
// ❌ Critical: Code references binding not in wrangler.toml
export default {
  async fetch(request: Request, env: Env) {
    const user = await env.USER_CACHE.get(userId); // USER_CACHE not configured!
  }
}

// wrangler.toml (missing binding)
[[kv_namespaces]]
binding = "USER_DATA"  # Different name!
id = "user-data"

// ✅ Correct: Matching names
export default {
  async fetch(request: Request, env: Env) {
    const user = await env.USER_DATA.get(userId); // Matches wrangler.toml
  }
}

// wrangler.toml (correct binding)
[[kv_namespaces]]
binding = "USER_DATA"  # Matches code!
id = "user-data"

Fixing TypeScript Interface Mismatches

typescript
// ❌ Critical: Interface doesn't match wrangler.toml
interface Env {
  USERS: KVNamespace;      // Code expects USERS
  SESSIONS: KVNamespace;    // Code expects SESSIONS
}

// wrangler.toml has different names
[[kv_namespaces]]
binding = "USER_DATA"      # Different!
id = "user-data"

[[kv_namespaces]]
binding = "SESSION_DATA"    # Different!
id = "session-data"

// ✅ Correct: Matching interface and configuration
interface Env {
  USER_DATA: KVNamespace;   # Matches wrangler.toml
  SESSION_DATA: KVNamespace; # Matches wrangler.toml
}

// wrangler.toml (matching names)
[[kv_namespaces]]
binding = "USER_DATA"       # Matches interface!
id = "user-data"

[[kv_namespaces]]
binding = "SESSION_DATA"     # Matches interface!
id = "session-data"

Fixing Binding Type Mismatches

typescript
// ❌ Critical: Wrong binding type
interface Env {
  MY_BUCKET: KVNamespace;    # Wrong type - should be R2Bucket
  MY_DB: D1Database;        # Wrong type - should be KVNamespace
}

// wrangler.toml
[[r2_buckets]]
binding = "MY_BUCKET"       # R2 bucket, not KV!

[[kv_namespaces]]
binding = "MY_DB"           # KV namespace, not D1!

// ✅ Correct: Proper binding types
interface Env {
  MY_BUCKET: R2Bucket;      # Correct type for R2 bucket
  MY_DB: KVNamespace;       # Correct type for KV namespace
}

// wrangler.toml (same as above)
[[r2_buckets]]
binding = "MY_BUCKET"

[[kv_namespaces]]
binding = "MY_DB"

Fixing Remote Binding Configuration

typescript
// ❌ High: Missing remote binding for development
// wrangler.toml
[[kv_namespaces]]
binding = "USER_DATA"
id = "user-data"
# Missing remote = true for development!

// ✅ Correct: Remote binding configured
[[kv_namespaces]]
binding = "USER_DATA"
id = "user-data"
remote = true  # Enables remote binding for development

Fixing Secret vs Environment Variable Confusion

typescript
// ❌ High: Secret in [vars] section (visible in git)
// wrangler.toml
[vars]
API_KEY = "sk_live_12345"  # Secret exposed in git!

// ✅ Correct: Secret via wrangler secret command
// wrangler.toml (no secrets in [vars])
[vars]
PUBLIC_API_URL = "https://api.example.com"  # Non-secret config only

# Set secret via command line:
# wrangler secret put API_KEY
# (prompt: enter secret value)

// Code accesses both correctly
interface Env {
  API_KEY: string;           # From wrangler secret
  PUBLIC_API_URL: string;    # From wrangler.toml [vars]
}

MCP Server Integration

When Cloudflare MCP server is available:

  • Query actual binding configuration from Cloudflare account
  • Verify bindings exist and are accessible
  • Check binding permissions and limits
  • Get latest binding configuration best practices

Benefits

Immediate Impact

  • Prevents Runtime Failures: Catches binding mismatches before deployment
  • Reduces Debugging Time: Immediate feedback on configuration issues
  • Ensures Type Safety: Validates TypeScript interfaces match reality

Long-term Value

  • Consistent Configuration: Ensures all code uses correct binding patterns
  • Better Developer Experience: Clear error messages for binding issues
  • Reduced Deployment Issues: Configuration validation prevents failed deployments

Usage Examples

During Binding Usage

typescript
// Developer types: const data = await env.CACHE.get(key);
// SKILL immediately activates: "❌ CRITICAL: CACHE binding not found in wrangler.toml. Add [[kv_namespaces]] binding = 'CACHE' or check spelling."

During Interface Definition

typescript
// Developer types: interface Env { USERS: R2Bucket; }
// SKILL immediately activates: "⚠️ HIGH: USERS binding type mismatch. wrangler.toml shows USERS as KVNamespace, not R2Bucket."

During Configuration Changes

typescript
// Developer modifies wrangler.toml binding name
// SKILL immediately activates: "⚠️ HIGH: Binding name changed from USER_DATA to USERS. Update TypeScript interface and code references."

Binding Type Reference

KV Namespace

typescript
interface Env {
  MY_KV: KVNamespace;
}
// Usage: await env.MY_KV.get(key)

R2 Bucket

typescript
interface Env {
  MY_BUCKET: R2Bucket;
}
// Usage: await env.MY_BUCKET.get(key)

D1 Database

typescript
interface Env {
  MY_DB: D1Database;
}
// Usage: await env.MY_DB.prepare(query).bind(params).all()

Durable Object

typescript
interface Env {
  MY_DO: DurableObjectNamespace;
}
// Usage: env.MY_DO.get(id)

AI Binding

typescript
interface Env {
  AI: Ai;
}
// Usage: await env.AI.run(model, params)

Vectorize

typescript
interface Env {
  VECTORS: VectorizeIndex;
}
// Usage: await env.VECTORS.query(vector, options)

This SKILL ensures Workers binding configuration is correct by providing immediate, autonomous validation of binding patterns, preventing runtime failures and configuration mismatches.

Didn't find tool you were looking for?

Be as detailed as possible for better results