Coding agents

Unmute ships an optional skill that teaches a supported coding assistant how to write an Unmute package. The skill carries the schema, the model catalog, the tool kinds, how to shape a prompt for speech, and what each target refuses. Install it once, then describe the agent you want in a sentence and check what comes back. Setup is quick, and talking to the agent it builds takes a bit longer. An assistant is not required. If you would rather write the YAML yourself, the quickstart is the same journey by hand, and it is the better page if you want to understand every field as you go. If your assistant is not one of the four below, you can still use Unmute: you just do not get the skill, and the rest of this site is written for you. On this page:

Set it up - one command, every assistant
Check it took - prove the skill loaded
Read this site as Markdown - the endpoints an assistant fetches
Build the salon agent - one build, start to finish
Change an existing package - a different order
Ask for more - what your request has to carry
Habits - six things that help

Set it up

You need the unmute binary. See installation. From the root of your project:

unmute skill install

  .agents/skills/unmute/
    SKILL.md                         written
    references/conversation.md       written
    references/deploy.md             written
    references/examples.md           written
    references/latency.md            written
    references/models.md             written
    references/orchestration.md      written
    references/package.md            written
    references/prompting.md          written
    references/telephony.md          written
    references/tools.md              written
    references/transfers.md          written
    references/variables.md          written
    references/workflow.md           written
  .claude/skills/unmute/
    SKILL.md                         written

Installed the Unmute skill for claude, codex, copilot, cursor.
Commit these files so your team's assistants get them too.
Next: ask your assistant to build a voice agent, in a sentence.

One command covers every assistant, because they read different directories but the same instructions. Commit both directories. Then anyone who clones the repository has an assistant that knows Unmute, with nothing to install.

Assistant	Reads
Claude Code	`.claude/skills/unmute/`
Codex	`.agents/skills/unmute/`
Cursor	`.agents/skills/unmute/`
GitHub Copilot	`.agents/skills/unmute/`

.claude/skills/unmute/SKILL.md is a pointer at the full bundle, so the instructions exist once no matter how many assistants you set up. Two assistants in the same project is fine and normal.

The skill ships inside the binary. Installing it downloads nothing and works offline. It writes only the two directories above, so if your assistant cannot run shell commands, run the command yourself in a terminal and the result is exactly the same.

Re-run it whenever you upgrade the CLI. It reports what it changed, and it refuses to overwrite a file you edited by hand unless you pass --force. Full flags are on the skill command page.

Check it took

A skill that silently did not load looks exactly like an assistant that is bad at Unmute, so prove it before you build anything. A tool is an action the voice agent can call, such as checking appointment slots or booking one. Its YAML file describes what the model may send and has exactly one execution block that says where the action runs. Ask:

In Unmute, what are the six ways a tool can run?

A correct answer names all six. Three of them say where an action runs: an HTTP webhook:, a local: Python handler in the package, and a remote mcp: server. The other three point at something that already exists. builtin: selects a tool the runtime already has by id. knowledge: is a search over a folder of your own documents. slng: is a reference to a tool the SLNG platform already hosts. A very good answer also mentions the two blocks that exist in the schema but no target emits. This question is the check because it cannot be guessed. It is a closed list out of this project’s own schema, so a model that has not read the skill either hedges or invents kinds that sound right. If you get a vague paragraph about function calling, the skill did not load. When it fails: run unmute skill install again, confirm the directory for your assistant from the table above exists, and start a new session so the assistant picks it up.

Read this site as Markdown

The skill teaches an assistant how to write a package. This section is the other half: how an assistant reads the site itself. Every page here is served as Markdown as well as HTML, so an assistant does not have to work from scraped HTML.

What	Where	Use it for
One page as Markdown	add `.md` to any page URL, for example `/start/coding-agents.md`	pointing an assistant at the one page that answers the question in front of it
The index	`/llms.txt`	letting an assistant see every page and its description, then fetch the ones it needs
The whole site	`/llms-full.txt`	one file with every page in it, for a tool that wants the lot in a single fetch

Prefer /llms.txt and then one page. It is a few kilobytes, and it lets the assistant choose. /llms-full.txt is the entire site in one file, which is hundreds of kilobytes and will crowd out the rest of a context window. Every page also carries a menu in its top right corner that copies the page as Markdown, opens the Markdown, or opens the page in a chat with ChatGPT or Claude. That is the fastest way to hand one page to an assistant that cannot fetch a URL itself.

These endpoints are the current site, so they always match what is published. The installed skill is version matched to your binary and works offline. Use the skill for how to author a package, and these endpoints when you want the page a reader would see.

Build the salon agent

This is one build, start to finish. It is the shape unmute init scaffolds: one agent, browser audio, local tools, no phone number.

Ask in a sentence

Build me a voice agent for a hair salon. It answers in the browser, greets
the caller by name, and can check appointment slots and book one.

You do not need to name files, fields, or models. The skill carries the schema. What you supply is the job.Check: before writing anything, the assistant should tell you what it is about to do. Which target, which models by vendor and role, and which channel. If it starts writing files without saying any of that, stop it and ask, because a silent choice here is one you will find out about later.

Read what it wrote

salon/
├── agent.yaml
├── instructions.md
├── targets.yaml
└── tools/
    ├── check_slots.yaml
    ├── check_slots.py
    ├── book_appointment.yaml
    └── book_appointment.py

