The idea
A skill is a folder with a SKILL.md file (a name, a one-line description of when to use it, and step-by-step instructions) plus optional scripts, templates and reference files. The agent sees only the short descriptions at first.
When a task matches a description, the agent reads the full SKILL.md and any files it points to. This is progressive disclosure: lots of know-how available, little of it in context at once.
Skills package team knowledge: how to make a report in house style, how to run the release checklist, how to query the analytics warehouse. They are easy to version and share because they are just files.
Skills let agents do specialised work reliably without stuffing every instruction into one giant system prompt.
Words to know
- Progressive disclosureLoad detail only when it is needed.
Try it without code
Write a skill on paper
- Pick a task you repeat weekly.
- Write its SKILL.md: name, when to use, steps, and the scripts it needs.
Use it in code
A minimal skill folder: skills/weekly-report/SKILL.md
---
name: weekly-report
description: Use when asked for the weekly engineering report. Produces a Markdown report from the metrics CSV.
---
# Weekly report
1. Run scripts/fetch_metrics.py to write metrics.csv for the last 7 days.
2. Compute week-over-week change for deploys, incidents and p95 latency.
3. Write the report using templates/report.md. Keep it under 300 words.
4. Flag any metric that moved more than 20% in a "Needs attention" section.Implement a loader that lists skill descriptions in the system prompt and gives the agent a read_skill(name) tool.
Common mistakes
- Descriptions too vague to trigger at the right time.
- Huge skills that should be split.