Writing good skills

Writing the skill

One skill, one behavior

Apply when deciding what a skill covers.

If it does two different things, split it in two. A skill that does one thing is easier to trigger, test and fix.

The test: Can you describe what it does in one sentence without "and"?

Write the description for the request

Apply when writing the description.

The description decides when your agent picks the skill up. Say what it does and when to use it, in a line or two, using the words your team actually says when asking for it. One phrase per kind of request is enough; a list of synonyms adds length without adding reach.

The test: Would the words someone types in a real request match the description?

End every step with a done line

Apply when writing each step.

Write the steps in order, and end each one with how the agent knows it's done. A vague step lets the agent stop early.

The test: Could someone else look at the result and agree the step is done?

Keep the main file short

Apply when the skill needs templates, field lists or long examples.

Put them in separate files in the same folder, with a line saying when to open each one. The main file stays readable, and the agent loads the extra material only when it needs it.

The test: Does every line in SKILL.md matter on every run?

Cut what changes nothing

Apply when reviewing any line.

Delete anything the agent already does on its own. Delete whole sentences rather than trimming words, and remove what's gone stale after a few runs. A skill usually gets better as it gets shorter.

The test: If you delete the line, does the agent do anything differently?

Use one word for one thing

Apply when naming anything the skill refers to.

Call it a "brief" everywhere, not a brief in one step and a summary in the next. The agent treats different words as different things.

The test: Does each thing in the skill have exactly one name?

Scripts

Put deterministic work in a script

Apply when something must come out exactly the same every time: a calculation, a file format, a lookup.

Written instructions are the weakest way to get consistent results. Ask your agent to write a script for that part and keep it in the skill's folder. The skill keeps the judgment: when to run the script and what to do with the result.

The test: Would two runs on the same input always give the same answer?

Return a result the agent can act on

Apply when a script finishes, fails or refuses.

Keep the script like a tool: one job, clear inputs, and a result that says what it did, or why it couldn't. Running it twice shouldn't do the work twice.

The test: Could the agent decide its next move from the result alone?

Say when to run a script, not how it works

Apply when the skill mentions a script.

A description of the script's insides goes stale the first time the script changes. The skill says when and why to run it; the script is the source of truth for how.

The test: If the script changes tomorrow, does the skill still read true?

Business rules

Keep the policy separate from the process

Apply when a skill or script depends on a limit, rate, deadline or who signs off on what.

Think of a store's return policy and the way staff handle a return. The policy says what's allowed: 30 days, with a receipt. The process says how to do it: check the receipt, check the date, issue the refund. You can change the policy to 60 days without retraining anyone on the process. Skills and scripts are the process. Your business rules are the policy.

Rules can go straight into a skill, and that works. The step up is to keep them in a document your team already maintains and have the skill point to it. A script takes the rule as an input and never keeps its own copy.

In a skill:

In a script:

The test: If the policy changes tomorrow, do you edit only the policy?

Getting started

1. Do the task with your agent once, on a real case.
2. Ask it to write the skill.
3. Ask it to review the draft against these principles and cut what doesn't change its behavior. Agents write long first drafts.
4. Run it on two or three different real cases. Fix what it got wrong, and make sure the skill isn't tied to the first case you used.

An example skill

---
name: client-meeting-prep
description: Prepares a one-page brief before a client meeting. Use when someone asks to prep for a client meeting.
---

1. Find the meeting in the calendar and note who's attending.
   Done when you have the date, time and every attendee's name.
2. Pull the client's notes from the CRM since the last meeting.
   Done when every note from that period is listed, or you've confirmed there are none.
3. Run holdings_summary.py with the client's account ID.
   Done when it returns a summary. If it reports a problem, put its message at the top of the brief.
4. List open items: unanswered emails, pending requests, overdue tasks.
   Done when each item has an owner and a date.
5. Check the Client Communications policy for anything that needs compliance review.
   Done when each flagged item is marked in the brief.
6. Write the brief with brief-template.md.
   Done when it fits on one page and every open item from step 4 is in it.

What it shows:

• One skill, one behavior: meeting prep, nothing else.
• Write the description for the request: "prep for a client meeting", the way the team asks.
• End every step with a done line: all six steps.
• Put deterministic work in a script: holdings_summary.py.
• Say when to run a script, not how it works: step 3 says when, and what to do with a problem.
• Keep the policy separate from the process: the Client Communications policy, pointed to, not copied.
• Keep the main file short: the template lives in its own file.

When a skill misbehaves

• Not picked up, or picked up at the wrong time: fix the description.
• Stops before the work is really done: sharpen the done line on that step.
• Inconsistent results: look for a rule stated in two places, a thing with two names, or work that should be a script.