A Quality Checklist for Skills

Good authoring guidance for skills is published by the makers of the products that load them. Its core ideas hold up for any agent that loads skills, and they give you a way to judge your own.

What the Guidance Emphasizes

• Be concise. A skill shares the context window with everything else, so only add what the agent doesn't already know. Ask of each paragraph whether it earns its place.
• Match freedom to fragility. Give text guidance where several approaches are fine, a template where a pattern matters, and an exact script where one wrong step breaks things.
• Write a clear description. The agent picks skills by name and description, so say what the skill does and when to use it.
• Load in layers. Keep the main file short and point to extra files that are read only when needed.
• Test with real tasks, and watch what the agent does. Fix the skill from what you see.

A Worked Example

A skill for invoicing reminders opens with three paragraphs explaining what invoices are. The reviewer deletes all three, because the agent knows. The remaining skill is a 20-line procedure, a tone example and a short list of what never to say. The description changes from 'Helps with invoices' to 'Drafts polite overdue-invoice reminders from a client name and amount. Use when asked to chase a payment.'

Common Mistakes

• Explaining basics the agent already knows.
• A vague description, so the skill is never picked.
• No test on a real task before you rely on it.

Exercise

• Review one of your skills with the five points.
• Cut anything the agent already knows and rewrite the description so a stranger could tell when to use it.
• Pass condition: a revised skill with a shorter body and a description that says what it does and when to use it.