Skills

A skill holds detailed steps for one kind of request, such as returns, sizing or bulk orders. The agent always sees each skill's name and when to use it, and loads the full steps only when a conversation needs them. Your always-on instructions stay short, and the agent still knows exactly what to do in the cases that need care. Skills are compatible with the SKILL.md format, so you can import and export them.

How skills work

1. On every message, the model's instructions include a ## Skills section: the name and When to use it text of each skill. Nothing else of the skill is sent.
2. When the model decides that a skill fits the conversation, it calls the built-in load_skill tool with the skill's name.
3. Peki returns the skill's Instructions, plus the list of Tools this skill uses, and the model follows them for the rest of the reply.

The model decides when to load a skill, from the When to use it text alone. That text is the most important part of a skill.

Skills used in a reply are listed in the Test panel and in the conversation's trace, so you can check that the right skill loaded.

Skills, instructions, tools and knowledge

	Instructions	Skills	Tools	Knowledge
What it is	Rules and identity	Step-by-step procedures	Actions: API calls and code	Reference documents
When the model sees it	Every message	Name and "when to use" every message; steps only when loaded	Name and description every message; result when called	Matching passages, when the message matches
Who decides	Always (or a condition)	The model	The model	Automatic search for each message
Good for	Tone, hard rules, scope	Returns flow, booking flow, troubleshooting	Order lookups, bookings, calculations	Price lists, policies, manuals, FAQs
Size	Keep short	Up to 20,000 characters each	—	Large

A simple way to decide:

• If the agent must always follow it, it's an instruction.
• If it's how to handle one kind of request, step by step, it's a skill.
• If it does something or fetches live data, it's a tool.
• If it's information to look up, it's knowledge.

Skills and tools work together: a skill often says which tool to call at which step.

Create a skill

1. Open the agent and go to Skills.
2. Below the list, click New skill.
3. Fill in Title, When to use it (the AI always sees this) and Instructions.
4. Add the tools the steps use under Tools this skill uses.
5. Click Test on the card to open the Test panel and write a message that should trigger the skill.
6. Publish. Skills are part of the draft; the Test panel uses the draft right away.

Skill settings

Setting	What it does	Limit
Title	The name people see in Peki.	Required, up to 80 characters
Name the AI calls	The name the model uses with load_skill, like returns. Filled from the title while you haven't changed it.	Lowercase letters, digits and _, starting with a letter, up to 64 characters. Unique among the agent's skills.
When to use it (the AI always sees this)	The trigger. The only part the model sees before loading.	Required, up to 500 characters
Instructions	The steps, in Markdown (SKILL.md format). Loaded only when the AI decides this skill fits the conversation.	Required, up to 20,000 characters
Tools this skill uses	Tool names shown to the model with the instructions.	Up to 30

An agent can have up to 30 skills.

Tools this skill uses

Click Add to pick from the agent's HTTP tools, plus request_human when handoff is on and web_search and read_page when web search is on. A tool that the agent doesn't have (for example, removed later) shows not on this agent.

This list is guidance for the model, not a permission. When the skill loads, the model reads "Tools for this skill: …" after the steps. The agent's other tools stay available, and the listed tools are available without the skill too.

Write a good trigger

The When to use it text decides whether the skill ever loads. Write it for the model:

• Start with the situation. "Use when the customer wants to return or exchange an item."
• Name the signals. Words and intents customers use: "return, refund, exchange, wrong size, damaged item".
• Say when not to use it if there's a close neighbour: "Not for order tracking: use order_status."
• One job per skill. Two jobs in one trigger make it fire too often or not at all. Split them.

Weak	Better
Returns	Use when the customer wants to return, exchange or get a refund for an item, including wrong size or damaged items.
Help with appointments	Use when a patient wants to book, move or cancel an appointment. Not for questions about prices.
Integration stuff	Use when a user reports that data from an integration (Shopify, Stripe, HubSpot) is missing or wrong in their dashboards.

Write the steps

The instructions are read only after the skill loads, so they can be long and precise.

• Number the steps in the order the agent should do them.
• Say what to ask, what to check and which tool to call at each step, by its exact name (order_status).
• Cover the branches: what if the order is too old, what if the tool fails, what if the customer refuses.
• End with a clear outcome: what to tell the customer, when to hand off.
• Use Markdown: headings, lists and short examples of good replies.
• Don't repeat the always-on rules. Tone and identity come from your instructions.

Import and export SKILL.md

Skills use the SKILL.md format: a frontmatter block, then the instructions in Markdown.

---
name: Returns and exchanges
description: Use when the customer wants to return, exchange or get a refund for an item.
allowed-tools: order_status, request_human
---

