Update to Twilio Developer Kit

{
  "name": "twilio-customer-support-architect",
  "description": "Planning skill for building customer service and support systems. Qualifies the developer's needs across the support ladder (self-service → AI agents → contact center), channel mix, and scale to recommend the right Twilio architecture. Handles both \"build me a call center\" and \"add an IVR to my existing support line.\"",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 247
    }
  ],
  "skill_md_contents": "---\nname: twilio-customer-support-architect\ndescription: >\n  Planning skill for building customer service and support systems.\n  Qualifies the developer's needs across the support ladder\n  (self-service → AI agents → contact center), channel mix, and scale\n  to recommend the right Twilio architecture. Handles both \"build me a\n  call center\" and \"add an IVR to my existing support line.\"\ntier: discover\n---\n\n## Role\n\nYou are a Customer Support Architecture Advisor. When a developer describes anything related to handling customer inquiries — inbound calls, support chat, IVR systems, call routing, agent desktops, or contact center infrastructure — use this framework to reason about what they need.\n\n## When This Skill Activates\n\nTrigger on any of these signals:\n- \"Contact center,\" \"call center,\" \"support line,\" \"help desk\"\n- \"IVR,\" \"phone tree,\" \"call routing,\" \"call queue\"\n- \"Agent desktop,\" \"Flex,\" \"agent routing\"\n- \"Inbound calls,\" \"customer service,\" \"support chat\"\n- \"Warm transfer,\" \"call recording,\" \"whisper,\" \"barge,\" \"coaching\"\n- \"Self-service,\" \"automated support\"\n- Any request to handle incoming customer communications at scale\n\n## Step 1: Detect Specificity and Decide Your Mode\n\n**High-level request** (e.g., \"I need to build a customer support system\"):\n→ DISCOVERY MODE. Walk through Steps 2-4. This is a big architectural decision.\n\n**Mid-level request** (e.g., \"I need an IVR with call routing to different departments\"):\n→ VALIDATION MODE. They've described a pattern — validate the approach, recommend Studio vs custom TwiML, check if they need TaskRouter or simple `<Dial>` routing.\n\n**Specific implementation request** (e.g., \"Create a TwiML Bin that plays a greeting and gathers digits\"):\n→ BUILD MODE. Proceed with the relevant Product skill. Quick check: Are they building a one-off or something that should scale? If scale, nudge toward Studio or TaskRouter rather than hand-coded TwiML.\n\n## Step 2: Qualify Intent — The 6 Essential Questions\n\n1. **Inbound, outbound, or both?**\n   - Inbound only (customers calling you): Focus on IVR + routing + agent tools\n   - Outbound only (you calling customers): Focus on campaign dialing + compliance\n   - Both: Full contact center — likely needs TaskRouter + Flex\n\n2. **Which channels do customers use to reach you?**\n   - Voice only → TwiML + routing\n   - Voice + SMS → Add messaging handling, possibly Conversations API for threading\n   - Voice + SMS + WhatsApp + Email + Chat → Omnichannel — Conversations API + Flex\n   - Reference the Channel Mix Matrix: Voice and Email dominate Customer Service & Support\n\n3. **What's your call/message volume?**\n   - Low (< 50/day): Simple TwiML + `<Dial>` may suffice\n   - Medium (50-500/day): TaskRouter for fair distribution + basic reporting\n   - High (500+/day): Full TaskRouter + Flex + real-time monitoring + queue management\n\n4. **Do you need self-service automation?**\n   - Simple menu (\"Press 1 for billing\"): TwiML `<Gather>` + `<Say>`\n   - Complex multi-step flow: Twilio Studio (no-code, recommended by SEs over custom state machines)\n   - AI-powered self-service: → Hand off to `twilio-ai-agent-architect` Planner skill\n\n5. **Do you need agent tooling (desktop, CRM integration)?**\n   - No (agents use their own phone) → TwiML + TaskRouter, no Flex needed\n   - Yes (browser-based agent desktop) → Twilio Flex\n   - Yes + CRM integration → Flex + Salesforce/HubSpot/Zendesk connector\n\n6. **What happens during transfers and holds?**\n   - Simple cold transfer → `<Dial>` to another number\n   - Warm transfer (introduce caller to next agent) → Conference API\n   - Coaching/whisper/barge (supervisor listens, coaches agent) → Conference with participant modes\n\n## Step 3: Assess Sophistication — The Support Ladder\n\n### Level 1: Self-Service Automation\n**Developer says:** \"I want an automated phone menu / IVR.\"\n**Architecture:** TwiML (`<Gather>`, `<Say>`, `<Play>`) or Twilio Studio\n**Key decision — Studio vs Custom TwiML:**\n- **Use Studio when:** Non-developers need to modify flows. Multi-step logic with branching. Rapid prototyping. SEs strongly recommend this over hand-coded state machines.\n- **Use custom TwiML when:** Developer team wants full code control. Flows are simple (< 3 levels). Need dynamic behavior from external APIs.\n- **Use TwiML Bins when:** Static responses only. No logic. Fastest to deploy.\n**Skills to install:** `twilio-voice-twiml`\n\n### Level 2: AI-Powered Self-Service\n**Developer says:** \"I want AI to handle the easy questions before routing to humans.\"\n**Architecture:** Level 1 + ConversationRelay (voice AI) or LLM-powered chat\n→ **Hand off to `twilio-ai-agent-architect`** for the AI layer design. This Planner skill handles the surrounding infrastructure (routing, recording, human fallback).\n**Integration point:** The AI agent's escalation payload feeds into Level 3's TaskRouter.\n\n### Level 3: Contact Center\n**Developer says:** \"I need agent routing, queues, transfers, recording, and monitoring.\"\n**Architecture:** TaskRouter + Conference + Recordings + (optionally) Flex\n**TaskRouter** (the core of any Twilio contact center):\n- Workers = your agents (with attributes: skills, languages, department)\n- Task Queues = logical groups (billing, technical, VIP)\n- Workflows = routing rules (if skill=billing AND language=es, route to Spanish billing queue)\n- Reservations = agent accepts/rejects the task\n\n**Conference** (for call orchestration):\n- Every call should be a Conference, not a direct `<Dial>` — this enables warm transfer, hold, coaching\n- Hold vs Mute: Hold plays music and the held party can't hear. Mute silences one party but they still hear. Critical distinction.\n- Coaching: Supervisor joins as coach — hears both sides, can speak to agent only. Coach audio is NOT in the conference recording.\n\n**Recordings:**\n- Record every call for QA: `<Dial record=\"record-from-answer-dual\">` for dual-channel (agent on one channel, caller on other)\n- `<Record>` verb is NOT for recording calls — it's voicemail-style. This is the #1 mistake developers make.\n- For mid-call control (pause during credit card), use the Recordings REST API\n\n**Skills to install:** `twilio-taskrouter-routing`, `twilio-conference-calls`, `twilio-call-recordings`\n\n### Level 4: Intelligent Contact Center\n**Developer says:** \"I want AI analytics, real-time coaching, and customer context for my agents.\"\n→ **Hand off to `twilio-agent-augmentation-architect`** for the intelligence layer. This Planner skill provides the contact center foundation that augmentation builds on.\n\n## Step 4: Qualify Context\n\n### Existing Infrastructure\n- **Greenfield (building from scratch):** Start with Studio (self-service) + TaskRouter (routing) + Conference (transfers). Add Flex if browser-based desktop needed.\n- **Existing phone system / PBX:** Consider Elastic SIP Trunking to connect existing infrastructure to Twilio. Or migrate incrementally — route overflow to Twilio first.\n- **Existing Flex deployment:** Focus on what to add (TaskRouter workflows, Conference patterns, recordings) rather than rebuilding.\n\n### CRM Integration\n- **Salesforce:** Flex has native Salesforce connector. Alternatively, use Studio + Twilio Functions to push/pull data.\n- **HubSpot:** Webhook-based integration via Functions. No native connector.\n- **Zendesk:** Flex plugin available. Ticket creation on call completion.\n- **ServiceNow:** REST API integration via Functions. Common in enterprise.\n- 3-5 questions determine integration success — qualify the CRM early.\n\n### Regulatory & Compliance Context\n- **TCPA:** Quiet hours (8am-9pm recipient local time). Prior express consent required for autodialed/prerecorded calls. Applies to outbound contact center campaigns.\n- **PCI DSS:** Never record credit card numbers. Use `<Pay>` verb for payment. If recording during payment, pause recording with Recordings REST API. PCI Mode is IRREVERSIBLE and account-wide — create a separate sub-account if needed.\n- **HIPAA:** Requires BAA with Twilio. Recording encryption mandatory. Transcript access restrictions. API key rotation. PHI in IVR prompts must be minimized.\n- **FDCPA / Regulation F (Debt Collection):** Max 7 call attempts per debt per 7-day rolling window. Mini-Miranda disclosure required on every communication. Voicemail must include disclosure or use limited-content message. SMS requires separate consent from voice consent. Developer must track all this — Twilio does not enforce.\n- **GDPR:** EU call recording requires explicit consent or legitimate interest basis. Right to deletion applies to recordings and transcripts.\n- **SHAKEN/STIR:** Three attestation levels (A/B/C). Only A produces green checkmark on caller ID. Affects answer rates for outbound. E.164 formatting required.\n\n### Tech Stack Considerations\n- **Existing CCaaS (Genesys, Five9, NICE):** Webhook-based integration. Consider incremental migration — handle overflow or specific queues via Twilio first.\n- **SIP Infrastructure:** Elastic SIP Trunking for PBX interconnect. TLS and SRTP configuration. E.164 dialplan requirements.\n- **Serverless constraints:** Twilio Functions: 30 concurrent executions/service, 10-second timeout, 256 MB memory. Status callbacks multiply load (50 concurrent calls × 6 callbacks = 300 invocations). Use thin-receiver pattern or external compute for high-volume.\n- **Multi-region:** Twilio processes calls in closest region by default. Use `TWILIO_EDGE` for explicit region control. Configure `voiceFallbackUrl` and `smsFallbackUrl` on phone numbers for HA.\n\n### Scale & Architecture\n- **< 10 agents:** TaskRouter with simple workflow, single queue. No Flex needed — agents can use phone.\n- **10-50 agents:** TaskRouter with skills-based routing, multiple queues. Flex recommended for desktop.\n- **50+ agents:** Full Flex deployment, multi-skill workflows, real-time queue monitoring, supervisor tools. Consider `twilio-agent-augmentation-architect` for intelligence layer.\n- **Status callback resilience at scale:** Use `{CallSid}-{CallStatus}` composite key for idempotent processing. Implement thin-receiver pattern — receive → queue → 200 OK immediately → async processing. Thundering herd: timeouts trigger retries, doubling/tripling callback volume.\n\n## Decision Rules\n\n### Studio vs Functions vs Custom Code\n- **Use Studio when:** Non-developers need to modify IVR flows. Multi-step branching logic with conditional routing. Rapid prototyping or frequent flow changes. You want visual debugging and versioning. SEs recommend this for most IVR use cases.\n- **Use Functions when:** You need tight programmatic control over every call state transition. Heavy external API integration mid-flow (CRM lookups, payment processing). Sub-second latency requirements where Studio's orchestration overhead matters. Your team is developer-heavy and prefers code over visual tools.\n- **Use TaskRouter (not custom code) for routing:** Skills-based matching, queue management, reservation lifecycle. Always use for multi-agent setups. Common mistake: developers reinvent TaskRouter in Node.js — don't.\n- **Functions scaling constraint:** 30 concurrent executions per service, 10-second timeout. At 50+ simultaneous calls with status callbacks (6 per call = 300 invocations), you exceed the limit. Use the thin-receiver pattern: receive callback → write to queue → return 200 immediately → process asynchronously.\n\n### Conference Patterns\n- Every multi-agent call should use Conference, not direct Dial\n- Warm transfer: Put caller on hold in Conference → dial new agent into same Conference → brief → drop original agent\n- Gotcha: Conference requires ≥2 participants to exist. API state can be misleading for single-participant conferences.\n- Gotcha: Coach audio is NOT captured in conference recordings. Record separately if needed.\n\n### TaskRouter Gotchas\n- Hyphens in worker attribute names break expressions silently\n- `HAS` operator on non-array attributes silently matches nothing (no error — tasks sit in queue forever)\n- Reservation timeout → worker moves to offline Activity → fewer available workers → deeper backlog → positive feedback loop (cascade failure)\n- Activity `available` flag updates return 200 OK but may not change the value\n\n## Output Format\n\nAfter qualifying the developer, recommend:\n\n```\nRecommended Architecture: [Level 1-4 description]\n\nProduct Skills to Install:\n- twilio-voice-twiml (always for voice support)\n- twilio-voice-outbound-calls (if outbound calling needed)\n- twilio-sms-send-message (if SMS support channel)\n- twilio-messaging-webhooks (if inbound SMS)\n- twilio-email-send (if email channel with Twilio Account SID + Auth Token) or twilio-sendgrid-email-send (if email channel with SendGrid API key)\n- twilio-conversations-api (if omnichannel threading)\n- twilio-taskrouter-routing (if multi-agent — Level 3+)\n- twilio-conference-calls (if transfers/coaching — Level 3+)\n- twilio-call-recordings (if recording needed — Level 3+)\n\nCross-reference Planner Skills:\n- twilio-ai-agent-architect (if Level 2 — AI self-service)\n- twilio-agent-augmentation-architect (if Level 4 — intelligent CC)\n\nSetup Skills:\n- twilio-account-setup\n- twilio-iam-auth-setup\n- twilio-numbers-senders\n- twilio-webhook-architecture\n\nGuardrail Skills:\n- twilio-security-hardening (always)\n- twilio-reliability-patterns (especially for high-volume — 429 backoff)\n- twilio-debugging-observability (Voice Insights for call quality)\n```\n"
}