Best practices for writing skillsUpdated 10 hours ago

A skill tells AI Agent how to handle one type of conversation every time it comes up. The clearer your instructions, the more reliably AI Agent follows them. This article covers how to choose which conversations to cover and how to write skills, so AI Agent can act with confidence.

For the steps to build a skill, see create a new skill for AI Agent. This article is about writing them well.

In this article, you'll learn:

Choose which conversations to cover

Start with the conversations that matter most. A few ways to find them:

Cover your highest-volume requests first. In AI Agent, go to Skills > View intents to see the conversation types Gorgias detects and how much volume each one carries. Build skills for your top requests, like returns, order status, and cancellations.
Look at where AI Agent struggles. A skill with a high handover rate, or a high-volume intent with no skill, is a sign that a new or sharper skill would help. See how your skills and knowledge are performing.
Convert procedural guidance you already have. If you've written a guidance as a step-by-step procedure for one type of request, like a returns process, it belongs in a skill. Convert it into a skill instead of starting over. See convert guidance to a skill.

Each skill should cover one type of request. Keeping skills focused makes them easier to write, test, and improve, and it keeps AI Agent's behavior predictable.

Write clear instructions

Instructions are the steps AI Agent follows when a skill is triggered. The simpler and more complete they are, the more accurate AI Agent will be. If your instructions would confuse a new teammate, they'll confuse AI Agent too.

A few principles make a big difference:

Give every path a resolution. Spell out what AI Agent should do in each case, so it has a predictable outcome rather than guessing.

✅ When a shopper reports a shipping delay, acknowledge the delay and share the latest tracking status. If they ask for a refund, hand the conversation to your team.
❌ Complaints about shipping delays should be handled by a human.

Tell AI Agent what to do, not what to avoid. Positive, step-by-step instructions are easier to follow than prohibitions.

✅ When a shopper sends a complaint, apologize, ask for an order number, and offer a replacement or refund.
❌ Don't reply to complaints.

Set boundaries. Tell AI Agent what it shouldn't say or promise, so it stays within your policies. For example, don't promise a specific delivery date, or don't commit to a refund before a returned item arrives. Setting clear limits is different from listing don'ts: you're still telling AI Agent how to handle the request, while keeping it from over-promising.

Use WHEN, IF, and THEN to lay out the logic. Describe the situation, the conditions, and the steps AI Agent should take.

✅ WHEN a shopper asks to return an order:
- IF the order was placed 15 days ago or less, THEN tell them they're eligible, send the return portal link, and explain they'll get a prepaid label by email.
- IF the order was placed more than 15 days ago, THEN tell them it's outside the return window.
❌ When a shopper asks for a return, they're eligible if the order is 15 days old or less, send them the portal and a label, otherwise they're not eligible.

Name your audience. If a step applies to a specific group, say so, and use variables like a shopper's tags or order details to make it specific (for example, all shoppers versus shoppers with a [VIP] tag).

Reference actions in context. If a skill uses an action to do something in your connected apps, reference it at the exact step where AI Agent should use it, so the surrounding instructions explain when and why. For example: THEN confirm the return is eligible, and send the shopper a link to the returns portal. [Send return portal link]

Explain your terms. Spell out acronyms the first time you use them, and define anything specific to your brand, so AI Agent interprets it the way you mean.

Keep it focused. Cover the cases that matter, then stop. Very long or deeply nested instructions are harder for AI Agent to follow reliably. If a skill keeps growing, it's often a sign it's trying to handle more than one type of request, and would work better split into separate skills.

Format for clarity

AI Agent reads structure the way a person does. Well-formatted instructions are easier to follow than a wall of text.

Break steps into bullet points or a numbered list.
Use bold text to highlight key conditions or outcomes.
Keep each step to one action.
Group related steps under the condition they apply to — for example, under each IF branch in your instructions.

What a skill can't do

Some things can't be done from a skill's instructions alone. If a skill isn't behaving the way you expect, check whether you're asking the instructions to do something they can't, and reach for the right tool instead:

Ticket actions like leaving an internal note, delaying a reply, assigning a ticket, or applying a tag. Use rules for these. (A skill can still hand a conversation to your team.)
Tone of voice. AI Agent applies your brand voice automatically from your tone of voice settings, so you don't need to describe how to sound in a skill.
Tasks in your other tools, like creating a return or canceling an order. A skill can do these, but not from instructions alone, it needs an action. Create the action, then reference it in your skill so AI Agent runs it at the right step. See [create an action to connect AI Agent to other apps] and add an action to a skill.
Sending macros. A skill can't send a macro. If your team uses a macro to resolve a request, write the relevant information into the skill's instructions instead.

Test and troubleshoot a skill

Before you rely on a skill, test it. Send AI Agent a message that should trigger the skill and confirm it responds the way you intend. See preview AI Agent responses with test conversations.

If a skill isn't working as expected:

It doesn't trigger. Check the intents linked to the skill. AI Agent runs a skill only when it detects one of its intents, so the conversation type you're testing needs to be linked.
It gives an incomplete or wrong answer. Look for a gap or an ambiguous step in the instructions. Make sure every condition has a clear resolution.
It ignores part of your instructions. Check the formatting. Long paragraphs are easy to misread; break them into steps.
It won't take an action. Confirm you've created the action and referenced it at the right step in the skill's instructions. See [create an action to connect AI Agent to other apps] and add an action to a skill.

Next steps

Create a new skill for AI Agent — the steps to build a skill
Skills explained — what a skill is and how it works
See how your skills and knowledge are performing — find which skills need attention

Was this article helpful?

Yes