Agent-Skills.md

Agent Skills: ElevenLabs Production Checklist

|

UncategorizedID: jeremylongshore/claude-code-plugins-plus-skills/elevenlabs-prod-checklist

Repository

jeremylongshore/claude-code-plugins-plus-skills
jeremylongshoreLicense: NOASSERTION
1,723221

Install this agent skill to your local

pnpm dlx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/HEAD/plugins/saas-packs/elevenlabs-pack/skills/elevenlabs-prod-checklist

Skill Files

Browse the full folder contents for elevenlabs-prod-checklist.

Download Skill

Loading file tree…

plugins/saas-packs/elevenlabs-pack/skills/elevenlabs-prod-checklist/SKILL.md

Skill Metadata

Name
elevenlabs-prod-checklist
Description
|

ElevenLabs Production Checklist

Overview

Complete checklist for deploying ElevenLabs TTS/voice integrations to production. Covers API configuration, health checks, circuit breakers, monitoring, and rollback procedures. The deep code for the resilience primitives lives in references/ so this file stays a fast, scannable runbook — drill in when you need the full implementation.

Prerequisites

  • Staging environment tested and verified
  • Production API key (separate from dev/staging)
  • Monitoring and alerting infrastructure ready

Instructions

Step 1: Pre-Deployment Verification

Walk the checklist below. Every unchecked box is a launch blocker.

Configuration:

  • [ ] Production API key stored in secure vault (not in code)
  • [ ] ELEVENLABS_API_KEY set in deployment platform's secrets
  • [ ] Webhook secret configured (if using webhooks)
  • [ ] Using production model ID (eleven_multilingual_v2 or eleven_v3)

Code Quality:

  • [ ] All tests passing with mocked ElevenLabs SDK
  • [ ] No hardcoded API keys (scan with grep -r "sk_" src/)
  • [ ] Error handling covers 400, 401, 404, 429, 5xx responses
  • [ ] Rate limiting implemented matching plan concurrency limit
  • [ ] Text splitting handles inputs > 5,000 characters
  • [ ] Audio output format appropriate for use case

Quota Planning:

  • [ ] Estimated monthly character usage fits within plan limit
  • [ ] Usage-based billing enabled (Creator+ plans) if needed
  • [ ] Flash/Turbo models used where latency matters more than quality

Step 2: Wire the resilience primitives

Production ElevenLabs integrations need three primitives. The full drop-in TypeScript for each is in references/implementation.md — high-level intent:

  1. Health check endpoint — reports connectivity, latency, and remaining quota; returns degraded past 90% quota and unhealthy on any API failure, so a load balancer can gate traffic.
  2. Circuit breaker — opens after N consecutive failures, cools down, then probes half-open; accepts a fallback (placeholder audio / cached clip / null) so a TTS outage degrades gracefully instead of throwing.
  3. Monitoring & alerting — emit one structured metric per TTS call and drive the alert thresholds in the table below into your observability platform.

Step 3: Run the pre-flight gate

Before promoting a build, run the pre-flight script — it checks connectivity, quota, voice availability, and a live TTS smoke test, exiting non-zero on any hard failure so it can block a CI/CD deploy step. Full script + CI wiring: references/preflight.md.

# The load-bearing first gate — full script in references/preflight.md
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  https://api.elevenlabs.io/v1/user \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}")
[ "$HTTP" != "200" ] && echo "FAIL: API not reachable" && exit 1

Output

Running this checklist produces:

  • A completed pre-deployment verification (every box in Step 1 checked or explicitly waived).
  • A health-check endpoint returning healthy / degraded / unhealthy plus latency and remaining quota.
  • A circuit breaker and monitoring harness wired into the TTS call path.
  • A green pre-flight run (=== All checks passed ===, exit 0) gating the deploy.
  • A monitoring/alerting matrix mapped to your on-call severities (see below).

Deployment Monitoring

| Alert | Condition | Severity | |-------|-----------|----------| | API unreachable | Health check fails 3x | P1 — Critical | | Quota exhausted | 401 quota_exceeded | P1 — Critical | | High error rate | 5xx > 5% of requests | P2 — High | | Rate limited | 429 > 10/min sustained | P2 — High | | High latency | p99 > 5000ms | P3 — Medium | | Quota warning | > 80% used | P3 — Medium |

Error Handling

| Scenario | Response | |----------|----------| | ElevenLabs API down | Circuit breaker opens; fallback to cached/placeholder audio | | Quota exhausted mid-day | Alert team; switch to Flash model (0.5x cost); queue non-urgent requests | | Voice deleted | Return 404 to caller; alert; fall back to default voice | | Webhook delivery failing | Monitor ElevenLabs webhook health; webhooks auto-disable after 10 failures |

Examples

Gate a deploy on the pre-flight script. Run it as the last step before promotion; a non-zero exit blocks the pipeline:

$ ELEVENLABS_API_KEY=$PROD_KEY ./scripts/pre-flight-check.sh
=== ElevenLabs Pre-Flight Check ===
API connectivity: HTTP 200
Characters remaining: 428193
Voices available: 14
TTS smoke test: HTTP 200
=== All checks passed ===
$ echo $?
0

Poll the health endpoint for a load-balancer probe. A degraded status (quota > 90%) still serves traffic but pages on-call; unhealthy drains the node:

$ curl -s https://myapp.example.com/health | jq '.status, .elevenlabs.quotaPctUsed'
"healthy"
41

Full worked implementations for both: references/implementation.md and references/preflight.md.

Resources

Next Steps

For version upgrades, see elevenlabs-upgrade-migration. For cost optimization, see elevenlabs-cost-tuning.