# Skills (/docs/agents/voice-agents/skills)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

An agent's system prompt describes its persona. Procedures — how to take a confirmation
number, how to verify a caller, how to walk a return — either get pasted in there, where they
lengthen the persona and have to be maintained agent by agent, or they do not exist.

A **skill** is the third option: a named, self-contained procedure you switch on per agent. The
agent follows it whenever the situation it describes comes up, and it stays separate from the
persona you write.

Skills live on the **Skills** row of the **Tools & Skills** group, on the **Conversation**
step of the agent editor. The row shows which skills are on; clicking it opens the editor in a
side panel.

## Platform skills

Three skills ship with Tandem and can be switched on by name.

**collect-code** handles a spoken code: a confirmation number, order number, member ID, case
number. It asks for the code on its own, asks for a word when a letter is ambiguous ("was that M
as in Mary?"), reads the code back, and retries up to three times before falling back.

<Callout type="info">
    This improves *handling*, not recognition. Where the underlying speech recognition mishears a
    letter, the read-back-and-confirm loop is what catches it.
</Callout>

**read-back-values** covers the other direction — a value the agent says _to_ the caller, which
they have to write down or check against a screen. A voice reads `12345` as "twelve thousand three
hundred forty five", so the skill has the agent write it as "one two three four five" instead,
grouped with commas for the pauses. It covers codes and IDs, and also phone numbers, dates, times,
and dollar amounts.

The skill governs speech only. The agent still passes the original, unspaced value to your tools,
so a lookup on the code keeps working.

<Callout type="info">
    Switch this on alongside `collect-code` when the agent both takes a code and reads one back.
    `collect-code` covers its own read-back, so an agent that only collects codes does not strictly
    need both.
</Callout>

**verify-identity** confirms a caller before you disclose anything. It collects your configured
identifying details one at a time, calls your own verification tool, allows three attempts, and
then follows the failure path your system prompt names. It never tells the caller which detail
was wrong.

`verify-identity` uses a tool you have already bound to the agent under
[Tools](/docs/agents/voice-agents/tools). It does not bring one of its own. Without a
verification tool configured, the agent says it cannot confirm the account and follows the
failure path.

In a website chat, `collect-code` and `verify-identity` use chat wording. The agent takes what the
visitor typed as written: it does not ask them to spell a code or an answer, and it does not read
a value back to check it. Each still allows three attempts and follows the same failure path. `read-back-values`
applies to calls only, so it is skipped in a chat.

Each platform skill also has a **View** action, which shows its full instructions as
the agent receives them on a call. Read them there before you switch a skill on — the description on the
row is a one-line summary, and the instructions are what actually run.

## Custom skills

A custom skill is a name, a description, and instructions.

**Name** — lowercase letters, numbers, and hyphens, up to 64 characters, and it must start with a
letter or number (not a hyphen). It cannot be the name of a platform skill; use the Duplicate
action if you want to start from one.

**Description** — up to 280 characters. This is what tells the agent _when_ the skill applies, so
write it as a trigger: "Use when the caller asks to return a part." Keep it to a sentence or two.

**Instructions** — up to 8,000 characters. This is the procedure itself, and it can be much longer
than the description.

You can have up to ten platform skills enabled and ten custom skills.

<Callout type="warn">
    Keep the set you switch on tight. An agent's skills are given to it up front, which is what
    makes them reliable, but past a large combined size (roughly all three platform skills plus a
    couple of long custom ones) the agent switches to fetching them mid-call instead, and then
    whether a skill applies depends on the agent recognizing that it should go and get it. Ten long
    custom skills is not a configuration to reach for.
</Callout>

## Starting from a platform skill

Each platform skill has a **Duplicate** action. It copies the description and instructions into a
new custom skill named `<skill>-copy`, and opens it for editing.

The copy is a fork, not a replacement: the platform skill stays in the list and stays
independently switchable, and it keeps getting our updates while your copy does not. That is what
the `-copy` suffix is for — a custom skill that takes a platform skill's exact name is ignored at
call time rather than overriding it.

## Writing skills for voice

These instructions are executed by an agent talking on a phone. The format does not imply that
constraint, so it is the one most often missed.

**No tables, no bullet lists, no code blocks.** The agent will read them out loud.

**Ask for one thing at a time.** "Collect the customer's name, address, and order number" gets you
a run-on question and a partial answer. "Ask for the order number. Wait for an answer, then ask
for the postal code" gets you both.

**State retry limits in words, and say what happens when they run out.** There is no loop
construct; write the repetition into the instructions. "You get three attempts. After the
third, stop asking and offer to transfer."

**Say what to do when the caller goes off-script**, because on a phone call they will. Callers
change the subject, do not have the number in front of them, and ask why you need it. Every one of
those is a branch your instructions either cover or leave to chance.

## What skills are not

A skill is instructions, not permissions. It cannot restrict which tools the agent may call, and
an agent with a skill active still answers unrelated questions with unrelated tools, which is
usually what you want.

To constrain what an agent may _do_, use
[Steering Rules](/docs/agents/voice-agents/safety#steering-rules), which are checked before every
tool call.

## Reserved names

`skills` is reserved — it is the name the agent uses to fetch a skill's instructions when it has
to fetch them — so you cannot name a workflow or integration tool `skills`. Every other name the
platform's own tools answer to is reserved the same way — `end_call`, `search_knowledge_base`, and
each of the [built-in tools](/docs/agents/voice-agents/built-in-tools). See
[Tools](/docs/agents/voice-agents/tools#limits-and-defaults) for the full list.

## Over the API

Skills are part of an agent's configuration, under `skills.builtins` (platform skill names) and
`skills.custom`. `GET /v1/agent-media/skills` lists the platform catalog with each skill's full
instructions, which is what the View and Duplicate actions read. See the
[API reference](/docs/api/voice-agents/skills/listPlatformSkills).

## Next steps

<Cards>
    <Card
        title="Safety"
        href="/docs/agents/voice-agents/safety"
        description="Constrain which tool calls the agent may make."
    />
    <Card
        title="Tools"
        href="/docs/agents/voice-agents/tools"
        description="Bind the tool verify-identity checks a caller against."
    />
</Cards>