Skip to main content
This guide shows how to create skills using three methods: asking the agent, using the dashboard, or via API.
New to skills? Read Understanding Skills first.

​
Where Skills Live

Skills are stored in a .skills/ directory at your project root:

​
Ask the Agent

The agent has a built-in create_skill tool. Describe the workflow you want to capture:
“Create a skill for processing return requests. First verify the order exists, check if it’s within 30 days and unused, generate a return label, then send confirmation.”
To refine an existing skill:
“Update the returns skill to require photo proof for items over $100”
The agent uses update_skill_with_patch to make targeted edits.

​
From the Dashboard

  1. Go to Skills in the sidebar
  2. Click Create Skill
  3. Enter a name (lowercase, hyphens only)
  4. Write a description of when the skill should activate
  5. Add workflow steps in the body
  6. Click Save

​
From the API

See Skill Schema — API for endpoints and request formats.

​
Writing the Description

The description determines when the agent loads the skill. Be specific:
VagueSpecific
Handle ordersCheck order status, provide tracking links, explain delivery estimates
Customer supportProcess returns, explain refund timelines, generate shipping labels

​
Writing the Body

Structure the body as numbered steps. Reference the tools the agent should use: 
---
name: process-return
description: Process return requests by verifying eligibility and generating labels
---

# Process Return

## 1. Verify Order
- Use `orders.lookup` with order ID or customer email
- Confirm the order belongs to this customer

## 2. Check Eligibility
- Within 30 days of delivery
- Unused, original packaging
- Not a final-sale item

## 3. Generate Label
- Call `shipping.create_return_label`
- Save the tracking number

## 4. Confirm
- Send email with label and refund timeline (5-7 days)

​
Testing

Ask the agent a question that should trigger the skill. If it doesn’t activate:
  • Check the description matches the question type
  • Verify the name format (lowercase, no consecutive hyphens)
  • Check for validation errors in the dashboard

​
Next Steps

Skill Schema

Field definitions and validation rules

Understanding Skills

How progressive disclosure works