Write good skills
A skill only helps if the model loads it at the right moment and then follows it. Both depend on how you write it: the description decides when it is loaded, and SKILL.md decides what happens next. This page collects practical advice for both, plus how to test a skill before you rely on it.
The description decides when it loads
The model sees only each skill’s name and description until it chooses to open one. A good description covers what the skill does and the requests that should trigger it:
| Weak | Strong |
|---|---|
Finance helper. | Build the monthly finance pack (P&L, cash flow, variance commentary) from a ledger CSV export. Use when asked for month-end reporting, a finance pack, or management accounts. |
Brand guidelines. | Apply Northwind's brand rules to slides and documents: colours, fonts, logo placement and tone. Use whenever creating or editing customer-facing slides, one-pagers or proposals. |
Mention the file types, words users actually say, and the output it produces. Avoid overlap between skills; two skills that both claim “reports” leave the model guessing.
Keep SKILL.md short and procedural
SKILL.md is read into the context when the skill loads, so every line costs tokens on every use. Aim for one to three screens:
- Purpose in a sentence.
- Steps as a numbered list, each one an action.
- Checks to run before declaring the task done.
- Pointers to scripts, templates and reference files, with when to use each.
Move long material (style guides, tables, examples) into separate files under reference/ and tell the model when to open them. It reads them only when needed.
---
name: finance-pack
description: Build the monthly finance pack from a ledger CSV export. Use when asked for month-end reporting, a finance pack or management accounts.
---
1. Load the ledger CSV from /mnt/input. If there is more than one, ask which month.
2. Run `python scripts/build_pack.py <csv> /mnt/out/pack.xlsx`.
3. Read /mnt/out/summary.json and write three to five sentences of variance commentary.
Follow reference/commentary-style.md for tone.
4. Check: totals in the pack equal the ledger totals in summary.json. If not, stop and report the difference.Put exact work in scripts
Anything that must be exactly right every time (calculations, file conversions, formatting a spreadsheet) belongs in a script the skill runs, not in instructions the model follows by hand. The model then does what it is good at: deciding what to run, reading the results, and writing the explanation.
- Make scripts print a short, structured summary (JSON is ideal) that the model can read.
- Fail loudly with a clear message when inputs are wrong; the model will relay or fix it.
- Keep dependencies to what the environment provides, or list them so the environment can install them.
Version deliberately
Every upload produces another version, and versions never change afterwards. Pin agents in production to a version number and move the pin after testing, rather than relying on latest. Keep the skill’s source in version control and build the ZIP in CI, so a version number maps to a commit.
Test before you rely on it
| Test | Passes when |
|---|---|
| Trigger | Requests that should use the skill load it; unrelated requests do not. |
| Procedure | The steps run in order and the checks are executed. |
| Edge cases | Missing input, two candidate files, malformed data: the skill asks or stops cleanly. |
| Cost | Loading the skill adds a predictable number of input tokens; check usage. |
Run the same scenarios on each new version before moving the pin. See Test your prompts; the same approach applies.
Skills can contain code that runs in your environment. Review scripts from others before uploading them, and keep network access off unless the skill truly needs it.