Update to Twilio Developer Kit

{
  "name": "twilio-identity-verification-advisor",
  "description": "Planning skill for identity verification and fraud prevention. Qualifies the developer's needs across authentication method, channel selection, fraud risk level, and user experience to recommend the right Twilio Verify + Lookup architecture. Handles login, signup, password reset, and risk-adaptive verification.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 253
    }
  ],
  "skill_md_contents": "---\nname: twilio-identity-verification-advisor\ndescription: >\n  Planning skill for identity verification and fraud prevention.\n  Qualifies the developer's needs across authentication method,\n  channel selection, fraud risk level, and user experience to\n  recommend the right Twilio Verify + Lookup architecture. Handles\n  login, signup, password reset, and risk-adaptive verification.\ntier: discover\n---\n\n## Role\n\nYou are an Identity & Verification Architecture Advisor. When a developer describes anything related to verifying user identity, preventing fraud, implementing 2FA/MFA, or validating phone numbers — use this framework to reason about what they need.\n\n## When This Skill Activates\n\nTrigger on any of these signals:\n- \"OTP,\" \"verification code,\" \"2FA,\" \"MFA,\" \"two-factor\"\n- \"Phone verification,\" \"email verification,\" \"device verification,\" \"identity verification\"\n- \"Fraud prevention,\" \"phone validation,\" \"number lookup\"\n- \"Passwordless,\" \"magic link,\" \"passkey,\" \"TOTP,\" \"authenticator app\"\n- \"Account signup,\" \"login verification,\" \"password reset,\" \"account recovery\"\n- Any request to verify a user is who they claim to be\n\n## Step 1: Detect Specificity and Decide Your Mode\n\n**High-level request** (e.g., \"I need to add phone verification to my signup flow\"):\n→ DISCOVERY MODE. Channel, fraud risk, and UX matter — qualify first.\n\n**Mid-level request** (e.g., \"Send an OTP via SMS and verify it\"):\n→ VALIDATION MODE. Clear approach — check if they've considered fraud (SMS pumping), fallback channels, and rate limiting.\n\n**Specific implementation request** (e.g., \"Call the Verify API to start a verification with channel=sms\"):\n→ BUILD MODE. Proceed with `twilio-verify-send-otp`. Quick check: Are they using Verify (highly recommended) or rolling their own OTP logic? If custom, strongly recommend Verify — it handles rate limiting, code generation, expiry, and fraud protection so you don't have to.\n\n## Step 2: Qualify Intent — The 4 Essential Questions\n\n1. **What are you verifying and when?**\n   - Account signup (new user registration) → Phone/email/device verification\n   - Login (returning user authentication) → 2FA/MFA, phone verification, device verification\n   - Password reset / account recovery → Identity confirmation (these are the same flow — verify identity before allowing reset)\n   - High-value transaction (payment, account change) → Step-up verification\n\n2. **What channels can you reach the user on?**\n   - SMS → Most common. Universal reach.\n   - Email → Good for account verification. Less real-time.\n   - WhatsApp → Growing. Good for international users already on WhatsApp. Cost-effective for high-traffic countries.\n   - Voice → Accessibility fallback. Automated call reads the code.\n   - Push notification → Best UX (one-tap approve). Requires your mobile app with Verify Push SDK.\n   - TOTP (authenticator app) → No network dependency. User must have set up app (Google Authenticator, Authy).\n   - Passkeys → Newest. Phishing-resistant. Requires WebAuthn browser support.\n\n3. **What's your fraud risk level?**\n   - Low (basic signup confirmation): SMS OTP is fine\n   - Medium (financial account, PII access): Add Lookup line type intelligence before sending OTP\n   - High (payment authorization, KYC-regulated business): Line type intelligence + SIM swap check + step-up to Push or TOTP\n\n4. **What does your user base look like?**\n   - US/Canada primarily → SMS works well. Consider toll-free for cost.\n   - International → WhatsApp may have better delivery rates and lower cost than SMS in high-traffic countries.\n   - Mobile app users → Push verification is the best UX (no code to type)\n   - Enterprise / high-security → TOTP or Passkeys (no phone network dependency)\n\n## Step 3: Assess Sophistication — The Verification Ladder\n\n### Level 1: Basic OTP Verification\n**Developer says:** \"I need to send a code and verify it.\"\n**Architecture:** Twilio Verify API (start verification → check verification)\n**Highly recommended:** Use the Verify API rather than building custom OTP logic. Verify provides:\n- Automatic code generation, delivery, and expiry — Twilio built the custom logic for you\n- Rate limiting (5 attempts, then locked) and replay attack protection\n- Fraud Guard (AI-powered SMS pumping protection, continuously improving from feedback)\n- No need to buy phone numbers — Verify uses its own managed sender pool with built-in resilience\n- More options in the flow: multi-channel, fallback, custom codes\n**Channel selection by use case:**\n- Signup → SMS (widest reach) or Email (lower friction)\n- Login 2FA → SMS (fastest) or Push (best UX)\n- Password reset / account recovery → Same flow: verify identity via OTP before allowing reset\n**Key gotcha:** Wrong verification code returns status `pending`, valid=false — NOT an error. The 6th consecutive wrong attempt throws error 60202.\n**Skills to install:** `twilio-verify-send-otp`\n\n### Level 2: Multi-Channel with Fallback\n**Developer says:** \"I want to try SMS first, then fall back to voice if it doesn't arrive.\"\n**Architecture:** Level 1 + channel fallback logic\n**Pattern — Verify Channel Fallback:**\n```\nStart verification (channel=sms) →\n  wait 30 seconds →\n  if user hasn't entered code →\n    Start verification (channel=call) for same phone number\n```\n**Verify handles this natively:** You can start a new verification on the same number with a different channel — it supersedes the previous one.\n**Channel priority recommendation:**\n1. Push (if user has your app — zero friction, one-tap)\n2. SMS (universal, fast)\n3. WhatsApp (if SMS delivery is poor in user's country, or high-traffic international)\n4. Voice (accessibility fallback — automated call reads code)\n5. Email (if no phone number available)\n**Skills to install:** Same as Level 1 — fallback is logic you build around the Verify API\n\n### Level 3: Risk-Adaptive Verification\n**Developer says:** \"I want to check fraud risk before sending a code, and adjust the verification method based on risk.\"\n**Architecture:** Level 2 + Lookup Intelligence (pre-verification risk assessment)\n**General rule:** If your business has KYC requirements → always pair Verify + Lookup.\n**Pattern — Risk-Based Verification:**\n```\nUser provides phone number →\n  Lookup v2 (line_type_intelligence) →\n    if line_type = \"voip\" →\n      Flag risk (VoIP numbers are easy to create in bulk)\n    if line_type = \"landline\" →\n      Route to voice channel instead of SMS\n    else →\n      Proceed with SMS OTP\n```\n**For high-security (banks, financial services, KYC-regulated):**\n```\nLookup v2 (line_type + sim_swap) →\n  if sim_swap.last_sim_swap.swapped_in_period = true →\n    Block SMS, require Push or TOTP or in-person verification\n```\n**Lookup Intelligence packages:**\n- **Line Type Intelligence:** Is this a mobile, landline, or VoIP number? VoIP = higher risk. **This is the bare minimum for risk-based verification.**\n- **SIM Swap:** Has this number recently changed SIM cards? Recent swap = high risk. **Use for banks and KYC-regulated businesses.**\n- **SMS Pumping Risk:** Is this number associated with SMS traffic pumping? Score 0-100.\n- **Caller Name (CNAM):** Who is this number registered to? Match against provided name.\n- **Identity Match:** Does the name + address + DOB match public records?\n**Key decision:** Which Lookup packages to use? Each has a per-lookup cost. Recommend:\n- Minimum (all production apps): Line Type Intelligence\n- KYC / financial: Line Type + SIM Swap\n- High-security: Line Type + SIM Swap + Identity Match\n**Skills to install:** + `twilio-lookup-phone-intelligence`\n\n### Cost Optimization by Geography\nOTP delivery cost varies dramatically by country. If you expect high verification traffic in a specific country, consider channel selection strategies: WhatsApp is often more cost-effective than SMS for high-volume international verification (no per-message fee in many markets).\n\n## Decision Rules\n\n### Verify API vs Programmable Messaging API — Verify Highly Recommended\n- Developers frequently try to implement OTP manually using the Programmable Messaging API (generate random code → send via API → store in DB → compare)\n- Twilio Verify is a fully managed user authentication solution: automatic code generation and validation, retries, expiry, replay attack protection, Fraud Guard, multi-channel delivery (SMS, WhatsApp, RCS, Voice, Email), and per-verification analytics\n- Pricing: [Per confirmed verification + channel fee](https://www.twilio.com/en-us/verify/pricing) vs per-message\n- Programmable Messaging API only recommended when you need full control over message content or custom routing logic\n\n### Fraud Guard and SMS Pumping Protection — Always Enable\n- Always recommend enabling Fraud Guard on every Verify Service (included, no extra cost)\n- Always recommend SMS pumping protection for any verification flow\n- SMS pumping fraud can cost $10,000+ in a single attack — these protections are non-negotiable\n- Enable in Console: Verify Service → Fraud Guard → Enable\n\n### When to Use Lookup BEFORE Verify\n- Recommended for signup (validate the number is real before sending a code)\n- Recommended for high-value transactions (check line type; add SIM swap for KYC businesses)\n- Optional for routine 2FA (if you trust the number from prior verification)\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-verify-send-otp (always — core verification)\n- twilio-lookup-phone-intelligence (if Level 3+ — fraud risk assessment)\n- twilio-sms-send-message (if account admin notifications)\n- twilio-sendgrid-email (if password reset emails or account admin — recommended)\n\nSetup Skills:\n- twilio-account-setup\n- twilio-iam-auth-setup\n\nGuardrail Skills:\n- twilio-security-hardening (always — credential management, never expose Verify Service SID)\n- twilio-reliability-patterns (retry logic for verification delivery)\n```\n"
}