Writing Skills

A well-written skill is one the agent discovers at the right moment and follows accurately. Here's how.

The description is everything

Agents read the description field in your frontmatter to decide whether to apply the skill. Be specific about what the skill does and when to use it.

Bad:

---
description: Helps with reports.
---

Good:

---
description: Generate a weekly delivery performance report in Google Sheets, including an SLA breach analysis, a lane-level breakdown, and an email summary to stakeholders.
---

Keep instructions step-by-step

Agents follow instructions better when they're numbered and concrete:

1. Ask the user which week they want the report for
2. Query the Sheets API for that week's raw data
3. Build a summary table with columns: lane, on-time %, breach count
4. Highlight lanes below 85% on-time
5. Email the result to stakeholders

Reference files, don't embed them

If your skill needs a template or reference, put it in assets/ and link to it:

Use the template at `assets/report-template.md` as the base.

Test the skill against a real prompt

Before publishing, install it locally and ask your agent to do the thing. Verify:

• The agent finds the skill from the description
• The steps are followed in order
• The output matches what you expect

Keep skills focused

One skill should do one thing. If you find yourself writing ... or if ... or for users who ..., split it into multiple skills.