Check three things, in this order. They take a minute and they catch most of what goes wrong.agent.yaml: is channels: what you asked for? A browser agent is web: realtime_audio and needs no phone route.instructions.md: read it out loud. It should sound like something a person says, with no bullet lists to read out, no markdown, and no raw URLs. It should also tell the model how to speak times and names. If it reads like documentation, the agent will sound like documentation.tools/*.yaml: each tool file has exactly one execution block, and the description reads as an instruction about when to call it, not as a label. Local Python handlers are fixtures until you wire them up, and the assistant should have said so.Use block-style YAML sequences in assistant-authored packages. Do not use anchors or aliases. This makes every list and task definition readable where it appears. It is a rule for assistant-written packages, not a claim that Unmute rejects other valid YAML.

Add your keys

Create salon/.env with OPENAI_API_KEY for the model that thinks and SLNG_API_KEY for the speech models. .env.local is also supported for local development. unmute dev reads your shell, then .env and .env.local in the current directory, then both files in the package directory. Later files win.Which names a package needs is not something to guess at. Every compile writes salon/build/<target>/.env.example listing the values you supply, so compile once and read that file.Check: no key, token, or phone number appears in any package file. A package carries environment variable names only, in UPPER_SNAKE, and the secrets: block in agent.yaml is where they are declared. If you find a literal value in the YAML, tell the assistant, because the compiler refuses them and it should not have written one.

Let it check its own work

unmute validate salon

The package is a directory beside you, so it is named on the command line. Inside salon you could run unmute validate with no argument and get the same result. It reports one row per target in targets.yaml, whichever ones the assistant put there.Ask the assistant to run this itself and fix what it finds. Reading a refusal is the fastest path it has, and the messages name the file and the line.Check: warnings are not errors, and they are not noise either. If validate prints one, the assistant should read it to you rather than move past it.

Talk to it

unmute dev salon

compiled salon/build/livekit
building and starting the container...

  ▸ http://localhost:8765/?agent=salon-livekit
    ctrl-c to stop  ·  logs: salon/build/livekit/dev.log

Open the link and speak. Docker has to be running, and this step is the only one that needs a network.Check: this is the check no test can do for you. Does it interrupt well? Does it say times like a person? Does it call the tool at the right moment? A green validate means the package is legal. It does not mean the agent is good, and the difference is only audible.

Change an existing package

An existing package needs a different order from a new build. Ask the assistant to keep current behavior until it has separated invalid definitions from unneeded structure:

Inspect the existing package. Read the agent, target, prompt, and loaded tool files before changing them.
Run unmute validate before editing. Save the errors and warnings as the baseline.
Fix invalid definitions. Make the package legal before changing its structure.
Simplify. Remove only structure the requested behavior does not need.
Run unmute validate again. Fix every error and report every warning.
Run unmute compile. Regenerate build/ from the corrected package.

This order matters. If validation and simplification happen together, you cannot tell whether a failure was already present or came from the rewrite.

Ask for more

The build above is one agent with two tools. Everything after it is a conversation with your assistant. What you get back depends on what your request carries. Describe required order, separate roles, and server-directed next steps in plain words. You do not need to ask for tasks or by name. The assistant should infer the smallest Unmute structure before writing files and tell you what it chose.

You want	Say	It should tell you
a tool	what it does, where the data comes from, and whether there is an HTTP endpoint already	which of the five kinds it chose, and why
an ordered workflow	which stages must happen in order and which parts are server-directed	which tasks and task groups it chose, and what context the steps share
a second agent	what each one owns, and when control moves between them	what context crosses the , and whether the handoff comes back
a phone number	inbound, outbound, or both, and which carrier you have	which route, and what that route cannot do

Ask what it decided, every time. The skill tells it to state the target, the models, the context across every handoff, and what it actually checked. If any of those is missing from the answer, ask, because a decision nobody named is a default nobody chose. Expect it to refuse things. Unmute does not support every vendor for every role on every target, and some shapes are gated on some targets. A good answer says plainly that something is not available and names what is. If your assistant invents a provider name instead, that is the failure to watch for, and it shows up as a validation error with the target named.

Habits

Six things that separate a good session from a frustrating one.

Let it run unmute validate and read the error. Guessing at a schema costs more turns than checking.
Never edit anything under build/. The next compile overwrites it. Change the package and compile again.
Name the target, or one gets picked for you. Pipecat and LiveKit both compile to a project you run, and they refuse different things.
Trust the references over what the assistant remembers, and unmute validate over both. Model memory of a fast moving schema is the single biggest source of confident wrong answers.
Ask what it decided. Structure, target, models, and the context across each task, group, or handoff. A silent default is the bug you find a week later.
Listen to the agent before you ship it. A green check is not a good call.

Where to go next

How Unmute works

What the compiler did between the package and that container.

Orchestration

Tasks, task groups, and handoffs.

Tools

The five active kinds in full.

Telephony

Put the agent on a real phone number.

Deployment

Get the agent off your laptop.

Get started

Build the agent

Best practices

Run and observe

Optimization

Deploy

Phone calls

Targets and models

Configuration files

CLI

Community

Releases

Set it up

Check it took

Read this site as Markdown

Build the salon agent

Change an existing package

Ask for more

Habits

Where to go next

How Unmute works

Orchestration

Tools

Telephony

Deployment

​Set it up

​Check it took

​Read this site as Markdown

​Build the salon agent

​Change an existing package

​Ask for more

​Habits

​Where to go next

How Unmute works

Orchestration

Tools

Telephony

Deployment

Set it up

Check it took

Read this site as Markdown

Build the salon agent

Change an existing package

Ask for more

Habits

Where to go next