Every team has procedures that live in someone's head: how refunds over a certain amount get approved, which template a renewal email uses, what to check before a release. An agent can't follow what nobody wrote down. Skills are how you write it down once, for every agent that needs it.
What a skill is
A skill is a folder with a SKILL.md file that teaches one procedure, plus any scripts and reference files the procedure needs. The top of the file names the skill and says when to use it. The rest is the procedure itself, in plain words.
---
name: refund-requests
description: How we handle refund requests. Use when a customer asks for money back on an order.
---
# Refund requests
1. Look up the order and check it was paid in the last 30 days.
2. Refunds up to $200: issue them and reply with the template below.
3. Anything larger: ask for approval in #support-leads first.The description can run to 1,024 characters. Make it say plainly when the skill applies, because that's what the agent reads to decide.
Four ways to make one
- Upload a folder you already have.
- Write it in the editor in the console.
- Paste a GitHub link to a skill in a repository.
- Ask Definable to write it. Describe the procedure and it drafts the whole skill, then shows it to you on an approval card before anything is saved.
The catalog also carries the open skills published on skills.sh, ready to add.
Costs almost nothing until it's used
A long playbook in an agent's instructions costs tokens on every message, used or not. A skill doesn't. The agent's prompt lists only each skill's name and description, about 120 tokens a skill. When a task matches, the agent reads the full skill, and only then.
With the sandbox on, the skill's folder is copied into the agent's workspace too, so its scripts can run.
The owner decides
A skill reaches an agent only when that agent's owner says yes. For a skill from the open catalog, which comes from outside your team, the owner also sees what five independent security scanners found in it.
Publishing an agent freezes the skill version it uses, so a skill edited later can't change a live agent behind your back. A newer version shows as Update available until the owner takes it.
Start with one
Pick the procedure people ask about most, the one that gets explained in chat every week, and write it as a skill. Then watch a run's trace: you'll see the moment the agent reads it.