Skip to content
Get packs

Guide · Agent skill

How to use the Twilio SMS agent skill: numbers and messages

Updated · written with AI from the project's own documentation and checked against our catalogue data

The twilio-sms skill is a set of instructions and commands that teaches an AI agent how to manage Twilio phone numbers and text messages on your behalf. It is for developers who send SMS notifications or two-way texts through Twilio, and for operators who need to check whether a number sent or received messages. After this guide you will know how to install the skill, what it can and cannot do, how to phrase requests, and which safety rules it follows.

Twilio SMS Numbers and Messagessteipete/agent-scripts · MIT

Quick start

  1. 1Download and unzip. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or into .claude/skills/ inside your project.
  2. 2Set up credentials. Provide your Twilio account SID and auth token through the 1Password CLI with the $one-password skill, or as the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN environment variables.
  3. 3Confirm the tools are available. Make sure curl and jq are installed, and that either the twilio command or Node.js for npx -y twilio-cli is available.
  4. 4Ask a read-only question first. Start with a request such as listing the numbers on your account, so you can confirm the connection works before any purchase or send.
  5. 5Make actions explicit. When you want a purchase, a label or a text sent, say so directly and name the number or recipient involved.

What the twilio-sms skill makes the agent do

Once installed, the agent knows how to handle routine Twilio work for text messaging. It can list the phone numbers already on your account, search US local inventory for numbers with SMS and voice enabled, buy a chosen number, and mark numbers you want to keep with a label.

It can also send SMS messages from one of your numbers and check the status of inbound and outbound texts. The skill says it should verify credentials before any purchase or send.

  • List numbers you own
  • Search US local numbers that support SMS
  • Buy one candidate number
  • Mark numbers to keep
  • Send SMS messages
  • Check inbound and outbound message status

How do you install the twilio-sms skill?

Download the ZIP for the skill from this page. Unzip it into one of two places: ~/.claude/skills/ to make it available across your projects, or the .claude/skills/ folder inside a specific project to limit it to that project.

If you use the Claude apps instead of files on disk, open Settings, go to Capabilities, then Skills, and upload the skill there.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into .claude/skills/ in your project
  • Claude apps: Settings, then Capabilities, then Skills, then upload

What do you need before the skill works?

The skill assumes a Twilio account with an account SID and auth token. The Twilio CLI is preferred, but the skill can also run it through Node.js with npx -y twilio-cli when twilio is not installed. You also need curl and jq on the command line.

For secrets, the skill is built around the 1Password CLI (op) together with the $one-password skill. Alternatively, you can set the environment variables TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN. The credential routing will not work without one of these setups.

  • Twilio account with account SID and auth token
  • Twilio CLI, or Node.js for npx -y twilio-cli
  • curl and jq
  • 1Password CLI (op) with the $one-password skill, or the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN environment variables
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \ "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"

How do you ask the agent to use the skill?

You do not need a special command. Describe the task in plain language about Twilio numbers or SMS, and the agent will pick up the skill when the request matches what it covers. The skill is for phone-number and SMS work, so requests about Twilio texting are the right trigger.

Be specific about the outcome you want, and state whether you only want a check or an action. Requests to buy, send or label something are actions that cost money or reach real people, so the agent should treat them with more care.

  • Find five US local numbers that support SMS and voice
  • Show the numbers on my Twilio account
  • Mark this number as KEEP for the support line
  • Send a test text from my number to this recipient
  • Check whether messages arrived at my number in the last 20 messages
  • Check the status of message SID X

How do number and message tasks work?

For numbers, the skill lists owned numbers, searches available US local numbers filtered for SMS and voice, and buys a candidate with a POST request to the Twilio API. After a purchase it checks capabilities such as sms, mms and voice. Numbers you want to keep are updated with a friendly name beginning with KEEP.

For messages, the skill sends a text with a from number, a to number and a body, fetches a message by its SID, and lists messages sent to or from a number. Twilio JSON uses lowercase keys, and the skill parses output defensively in case a single result comes back as an array.

  • Retention: a number stays while it remains in the account and billing is healthy
  • The skill does not release or delete numbers unless you explicitly ask
  • If the CLI lacks a flag, the skill falls back to the REST API with curl
npx -y twilio-cli api:core:messages:list \ --to "$NUMBER" --limit 20 -o json

What safety rules does the skill follow?

The skill tells the agent never to print account SIDs, auth tokens, API secrets, TOTP codes or full 1Password item JSON. It also says not to store real phone numbers, SIDs, names or account-specific item IDs inside the skill itself. Credentials are checked for presence and shape only, such as length or prefix class.

Message bodies are kept out of output unless you ask to read or check SMS. The skill lists scripts and network access as part of what it does: it runs commands and calls the Twilio API at api.twilio.com, so review the commands before running them on an account with real money at stake.

  • Secrets are never printed in full
  • Message bodies stay private unless you ask to read them
  • Numbers are not released or deleted without an explicit request
  • The skill runs scripts and uses the network

What limits should you know about?

International messages may show an alphanumeric or carrier sender instead of your purchased US number. US messages can be gated by compliance rules: if sends to US recipients fail, check A2P/10DLC registration before retrying. Trial accounts may restrict which recipients you can text.

Check authentication first when something fails. The skill verifies credentials before any purchase or send, so an auth failure is the first thing to rule out.

  • International senders may differ from your number
  • US sending can require A2P/10DLC registration
  • Trial accounts may restrict recipients
  • Verify auth before retrying a failed purchase or send

What people use it for

  • Searching for a US local number that supports SMS and voice, then buying one after you approve it
  • Labelling numbers you want to keep so they are easy to identify later
  • Sending a notification text from an application number and checking its delivery status by message SID
  • Reviewing the last 20 messages received by a support number to see whether customers are texting it

Frequently asked questions

How do I install the twilio-sms skill?

Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, you can instead upload it under Settings, then Capabilities, then Skills.

What do I need to use the twilio-sms skill?

You need a Twilio account with an account SID and auth token, curl and jq, and either the Twilio CLI or Node.js to run npx -y twilio-cli. You also need the 1Password CLI with the $one-password skill, or the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN environment variables.

Is the twilio-sms skill free?

The skill is listed under the MIT licence. Twilio itself is a paid service, and the skill source does not state prices, so check Twilio's own pricing for numbers and messages before buying or sending.

Can the agent delete or release my Twilio numbers?

The skill says not to release or delete numbers unless you explicitly ask it to. It treats a number as kept while it stays in your account and billing is healthy. A mistaken purchase or send can still cost money, so review requests before confirming.

Why does my text fail to send to US numbers?

US messaging can be compliance-gated. The skill advises checking A2P/10DLC registration state before retrying. Trial accounts may also restrict which recipients you can text.

Does the skill work without 1Password?

Yes, if you set the TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN environment variables instead. The credential routing in the skill is built around 1Password, so without either setup it will not work as described.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run Twilio for SMS and want an agent to handle routine number lookups, purchases, labels and message checks, with the safety rules built in. Pick something else if you do not have a Twilio account, do not use 1Password or environment variables for secrets, or want an agent that can release numbers or send texts without you reviewing each action.

Download the skill