Vobiz agent skills

Reusable skills that teach coding agents how to build with the Vobiz REST API, Voice API, VobizXML, SIP trunking, phone numbers, partner accounts, sub-accounts, WhatsApp, and AI voice integrations.

Overview

Coding agents are good at writing code and poor at guessing API contracts. Ask a general-purpose agent to "place a Vobiz call" and it will usually produce something that looks right — a plausible base URL, a plausible auth header, a plausible XML verb — and fails on the first request. Telephony makes that worse than usual, because the failure modes are expensive: a wrong number format buys the wrong DID, a fire-and-forget retry places a second billable call, and a leaked auth token is a live account.

This repository closes that gap. It packages the Vobiz platform as a set of thirteen focused skills — short, verified instruction files that an agent loads on demand. Each skill covers one domain, states the exact base URL, path casing, auth headers, request fields, and error behaviour for that domain, and tells the agent when to hand off to a different skill. A router skill (vobiz-api) sits in front and picks the right one, so the agent loads what the task needs instead of the whole platform.

The skills are consumed as an agent plugin rather than as documentation you read yourself. Install them into Codex or Claude Code and the plugin also wires up the public Vobiz documentation MCP server, so an agent can search current docs instead of relying on whatever it memorised. Alongside the skills, the repository carries repository-scoped instruction files for Cursor, Windsurf, and GitHub Copilot, so the same conventions and safeguards apply whichever agent a developer happens to be running.

It is aimed at developers building on Vobiz with an AI assistant in the loop, and at platform teams who want their agents to follow one consistent set of Vobiz conventions across a codebase. What you get at the end is an agent that reaches for the correct endpoint the first time, keeps X-Auth-ID and X-Auth-Token out of the code it writes, and asks before it does anything billable or externally visible.

What you can build with it

• Outbound voice integrations — an agent scaffolds a call flow that creates a call, serves VobizXML from an answer_url, and handles the hangup callback.
• AI voice agents on real phone numbers — wire Vapi, Retell, ElevenLabs, LiveKit, Pipecat, Bolna, Ultravox, OpenAI Realtime, or Deepgram to a Vobiz number, over a dashboard answer URL, a vendor API, or a self-hosted runtime.
• BYOC and PBX connectivity — provision trunks, SIP credentials, IP ACLs, and origination URIs, then route a DID to the trunk.
• IVR, voicemail, queues, and conferences — build declarative call flows in VobizXML with the correct verb and attribute names.
• Real-time audio pipelines — bidirectional WebSocket streaming for custom STT/TTS, live transcription, or barge-in handling.
• WhatsApp messaging and support flows — templates, campaigns, inbound webhooks, and multi-agent inbox work through the messaging API.
• Reseller and multi-tenant platforms — partner customer accounts, wallet transfers, KYC sessions, and per-customer CDR reporting.
• Plivo migrations — a guided, minimal-diff port of an existing Plivo voice app, including the XML verb rename and the webhook signature header change.

What's included

Thirteen skills live under skills/, one directory per domain, each containing a single SKILL.md with YAML frontmatter (name, description) that agent runtimes use for discovery.

Skills provide instructions, not credentials. Keep X-Auth-ID and X-Auth-Token in environment variables or a secret manager.

How it works

                      your prompt
                           │
                           ▼
                  ┌─────────────────┐
                  │    vobiz-api    │  router skill: auth, base URL,
                  │  (always first) │  path casing, error handling
                  └────────┬────────┘
                           │ routes by task
     ┌──────────┬──────────┼──────────┬──────────┬──────────┐
     ▼          ▼          ▼          ▼          ▼          ▼
  numbers    voice-     voice-xml   audio-      sip-      whatsapp
             calls                  streams    trunking      ...
     │          │          │          │          │          │
     └──────────┴──────────┴─────┬────┴──────────┴──────────┘
                                 │
                                 ▼
                    ┌────────────────────────────┐
                    │   vobiz-docs MCP server    │  live documentation
                    │  https://vobiz.ai/docs/mcp │  search
                    └────────────────────────────┘
                                 │
                                 ▼
                        generated integration

