Updated
How to write your own agent skill
How to write your own agent skill
The smallest useful skill is a folder with one SKILL.md inside it. Everything after that is progressive disclosure: add detail only when the skill needs it.
1. Start with the name and description
Pick a name that is lowercase, numbers, and single hyphens, and that matches the folder name. Then write a description that says what the skill does and when to use it — this is what the agent reads at startup.
---
name: weekly-status-update
description: Draft a concise weekly status update from a set of commits and notes. Use when the user asks for a weekly update, standup summary, or progress report.
---
2. Write the body as instructions
The Markdown body is the procedure. Write it as steps, in the order they happen, with the outcome of each step stated plainly.
## Steps
1. Read the commits and notes the user provides.
2. Group the work into shipped, in progress, and blocked.
3. Write three to five bullets per group, one sentence each.
4. Flag anything that needs a decision from the reader.
3. Add progressive disclosure
If a step needs more detail — a template, a full style guide, a long example — move it out of the body and into references/. The body should stay under about 500 lines.
weekly-status-update/
SKILL.md
references/
examples.md
Reference the file from the body so the agent knows to open it when it matters:
When formatting the final update, follow the template in `references/examples.md`.
4. Add scripts and assets only when they earn their place
A scripts/ folder is for executable code the skill needs — a parser, a linter, a formatter. An assets/ folder is for templates and data. If the skill is pure instructions, skip both. Empty folders add noise.
5. Test it
Run the skill against three realistic inputs: a normal case, an edge case, and something it should decline. If it misbehaves, tighten the description or the body — don't paste the fix into a chat and call it done, because that fix won't travel with the skill.
6. Share it
Because the skill is a portable folder, sharing it means handing over the folder (or a ZIP of it). It works the same for whoever receives it, on whatever runtime they use.
Where to go next
The authoring tag has more on structure and testing, and agent skills best practices covers the rules that keep a skill reliable.