Skip to main content
A skill is a rule you write for one agent, in your own words. A name and two fields, no code. When should the agent use this? The trigger, in plain words: “When the lead pushes back on price.” “When they ask if we’re licensed.” Be specific, this line is how the agent knows which skill to reach for. One skill, one moment. The playbook. What the agent does when that moment lands: what to say, what never to say, how to handle the pushback after the pushback. Brief it like a sharp new rep who knows how to talk but not your business. You don’t script every word, give it the shape and the lines that matter. Write what the moment needs, up to 12,000 characters; anything longer is cut off. The agent sees only the trigger until it reaches for the skill, and then reads the playbook. An agent has three skills, each showing only its trigger. The lead says that's too expensive, and only the skill for pushing back on price opens to show its playbook. An agent has three skills, each showing only its trigger. The lead says that's too expensive, and only the skill for pushing back on price opens to show its playbook.

​
Prerequisites

  • An agent. See Quickstart.
  • One moment you want handled differently, and what “handled well” looks like.
  • For the API, a key with agents:write.

​
An example

A price objection skill:
  • When to use it: the lead says it’s too expensive, or asks for a discount.
  • Playbook: Don’t discount. Anchor on what’s included and the outcome they came for. Remind them the first consultation is free, so there’s no risk in starting. If they still hesitate, offer to book the consult.
Now, when price comes up on this agent’s calls, the agent reaches for that skill and keeps going. You never see it happen. The caller just gets a rep who handled it well. The agent decides when a skill fits, so if it ever misses the moment, sharpen the trigger (Step 2).

​
Step 1: Add it

In Skills & Tools on the agent, choose Create a Skill, fill in Name, When should the agent use this? and Playbook, and save. Or send the same fields to Create an agent skill:
name is capped at 120 characters and whenToUse at 300. Anything longer in whenToUse is truncated, so put the trigger in the first sentence.

​
Step 2: Hear it

Bring the moment up yourself. Talk to the agent in the browser and push back on price. If the agent does not reach for the skill, the trigger is too vague. If it reaches for it and says the wrong thing, the playbook is.

​
Step 3: Keep it sharp

Two habits keep skills sharp:
  • One moment per skill. Don’t fold three situations into one, split them so each trigger stays clean.
  • Say the “never.” The most useful line is often what the agent must not do. Spell it out.
Edit a skill with Update one agent skill, sending back the version you read as expectedVersion. Switch one off with enabled: false rather than deleting it, so you keep the wording. List agent skills with view=summary shows every skill on the agent in one line each, which is the quickest way to spot overlap.

​
Next steps