1. Your agent runtime discovers the skills from skills/*/SKILL.md, reading the name and description frontmatter to decide what is available.
2. When a prompt mentions Vobiz, vobiz-api loads first. It establishes the base URL, the auth headers, and the non-negotiable conventions.
3. Its routing table sends the agent to exactly one domain skill. Only that skill's instructions enter the context, which keeps the guidance specific and the context small.
4. If the task touches an endpoint, field, price, or limit that may have moved, the agent queries the vobiz-docs MCP server declared in .mcp.json rather than answering from memory.
5. Before anything billable or externally visible — buying or releasing a number, placing a call, sending a message, transferring balance, deleting a resource — the agent is instructed to show the target account, resource, and expected effect, and to wait for your explicit confirmation.

Repository layout

Prerequisites

Installing the skills does not require Vobiz credentials. You only need them when the agent starts making real API calls on your behalf.

How to use these skills

Codex plugin

Add the Vobiz marketplace and install the plugin:

codex plugin marketplace add vobiz-ai/Agent-Skills --ref main
codex plugin add vobiz@vobiz-plugins

Start a new Codex session after installation. The plugin loads all 13 Vobiz skills and connects to the public Vobiz documentation MCP server.

To verify the marketplace and installation:

codex plugin marketplace list
codex plugin list

Claude plugin

Add the official Vobiz marketplace and install the plugin in Claude Code:

claude plugin marketplace add vobiz-ai/Agent-Skills
claude plugin install vobiz@vobiz-plugins

The plugin includes all Vobiz skills in this repository and connects Claude to the public Vobiz documentation MCP server for current documentation search. After installation, run /reload-plugins in Claude Code.

Verify the plugin manifests before contributing changes:

claude plugin validate . --strict

You can also add https://github.com/vobiz-ai/Agent-Skills through your Claude organization's Settings → Plugins → Add plugins control.

Other coding agents

List the available skills:

npx skills add vobiz-ai/Agent-Skills --list

Install all Vobiz skills:

npx skills add vobiz-ai/Agent-Skills --all

Install the core API skills:

npx skills add vobiz-ai/Agent-Skills \
  --skill vobiz-api \
  --skill vobiz-sip-trunking \
  --skill vobiz-voice-calls \
  --skill vobiz-partner-api \
  --skill vobiz-sub-accounts

Install globally for a specific agent:

npx skills add vobiz-ai/Agent-Skills \
  --skill vobiz-api \
  --agent codex \
  --global

Driving the skills

Ask your agent for the Vobiz workflow you need. For example:

Use Vobiz to build an outbound voice call integration.
Use Vobiz to create a SIP trunk and connect an AI voice agent.
Search the current Vobiz docs for the VobizXML Gather parameters.

The core vobiz-api skill routes tasks to the relevant domain skill. The plugin's public documentation MCP connection keeps documentation searches current. Any billable or externally visible action still requires your explicit confirmation.

Naming Vobiz explicitly in the prompt is the most reliable way to trigger skill selection. If the agent starts guessing endpoints, say "use the Vobiz skills" and it will reload the router.

Agent configuration

This repository includes public, repository-scoped instructions for major coding agents:

These files route agents to the maintained skills/ content, canonical Vobiz documentation, OpenAPI definition, and MCP server. They also apply credential and confirmation safeguards to billable or externally visible operations.

Developer resources

MCP Registry

The repository includes server.json for publishing the public Vobiz documentation server to the official MCP Registry. The server uses Streamable HTTP and does not require credentials:

https://vobiz.ai/docs/mcp

Registry name:

io.github.vobiz-ai/vobiz-docs

Contributing a skill

A skill is a directory under skills/ containing exactly one SKILL.md. The directory name is the skill name and must match the name in the frontmatter.

1. Create the directory and file.

   mkdir -p skills/vobiz-<domain>
   $EDITOR skills/vobiz-<domain>/SKILL.md
   

2. Write the frontmatter. Two fields, both required. The description is what an agent runtime reads to decide whether to load the skill, so make it specific and list the operations it covers.

   ---
   name: vobiz-<domain>
   description: One sentence stating what this skill does and when to use it, naming the concrete operations it covers.
   ---
   
   # Vobiz <Domain> skill
   
   Use this when the user wants to ...
   

3. Follow the repository standards in AGENTS.md. In short: one domain per skill, active voice, exact base URLs and path casing, link to canonical documentation rather than pasting long schemas, and no production identifiers, phone numbers, or secrets in examples.

4. Verify everything you assert. Every endpoint, field, header, and XML attribute must be checked against the live documentation or the OpenAPI specification before it lands. A confident wrong instruction is worse than no instruction, because the agent will act on it.

5. Register it. Add a row to the What's included table above, and update the skill count in .github/workflows/validate.yml — CI asserts the exact number of skill directories and will fail otherwise.

6. Run the checks locally.

   npx --yes skills add . --list
   claude plugin validate . --strict
   

   The first command is what CI runs to confirm discovery. The second validates the plugin manifests.

7. Open a pull request describing the domain the skill covers and where you verified its contents.

Troubleshooting

Security notes

• Skills contain instructions, never credentials. Nothing in this repository holds a Vobiz token, and no skill asks an agent to embed one in generated code. X-Auth-ID and X-Auth-Token belong in environment variables or a secret manager, and the agent instructions say so explicitly.
• Confirmation before consequences. Every skill inherits the safeguard in AGENTS.md: show the target account, resource, and expected effect before a write, and require explicit confirmation before purchasing or releasing numbers, placing calls, sending messages, transferring balance, or deleting resources.
• No blind retries on money-moving requests. If a billable or externally visible request times out, the instructions require checking the resulting resource or transaction state before retrying, so a timeout does not become a duplicate charge or a second call to a real person.
• Public MCP server only. The vobiz-docs server declared in .mcp.json serves public documentation over Streamable HTTP and takes no credentials. Installing the plugin does not grant an agent access to your account.
• Examples stay clean. Repository standards forbid production identifiers, real phone numbers, and secrets in skill examples. Please hold contributions to the same line.
• Found a security issue? Report it privately to [email protected] rather than opening a public issue.

Roadmap

Planned improvements to this repository. Ideas and pull requests are welcome — open an issue to discuss anything here.

• Replace the hard-coded skill count in validate.yml with a manifest-driven check, so adding a skill does not require editing CI.
• Add frontmatter linting to CI — assert that every SKILL.md has name matching its directory and a non-empty description.
• Add a link checker that verifies every documentation URL referenced by a skill still resolves.
• Build an evaluation harness of routing prompts, so changes to vobiz-api can be regression-tested against the domain skill they should select.
• Publish server.json to the official MCP Registry and keep the version in step with the plugin manifests.
• Introduce versioned releases and a changelog, so installations can pin a known-good set of skills instead of tracking main.
• Broaden skill coverage as new Vobiz API surfaces ship, and add worked end-to-end recipes that chain several skills together.

Contributing

Issues and pull requests are welcome. Bug reports, corrections to an endpoint or field, and new skills are all useful — corrections most of all, since an inaccurate instruction propagates into every integration an agent writes from it.

Before opening a pull request:

npx --yes skills add . --list      # skill discovery, same as CI
claude plugin validate . --strict  # plugin manifest validation

Read AGENTS.md for the repository standards, and see Contributing a skill above if you are adding a new domain. Please keep credentials, production identifiers, and real phone numbers out of every example.

License

Released under the MIT License © Vobiz.

MIT is permissive: you may use, modify, and redistribute this code, including in closed-source commercial products, provided the copyright notice and licence text are retained. There is no warranty. If your organisation needs a different licensing arrangement, contact [email protected].

Built by Team Vobiz

Vobiz is a programmable voice and SIP-trunking platform for voice APIs, SIP trunking, and AI voice agents. This repository is built and maintained by the Vobiz team.

Maintainer: Piyush Sahoo — [email protected] · LinkedIn

Questions, or want to talk through an integration? Open an issue on this repo, or reach out directly at [email protected].

Useful links: Docs · API reference · Sign up