Claude CodeでTwilio公式スキルを使う — 導入から計画・実装・安全策まで

Twilioは、AIコーディングエージェント向けの公式スキルをtwilio/aiリポジトリで配布しています。Claude Codeにはプラグインとして入り、「SMSを送りたい」「本人確認を足したい」と頼むだけで、該当する手順書が自動で読み込まれます。API仕様を引くMCPとは役割が違い、スキルが渡すのはどの製品を選び、何を避けるかという判断の知識です。

Twilioのスキルは何を渡し、MCPと何が違うか

スキルは、AIエージェント向けに手続き知識をまとめたパッケージです。起動時にはすべてのスキルの軽量なメタデータだけが見え、依頼がスキルの説明に合致したときに本体が読み込まれ、必要なら参照資料まで掘り下げます。コンテキストを圧迫せずに、深い知識を必要な場面だけで使う設計です。

Twilioのリポジトリは、スキルとMCPを1つのプラグインにまとめて配っています。両者の担当は次のように分かれます。

スキルの狙いは3つ挙げられています。1つ目は製品選定で、本人確認なら「Twilio Verifyか自前のOTPか」「不正対策にLookupを足すか」を、コードを書く前に整理させます。2つ目はアーキテクチャの提案で、AI音声エージェントを頼まれたときは利用ケースの複雑さを質問してから、Conversation Relay・Memory・Conversation Intelligence・TaskRouterといった組み合わせを勧めます。3つ目は避けるべき点の明示で、各スキルにCANNOT節を持たせ、制約や典型的な落とし穴を書いて幻覚を減らします。

4種類のスキルと、リポジトリの中身

スキルは役割で4種類に分かれます。

twilio/aiリポジトリのskills/配下は、Twilio本体向けのtwilioディレクトリにスキルが49個、メール配信のSendGrid向けのsendgridディレクトリに8個あります。SMS・MMS・WhatsApp・RCS・Voice・Verify・SendGrid・Conversations・Messaging Services・コンプライアンス(A2P 10DLC、Toll-Free、STIR/SHAKEN)が対象です。

各スキルは、YAMLのfrontmatterにnameとdescriptionを持つSKILL.mdです。Productスキルの本文は、概要・前提条件・クイックスタート・主要パターン・CANNOT・次のステップの順に並びます。Plannerスキルは別の型で、役割・起動条件・質問の手順・判断ルール・出力形式を持ちます。

Claude Codeに入れる手順

Claude Codeでは、Twilioのマーケットプレイスを追加してプラグインを入れます。このプラグインtwilio-developer-kitにはスキルとMCPの両方が含まれます。

/plugin marketplace add twilio/ai
/plugin install twilio-developer-kit@twilio

シェルから入れる場合はclaude plugin installが使えます。チームで共有するなら、次のようにプロジェクトスコープを指定します。

claude plugin marketplace add twilio/ai
claude plugin install twilio-developer-kit@twilio --scope project

プロジェクトスコープの設定は.claude/settings.jsonに入り、コミットすれば共同作業者側でも有効になります。ただしプラグインの実体は各自のマシンにダウンロードされないため、共同作業者もそれぞれ同じインストールコマンドを一度実行する必要があります。

動いているかを確かめる

導入後は、READMEの確認用プロンプトをそのまま投げるのが手早い方法です。

How do I send an SMS with Twilio?

スキルが効いていれば、学習データだけに頼らず、Messaging Services・A2Pコンプライアンス・エラー処理に触れたうえで、深掘り用のスキルを勧める回答になります。素のモデルがclient.messages.createの最小例だけを返すなら、スキルが読まれていません。その場合は、スキルの一覧を見る/skillsコマンドの使い方でtwilio-で始まる名前が並んでいるかを確かめます。

スキルは依頼が説明に合うと自動で起動しますが、名前を指定して直接呼ぶこともできます。

/twilio-verify-send-otp
/twilio-sms-send-message

プラグインを追加した直後にスキルが見えないときは、ディスク上の変更を取り込む/reload-skillsの手順が参考になります。

Plannerスキルは実装の前に質問する

公式スキルの特徴が出るのは、実装前の計画段階です。本人確認のtwilio-identity-verification-advisorを例にすると、依頼の具体度で動き方を変えます。

• 「サインアップに電話番号認証を足したい」のような抽象的な依頼は、DISCOVERY MODEで質問から入ります
• 「SMSでOTPを送って検証する」程度に方針が見えている依頼は、VALIDATION MODEで、不正利用・代替チャネル・レート制限を考慮済みかを確認します
• 「channel=smsでVerifyを開始する」のような具体的な依頼は、BUILD MODEでtwilio-verify-send-otpに進みます

