How to create a Skill

You will learn

How to build a fully custom skill from scratch, write a description and instructions that make Customer Agent use your skill at the right time, and test it before shoppers see it. This article also covers how to customize the skills Customer Agent comes with.

Before you begin

You’ll need:

• Customer Agent enabled
• A clear idea of what your skill should handle — the type of question, situation, or workflow
• Any tools your skill will use — either tools that come with Customer Agent or fully custom tools you’ve built

If you want Customer Agent to do something specific (look up data in your system, take an action in another platform), create the tool first or alongside your skill.

What a skill is

A skill is a scoped capability that lets Customer Agent handle a specific type of shopper request. Customer Agent comes with skills out of the box, and you can create fully custom skills from scratch.

A skill has a Title, a When to use this skill section (how Customer Agent knows this skill should handle a given request), and a How to respond section (how Customer Agent should behave once the skill is picked). You can also attach tools. The editor does not include a setting to limit a skill to a single knowledge source, such as a dedicated sizing guide.

For the underlying concepts, see the Understanding Customer Agent tools article and the Understanding skills vs. tools article.

When to create a fully custom skill

Build a fully custom skill when:

• The skills Customer Agent comes with don’t cover your use case — you have a workflow or question type Customer Agent doesn’t handle out of the box
• Your business has industry-specific behavior — specialized rules, unique product configurations, domain language
• You want a multi-step custom process — for example, a quiz, a guided troubleshooter, or a workflow that chains several tools together
• You want to use a fully custom tool — fully custom tools only do something when attached to a skill

Set it up

1. Open the Skills page

Navigate to Customer Agent > Skills, then click Create skill.

2. Add a Title

Enter a short, descriptive title like “Size Guide” or “Warranty Claim.” Choose a name that clearly identifies what the skill handles.

3. Write “When to use this skill”

When to use this skill tells Customer Agent’s router when your skill should handle a request. Use natural language. Be specific about what this skill handles and, where useful, what it does not handle. Including example shopper questions helps the router recognize matching intent.

Good examples:

Size Guide skill:

Use this skill when the shopper asks about finding the right size for apparel or footwear — including sizing charts, fit advice, and size exchanges. Example questions: “What size should I get for this dress?”, “Do your shoes run small?”, “How do I know if this will fit?”, “Can I exchange for a different size?” Do not use this skill for out-of-stock questions; those go to general support.

Vague example (avoid):

For questions about sizing and other product stuff.

The vague version doesn’t tell the router when to pick this skill over any other, and doesn’t show any concrete shopper questions it should match.

4. Write “How to respond”

How to respond tells Customer Agent how to behave once your skill is picked. Think of it as a short playbook. The field is a rich text editor — you can type freely, and you can also type / to insert specific elements (headings, lists, tools, or handoff actions).

Good “How to respond” content:

• Is specific and scoped to what this skill handles
• Describes how Customer Agent should approach the request — broken into clear topical sections (not numbered steps)
• Inserts tools via / at the point where each tool should run
• Inserts handoff actions via / where escalation applies
• Calls out what to do when data is missing or the request is out of scope

Keep it concise. Long, meandering guidance hurts performance more than it helps.

What you can insert via /:

• Formatting — Text, Heading 1/2/3, Bullet list, Numbered list. Use these to structure the instructions so they’re easy to read and edit.
• Actions — 2 handoff actions:
  • Offer to hand off — Customer Agent offers the shopper the option to connect with a human before handing off.
  • Hand off immediately — Customer Agent hands off without asking.
• Tools — The tools available to your account appear here. Insert a tool inline at the point where you want Customer Agent to use it.

5. Attach tools (optional)

If your skill needs to fetch data or take an action, attach the tools it should use in the instruction editor. A skill can use multiple tools. The “How to respond” section should tell Customer Agent when to use which tool.

1. In How to respond, type / where a tool should run and select it from the menu. Repeat for each tool you need.
2. Select an inserted tool to review its configuration. If it has configuration inputs, fill in the required values and click Save in the tool sidebar after making changes.

See the How to create a tool article for building your own.

6. Set regions (optional)

If this skill should only run in some countries, select them under Regions. A skill with regions only runs for shoppers in those regions. If Customer Agent cannot determine the shopper’s country, a region-restricted skill does not run. Leave this blank to run the skill everywhere.

For example, create separate return skills for the US and the EU, each with that market’s process. See How to set up Customer Agent for multiple countries and regions.

7. Save a draft

Complete the title, When to use this skill, and How to respond fields, then click Save as draft. This saves the skill and opens its details without making it available in live conversations.

8. Test in preview

In the skill’s details, click Preview if the right sidebar is closed. Select the Preview tab in the sidebar. Send test messages that would normally route to your skill, and check:

