Write it well
Words for people, instructions for the assistant, and how to polish both.
In 30 seconds
- People and the assistant read different files. Write each for its reader.
- Short, honest and friendly for people. Numbered and exact for the assistant.
- Test with real requests, then write each fix into the skill.
Writing it well
Every item speaks to two audiences who never read the same words. Keep them separate.
The person
Reads the files in text/. Plain, short, friendly. Says what they get. Never mentions tools, files or technical terms.
The assistant
Reads SKILL.md and tool descriptions. Exact and step by step. Says what to do, in what order, and what never to do.
Words for people
- Keep it short. A name up to 60 characters, a tagline up to 160, a description up to 2,000.
- Describe results, not mechanics. "Find the papers in your library" is right. "Calls the search tool" is not.
- Be honest about the internet. If your item goes online, say where, and set
network = "online". - Only promise what you've tried. If it needs a sign-in or a particular app, say so.
- Translate with care. The four other languages are read by real people. Ask a native speaker to look them over.
Instructions for the assistant
- Start the description with when to use the skill. Only the first 200 characters are shown to the assistant when it chooses, and it sees at most 15 skills at once.
- Keep
SKILL.mdunder about 20,000 bytes. Put long reference material in separate files in the skill's folder and say when to read them. - Number the steps.
- Say what to do when things go wrong. "If the tool says the app isn't open, tell the person to open it, then try again."
- Never invent. Tell it to use only names, numbers and units it was given, and to ask when something is missing.
- Protect people's files. Tell it never to overwrite a file the person made, to add a number to a name that's taken, and to say where it saved things.
When we tested our own skills, small things turned up: a template retyped with one colour changed, a currency added to a chart whose data had none, a file opened without being asked. Every one became a line in the instructions. Run your real requests, read what went wrong, and write the fix into the skill.
What a skill folder can hold
Text only: .md, .txt, .json, .csv, .tsv, .yaml. Nothing that runs. If your skill needs to run code, ask for the Python add-on (see below).