twilio-sms
Twilio SMS CLI: buy/list/keep numbers, send/check messages, credential routing.
How do I install this agent skill?
npx skills add https://github.com/steipete/agent-scripts --skill twilio-smsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides instructions and shell commands for managing Twilio SMS services, including purchasing numbers and sending messages. It follows security best practices by explicitly instructing the agent not to leak credentials and to use secure secret management tools like 1Password.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Twilio SMS
Use for Twilio phone-number and SMS work: create/buy numbers, list owned numbers, keep/label numbers, send texts, and check inbound/outbound messages.
Safety
- Never print Account SIDs, auth tokens, API secrets, TOTP codes, or full 1Password item JSON.
- Do not store real phone numbers, SIDs, names, or account-specific item IDs in this skill.
- Use
$one-passwordfor secret reads.opstays tmux-only. - If desktop 1Password access is needed, unset service-account auth for those commands:
env -u OP_SERVICE_ACCOUNT_TOKEN op .... - Print credential shape only: field present, length, prefix class if useful.
- Public writes or logs: avoid leaking message bodies unless the user asked to read/check SMS.
Credential Route
- Check Twilio CLI/profile:
twilio --versionornpx -y twilio-cli --versiontwilio profiles:listornpx -y twilio-cli profiles:list
- Check exact env presence only:
TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKEN- optional API key/secret vars
- If only partial env exists, search 1Password metadata first.
- Prefer an item with fields matching:
TWILIO_ACCOUNT_SIDTWILIO_AUTH_TOKEN- optional
TWILIO_FROM_NUMBER
- If
oponly sees a restricted vault, retry desktop-backed reads withenv -u OP_SERVICE_ACCOUNT_TOKEN. - Verify auth before any purchase/send:
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
"https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID.json"
CLI Setup
Twilio CLI profile creation requires account auth token, not just API key creds:
npx -y twilio-cli profiles:create "$TWILIO_ACCOUNT_SID" \
--auth-token "$TWILIO_AUTH_TOKEN" \
--profile default --force --silent
npx -y twilio-cli profiles:use default
Use npx -y twilio-cli when twilio is not installed.
Numbers
List owned:
npx -y twilio-cli api:core:incoming-phone-numbers:list \
--properties phoneNumber,friendlyName,capabilities
Search US local SMS-capable inventory:
npx -y twilio-cli api:core:available-phone-numbers:local:list \
--country-code US --sms-enabled --voice-enabled --limit 5
If the CLI shape is awkward or missing flags, use REST:
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
"https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/AvailablePhoneNumbers/US/Local.json?SmsEnabled=true&VoiceEnabled=true&PageSize=5"
Buy one candidate:
curl -sS -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
-X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json" \
--data-urlencode "PhoneNumber=$PHONE_NUMBER"
Verify ownership/capabilities after purchase. Twilio JSON uses lowercase keys:
capabilities.sms
capabilities.mms
capabilities.voice
Mark numbers the user wants to keep:
npx -y twilio-cli api:core:incoming-phone-numbers:update \
--sid "$PHONE_NUMBER_SID" \
--friendly-name "KEEP - <purpose>"
Retention rule: a number is kept while it remains in the Twilio account and billing is healthy. Do not release/delete unless explicitly asked.
SMS
Send:
npx -y twilio-cli api:core:messages:create \
--from "$FROM_NUMBER" \
--to "$TO_NUMBER" \
--body "$BODY" \
-o json
Fetch status:
npx -y twilio-cli api:core:messages:fetch --sid "$MESSAGE_SID" -o json
Check inbound to a number:
npx -y twilio-cli api:core:messages:list \
--to "$NUMBER" --limit 20 -o json
Check outbound from a number:
npx -y twilio-cli api:core:messages:list \
--from "$NUMBER" --limit 20 -o json
Twilio CLI JSON can return an array for single-resource commands. Parse defensively:
jq 'if type=="array" then .[0] else . end'
Notes
- International SMS may show an alphanumeric or carrier sender instead of the purchased US number.
- US SMS can be compliance-gated. If sending to US recipients fails, check A2P/10DLC registration state before retrying blindly.
- Trial accounts may restrict recipients.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/steipete/agent-scripts/twilio-sms">View twilio-sms on skillZs</a>