How to Build a Claude Code Skill That Makes Phone Calls

A Claude Code skill is a markdown file Claude reads at runtime to decide when and how to do something. The Anthropic docs place personal skills at ~/.claude/skills/<skill-name>/SKILL.md and project skills at .claude/skills/<skill-name>/SKILL.md. There is no SDK and no build step. You write instructions, frontmatter, and a description, and Claude loads the skill automatically when the description matches what the user asked for.

That model fits phone calling well, because most of the agent’s work is judgment, not code. A SKILL.md is good at questions like these, and a generic HTTP tool wrapper is bad at them:

• Should we place this call, or did the user just ask a question about a phone number?
• Is this an emergency line we should refuse?
• Do we need call evidence back, or only confirmation that the call happened?

The dialing itself is a fixed contract: a POST that returns a call ID immediately, and a GET that returns captured transcript evidence when present once the call finalizes. You do not want Claude inventing telephony; you want it picking up a phone that already works. That split is the whole pattern: markdown for judgment, REST for the boring part, and a stable provider contract so the skill keeps working as models change.

Your skill is only as good as the API behind it, so settle the backend first. The realistic options fall into three buckets:

1. Developer voice platforms (Bland, Vapi, Retell, Synthflow, Vocode, Regal) give you raw infrastructure for building voice products. They are powerful but sell construction-kit primitives priced per minute, and you end up writing the orchestration, IVR navigation, hold handling, and cleanup yourself. That is a months-long project, not an afternoon.
2. Agent phone-number services (AgentPhone, AgentLine, and Bland’s Agent Phone Plan) give your agent its own number behind an API, billed per minute or per month. They fit when the agent must receive calls and texts, and you still design what the agent says on the call.
3. Finished calling products with a public API handle the call end to end and let your skill stay small. ClawCall sits here, with hosted MCP, a REST API, and a published skill.

This tutorial uses ClawCall because the reference skill is already published, the REST contract is stable, and the free trial of 30 calls and 30 minutes, whichever lasts later, covers your development testing. The same SKILL.md pattern works against any backend with a similar fire-and-poll API; with a lower-level backend, you spend the time saved on the skill writing glue code instead.

Before you write your own SKILL.md, install an existing reference skill so you have a working example to study. From your project directory, drop the skill folder into .claude/skills/clawcall/, which puts SKILL.md alongside any helper files the skill needs.

Open it and read the frontmatter first: name, description, and any allowed-tools list. The description is the most important field in the file. Claude does not parse your skill on every turn. It scans descriptions, decides whether yours is relevant, and only then loads the body. A vague description like makes phone calls gets ignored when the user says “call my dentist and reschedule.” A precise one like Place outbound US phone calls on the user's behalf, navigate phone trees, wait on hold, and return captured transcript evidence when present fires when it should.

Read the body next. ClawCall’s published skill is deliberately short. It tells Claude to fetch the current API guides from the server before each operation, where to keep credentials, and which boundaries it must hold: not collecting the recipient’s own sensitive data, AI disclosure, and no bulk or robocall-style promotions. Individual outreach calls are allowed. The endpoint details live in the fetched guides rather than the skill, so the skill keeps working as the API evolves. Rules like these belong inside the skill because they are not preferences; they are constraints the agent must honor however the user phrased the request. The reference skill is at /for-agents and the API contract at /docs.

Now write your own. Create .claude/skills/phone-calls/SKILL.md with YAML frontmatter that gives the skill a name, a one-sentence description written for retrieval, and an allowed-tools list scoped to the bash or fetch tools it needs. Then build the body in this order:

1. Charter. One paragraph: what the skill does, who the user is, what counts as in scope.
2. When to invoke. Concrete triggers in the user’s words (“call this number,” “schedule an appointment by phone,” “sit on hold for me”) and concrete non-triggers (“look up this phone number,” “find the support line for X”; those are searches, not calls).
3. API contract. Document POST /call with the JSON body the API expects (to, task, an optional voice, and optionally loop_in_user for a live handoff to the user’s verified phone), the response shape (call_id, plus an auto-issued proto-key on a first anonymous call that the skill should save), and the polling loop against GET /call/:id. Say that lifecycle moves through queued, dialing, answered, and finalized, and that talk_seconds is the single duration field.
4. Hard rules and an example. Close with the rules and a short example transcript so Claude knows what a finalized response looks like.

Aim for 150 to 400 lines. Longer skills get partially ignored; shorter ones miss edge cases. Write it like a runbook for a junior teammate, not API documentation.

Every phone-calling skill runs the same three-step loop, and it is worth pinning down in SKILL.md so Claude does not improvise:

1. POST /call with the destination number in E.164 format (+1 NANP only; it is the only region the API supports today), a natural-language task, and a voice: eric (the default), jessica, sarah, or chris. The response comes back immediately with a call_id. On the very first call from a new caller without an X-Api-Key header, it also includes an auto-issued proto-key the skill should save so later requests authenticate. That key survives sign-up via linking, so the agent can start anonymous and graduate to a real account without losing its identity.
2. Poll GET /call/:id. Sleep two to five seconds per poll, tell the user about each lifecycle change, and stop once lifecycle is finalized.
3. Read the result. The finalized response includes outcome plus nullable transcript and recording_url fields. Read captured turns only when present, and offer temporary recording access only when available.

A loop-in adds a fourth step. When the call was placed with loop_in_user set to true and the agent decides to bring the person in, it calls the loop_in_user tool, which calls the user’s verified phone and connects them once they accept. Every plan allows one outbound call at a time per account. Trial and Unlimited calls use shared lines. A second call while one is running returns concurrent_call_limit. Wait for the current call to finalize before placing the next. If all shared lines are busy with other accounts, number_pool_exhausted means you can retry shortly. Unlimited Reserve and Reserve Plus calls always use your reserved number, one call at a time. On shared-pool calls, looping you in uses a second shared line while connected. Document this loop once and Claude will not need a second tutorial.

The best test for a phone-calling skill is a task you would actually delegate to a human assistant. Open Claude Code in a fresh terminal and type:

Sample taskCall my dentist at +1-555-0123 and ask whether they have any cleaning slots before Friday at 5pm. If they do, book the earliest one under my name.

If your skill description is right, Claude loads the skill, turns the request into a structured task, places the call, polls until finalized, and returns the booked time plus captured transcript evidence when present. Then check what Claude did between turns:

• Did it ask for missing information (your name, your insurance) before dialing? It should. The SKILL.md should tell it to gather everything the receptionist will ask before committing to the call.
• Did it disclose it is an AI when the receptionist asked? It must. That is a hard rule, not a preference.
• Did it handle voicemail as instructed, leaving a concise message when the task asked for one and reporting the result when it did not? It should.

Run a half-dozen variants: a restaurant reservation, a hold with a utility company, an airline rebooking, a doctor’s office. Each shakes loose a different edge case. Add the lessons back into the skill body as short examples; showing Claude a constraint inline works better than describing it abstractly at the top. For realistic examples, see Hold For Me and restaurant reservations.

Know where your skill fits so you do not aim it at the wrong job:

• Built-in phone features like Apple Hold Assist and Google Hold for Me hold the line and ring you when a person picks up, but they cannot negotiate, book, or dispute anything, and there is no API to drive them from a coding agent.
• Consumer calling apps such as Google’s Gemini Call for Me and HoldForMe.ai are built for a person in an app, not as an API a SKILL.md can call.
• Agent phone-number services (AgentPhone, AgentLine) give the agent its own number and leave the conversation design to you.
• Developer voice platforms (Bland, Vapi, Retell, Synthflow, Vocode, Regal) give you full control of the voice stack but bill per minute and expect you to build a product around them. That is right if you are shipping a voice product, and overkill if you just want your agent to make a call.
• Inbound AI receptionists (Goodcall, Rosie, Numa, Replicant) answer your business’s incoming calls, the opposite direction from what a calling skill needs.

ClawCall keeps coming up as the worked example for a narrow reason. It publishes hosted MCP, a stable outbound REST API, and a packaged Claude Code skill, with flat pricing (Unlimited at $4.99/mo, Unlimited Reserve at $8.99/mo, Unlimited Reserve Plus at $14.99/mo), and the free trial of 30 calls and 30 minutes, whichever lasts later, covers your build. See ClawCall vs Bland and pricing for the full comparison.

A working skill is the start, not the finish. Four additions pay off:

1. An escalation rule. If the call finalizes but the captured evidence does not show the task succeeded, what should the agent do? Retry once with a different opening, hand control back to the user with a summary, or surface the recording when one is available? Pick one default and put it in SKILL.md so behavior is predictable across runs.
2. Task templates for the calls you make most. A dentist-rescheduling template that already asks for the patient’s name and date of birth saves rewriting the prompt each time, and a utility-billing template that asks for the account number cuts the load on the user.
3. A logging hook. The finalized response exposes nullable transcript and recording_url fields. If transcript is present, save the captured evidence; if recording_url is present, download the recording before its temporary access expires. ClawCall deletes transcripts 7 days after a call ends and recordings 10 minutes after a call ends, and a call can finish without a transcript.
4. Sharing. The Claude Code skills ecosystem is young, and a calling skill that discloses it is an AI, leaves voicemail only when instructed, and respects a do-not-call list would be a useful addition to whichever marketplace you publish to.

The CC BY 4.0 license on the underlying docs means you can lift the API contract and rules into your own skill verbatim, as long as you credit the source.