• Router behavior — does Customer Agent actually pick your skill for the test message? If the skill is available for the test shopper but is not selected, refine “When to use this skill.”
• Response behavior — does Customer Agent follow the steps you described in “How to respond”?
• Tools — if the skill should use a tool, does it? With the right parameters?
• Response quality — is the output what a shopper would expect?

Iterate on “When to use this skill” and “How to respond” based on what you see.

9. Publish the skill

When you’re satisfied with preview testing, click Publish in the skill’s details. It can then handle live conversations that match When to use this skill and its region settings. Later edits to a live custom skill save as a draft automatically. Test the draft and click Update to apply your changes to live conversations.

Writing a good “When to use this skill”

This is the most important field on a skill. Customer Agent uses the description, along with the skill’s name and the shopper’s request, to decide when to use the skill. A good “When to use this skill”:

• Describes what the skill handles in plain language
• Is specific enough that the router won’t pick it for unrelated requests
• Is broad enough that the router picks it for all the requests it should handle
• Calls out edge cases where useful — what this skill does not handle

Iterate with preview tests. If your skill fires when it shouldn’t, tighten “When to use this skill.” If it doesn’t fire when it should, broaden it or add examples.

Writing a good “How to respond”

This tells Customer Agent how to handle the request once the skill is picked. Good “How to respond” content:

• Is scoped to what this skill does — don’t try to cover everything
• Breaks the response into clear topical sections using headings (not numbered steps)
• Inserts tools inline at the point where each tool should run — type / and pick the tool from the menu
• Inserts handoff actions inline — type / and pick Offer to hand off or Hand off immediately where it applies
• Handles fallback cases — “If the data is missing, apologize and offer to hand off”
• Shows the shape of a good response — formatting, tone, what to include

Example (“How to respond” for a Shopify order-tracking skill):

Identify shopper and order
If the shopper isn’t signed in, let them know they’ll need to log in to locate their order. Once signed in, use the shopper’s authenticated profile for the order lookup.

Check shipment status
Use /Get Customer Orders to retrieve the shopper’s recent orders. Find the relevant order and check its status, tracking URL, and estimated delivery date when available.

Provide update
Communicate the current status clearly (e.g., Processing, Shipped, Delivered). If shipped and a tracking URL is available, provide a clickable tracking link. If order or tracking details are missing, explain what is unavailable and offer to hand off.

Customizing existing skills

You can disable a skill Customer Agent comes with from the Skills page. Open its row’s action menu and select Disable skill. This is useful if you don’t want Customer Agent handling that type of request. Select Enable skill from the same menu to turn it back on.

Editing existing skills (changing instructions, swapping tools) is coming soon. When it ships, this article will cover that flow.

Troubleshooting

Symptom: The skill never gets used.
Likely cause: The skill is not live, its regions exclude the shopper, or “When to use this skill” does not clearly describe matching requests.
Fix: For live conversations, confirm the skill is published. For preview testing, open the skill’s details so its draft is included. Check its regions and the shopper’s country. Then rewrite “When to use this skill” to be more specific and add example request types. Test with real shopper-style messages in preview.

Symptom: The skill gets used at the wrong time.
Likely cause: “When to use this skill” is too broad, or it overlaps with another skill.
Fix: Narrow “When to use this skill.” Call out what the skill does not handle. Check if another skill should handle those requests instead.

Symptom: The skill doesn’t use its tool.
Likely cause: The tool isn’t attached, or “How to respond” doesn’t insert the tool at the right step.
Fix: Confirm the tool is attached to the skill. In “How to respond,” type / and insert the tool at the step where it should run.

Symptom: The skill ignores “How to respond.”
Likely cause: “How to respond” is too long, contradictory, or unclear.
Fix: Tighten it. Remove unrelated guidance. Break it into clear topical sections with headings. Test changes in preview.

FAQ

Can a fully custom skill use the tools Customer Agent comes with?
Yes. Select from the tools available to your account in the skill editor. Connect the required integration and grant any permissions the tool needs.

How do I disable a skill?
For a skill Customer Agent comes with, use its action menu on the Skills page and select Disable skill. To turn it back on, select Enable skill. For a fully custom skill, open its details, open the Actions menu, and select Unpublish. To make it live again, click Publish.

How do I monitor how my skill is performing?
The Performance dashboard shows how often each skill is used. Open a skill’s Performance tab to see its message-volume chart and review its conversations. See Understanding the performance dashboard for details.

Can a skill run only in some countries?
Yes. Set regions on the skill. To handle the same request differently by country inside one skill, use Get Profile to check the shopper’s country. Get Profile requires an identified shopper. See How to set up Customer Agent for multiple countries and regions.

Next steps

• Build tools your skill will use
• Test your skill thoroughly in preview
• Monitor the skill’s performance after it goes live

Additional resources