What a Skill Is: The SKILL.md Format

A skill is a folder with a file called SKILL.md. The file starts with a short header giving the skill a name and a description, followed by plain instructions. The agent reads the name and description of every skill it has, and loads the full instructions only when a task matches. This is called progressive loading, and it keeps the agent from carrying every instruction at once.

Because a skill is just text, you already know how to write one. If you can explain to a new hire how you do a task, you can write a skill for it.

The Parts of a Skill

• Name: short, lowercase, with hyphens.
• Description: one or two sentences saying what the skill does and when to use it. This is what the agent uses to decide, so be specific.
• Instructions: the steps, the rules, and the quality checks.
• Optional extras: templates, examples, reference files and scripts in the same folder.

A Minimal Example

Name: weekly-client-summary. Description: Writes a short weekly update for a client from project notes. Use when asked for a client update or a weekly summary. Instructions: read the notes, list what was done, what is next and what is blocked, write in plain language under 200 words, never promise dates not in the notes.

Exercise

• Pick a task you explain to people often.
• Write its name and description in the format above.
• Check the description: would an agent know exactly when to use it?
• Pass condition: a lowercase hyphenated name and a description of one or two sentences that says what it does and when to use it.