質問は4つに絞られています。何を・いつ確認するか、どのチャネルで届くか、不正リスクの水準、利用者の分布です。回答に応じて、基本のOTP、複数チャネルとフォールバック、リスク適応型の3段階の検証から構成を勧めます。

出力形式も決まっています。推奨構成を平易な言葉で述べ、続けて参照すべきProductスキル、Setupスキル、Guardrailスキルを列挙します。コードを書く前に「どのスキルを順に使うか」が一覧で出るため、後続の実装依頼にそのまま使えます。

判断ルールには、実装を左右する強い指針が入っています。たとえば、OTPをProgrammable Messagingで自作しようとする開発者には、レート制限・コード生成・有効期限・不正対策を管理するVerifyを強く勧めます。Fraud GuardとSMSパンピング保護は、Verifyサービスごとに有効にする前提で書かれています。

ProductスキルのCANNOT節が実装の事故を減らす

twilio-verify-send-otpは273行の長いスキルで、クイックスタートがPythonとNode.jsの両方で書かれています。実装時に効くのは、末尾のCANNOT節に並ぶ制約です。Claudeが「それらしいが動かない」コードを書く典型を先回りして潰しています。

• チェックで誤ったコードを送っても例外にならず、status: "pending"が返る。approvedかどうかを明示的に判定する必要がある
• 承認済みの検証は再チェックできず、承認後に取得すると404になる
• 認証完了のWebhookはなく、verification_checksをポーリングする。呼び出しには上限がある
• WhatsAppからSMSへの自動フォールバックはあるが、SMS・音声・メールをまたぐ代替は自前で実装する

エラーコードの早見表も同梱されています。60202は確認試行の上限、60203は送信試行の上限、60212はサービスが見つからない、60410は国別の送信許可が未設定、という具合です。Claudeにエラーの調査を頼むときも、このスキルが読まれていれば原因の当たりをつけやすくなります。

スキル同士は「次のステップ」でつながります。Verifyなら、WhatsAppの送信元登録はtwilio-whatsapp-manage-senders、電話番号の事前検証はtwilio-lookup-phone-intelligence、資格情報の設定はtwilio-iam-auth-setupに案内されます。

資格情報はCLAUDE.mdで境界を決める

スキルのコード例は、環境変数TWILIO_ACCOUNT_SID・TWILIO_AUTH_TOKEN・VERIFY_SERVICE_SIDから値を読む形で書かれています。この前提を、プロジェクトのCLAUDE.mdにも明記しておくと、Claudeが認証情報をコードに直書きする事故を避けられます。次は、書き方の一例です。

## Twilioの扱い
- 認証情報は環境変数から読む。SID・トークンをコードやコミットに書かない
- 本番のアカウントSIDでの動作確認はしない。テスト用の資格情報を使う
- 送信を伴う処理は、実行前に宛先と件数を提示して確認を取る

Twilioのスキルにはtwilio-security-hardeningもあり、APIキーとAuth Tokenの使い分け、Webhookの署名検証、PCI DSSとHIPAAの要件、SMSパンピング対策、アカウント分離までを扱います。実際にメッセージを送る処理を書かせる前に、このスキルの観点で見直しを頼む運用が考えられます。

twilio-security-hardening の観点で、このリポジトリの Twilio 呼び出しを
レビューして。資格情報の持ち方と Webhook の署名検証を中心に。

使う前に知っておく制約

スキルは知識を渡すだけで、メッセージの送信や発信をClaudeに代行させる仕組みではありません。実際の送信はSDKで書いたコードが行い、課金もTwilioアカウントに発生します。ほかのベンダーのスキルを入れるときも手順は同じで、一例としてStackHawkのスキルでHawkScanを回す手順があります。スキルの標準的な扱いはバンドルスキルと組み込みコマンドの違いと合わせて読むと整理しやすくなります。

同じSKILL.md形式なので、CursorやCodexなど他のエージェントでも使えます。Cursorは.agents/skills/を自動で探し、Codexは~/.agents/skills/にコピーして使います。ただしプラグインとして一括で入るのはClaude Codeの導入手順で、他のツールではskills/ディレクトリのコピーとMCPの設定を別々に行います。

まとめ

Twilioのスキルは、APIの引き方ではなく「何を選び、何を避けるか」を渡す仕組みです。Claude Codeでは2つのコマンドで入り、MCPも一緒に付いてきます。最初の一歩は、確認用の質問を投げて、Messaging ServicesやA2Pの話が出るかを見ることです。そのうえで、実装前にPlannerスキル、実装にProductスキル、公開前にGuardrailスキルを当てる順番にすると、スキルの種類分けがそのまま作業の段取りになります。