## Returns and exchanges
1. Ask for the order number and the reason.
2. ...

• Import SKILL.md (below the list) reads one or more .md files. name becomes the title and, in snake case, the name the AI calls (returns_and_exchanges). description becomes When to use it. allowed-tools (comma- or space-separated) becomes Tools this skill uses. Everything after the frontmatter becomes the instructions.
• If a name is already taken, Peki adds _2, _3 and so on.
• Export SKILL.md on a skill's card downloads <name>.SKILL.md, ready to share or use elsewhere.

Import errors:

Error	What to do
A SKILL.md file starts with a --- frontmatter block	Add the --- block at the very top of the file.
The frontmatter needs a description (when to use the skill)	Add a description: line.

Problems shown on the card

Message	What to do
Give it a title	Fill in Title.
The AI name may only use lowercase letters, digits and _	Fix Name the AI calls.
Another skill already uses this AI name	Pick another name.
Say when the AI should use it	Fill in When to use it.
Write the instructions	Fill in Instructions.

Test a skill

1. Click Test on the skill's card to open the Test panel.
2. Write a message the skill should handle, the way a customer would.
3. Check that the reply's Skills list shows your skill, and that the agent followed the steps.
4. Also write a message that should not trigger it, and check that the skill didn't load.

If the skill doesn't load, make the trigger more specific. If it loads too often, add when not to use it. See Testing.

tip

The Copilot checks each kind of customer question while it builds an agent and creates and tests a skill where one would help. In Analytics, topics that are often not resolved show A skill for this would help, which opens the Copilot to propose one.

Examples

Online store: returns

Setting	Value
Title	Returns and exchanges
Name the AI calls	returns
When to use it	Use when the customer wants to return, exchange or get a refund for an item, including wrong size or damaged items. Not for tracking a delivery.
Tools this skill uses	order_status, request_human

Instructions:

## Returns and exchanges

1. Ask for the order number if you don't have it, and the reason for the return.
2. Call `order_status` with the order number.
   - If the order isn't found, ask the customer to check the number. After two failed tries, hand off.
3. Check the return window: items can be returned within 30 days of delivery.
   - Older than 30 days: explain politely that the return window has passed. Offer a person if they insist.
4. Check the item:
   - Worn shoes or opened socks can't be returned, unless they are damaged.
   - Damaged or wrong item: apologise, ask for a photo, and hand off with request_human. We cover the shipping.
5. For a normal return or exchange, explain the steps:
   - Exchange for another size: free, we send the new size when the old pair arrives.
   - Refund: to the original payment method within 5 business days after we receive the item.
   - Send the link to the return form: https://yourshop.com/returns
6. End by asking if there's anything else.

Never promise a refund before the item arrives.

Dental clinic: appointment requests

Setting	Value
Title	Appointment requests
Name the AI calls	appointments
When to use it	Use when a patient wants to book, move or cancel an appointment. Not for questions about treatment prices.
Tools this skill uses	request_appointment, request_human

Instructions:

## Appointment requests

### Booking
1. Ask which treatment they need. If they don't know, offer a check-up.
2. Ask for their full name, a phone number and two preferred days.
3. Repeat the details and ask the patient to confirm.
4. Call `request_appointment`. It waits for the front desk's approval.
5. Tell the patient the clinic will call to confirm the exact time.

### Moving or cancelling
1. Ask for their name and the current appointment day.
2. Hand off with request_human and the reason "move appointment" or "cancel appointment".
3. Tell the patient the front desk will confirm.

### Urgent cases
If the patient mentions severe pain, swelling or bleeding, skip the booking steps and give the emergency number from your instructions.

SaaS support desk: missing integration data

Setting	Value
Title	Integration data missing
Name the AI calls	integration_sync
When to use it	Use when a user says data from an integration (Shopify, Stripe, HubSpot) is missing, late or wrong in their dashboards.
Tools this skill uses	workspace_status, request_human

Instructions:

## Integration data missing

1. Ask which integration and which dashboard, and since when the data looks wrong.
2. Ask for the workspace URL and call `workspace_status`.
3. Read `integrations[].last_sync` and `integrations[].error`:
   - Last sync under 1 hour ago and no error: data can take up to 1 hour to appear. Ask them to check again later.
   - Error "token_expired": tell them to reconnect it under Settings → Integrations → Reconnect.
   - Error "rate_limited": syncing resumes on its own within 24 hours.
   - Any other error, or no sync for over 24 hours: hand off with request_human, including the error text.
4. Never ask for passwords or API keys.

Related

• Instructions
• Tools
• Knowledge
• Testing
• Publishing and versions
• Copilot overview