How to create an Agent Skill

Creating an Agent Skill is straightforward: make a folder, write a SKILL.md, and refine the description until it activates when you want it to. This guide is a deterministic walkthrough you can follow exactly. For the file format in depth, see the SKILL.md guide; for the concepts, What are AI Agent Skills?.

The official specification is the source of truth for format details.

1. Create the directory

Create a folder named after what the skill does. Use a short, lowercase, stable identifier:

mkdir release-notes-skill
cd release-notes-skill

2. Create SKILL.md

Add a SKILL.md file. This is the only required file.

touch SKILL.md

3. Write the name

At the top, add frontmatter with a name:

---
name: release-notes
---

4. Write an activation-focused description

The description is the most important thing you will write, because it decides when the skill loads. State what it does and when to use it:

description: Draft release notes from a git log or diff. Use when the user asks for release notes, a changelog for a release, or to summarise recent changes for shipping.

Avoid generic phrasing. A good description names concrete triggers.

5. Write the instructions

The body holds the steps the agent follows. Lead with the goal, then the procedure, then edge cases:

Draft concise release notes from the provided changes.

1. Group entries under Added, Changed, Fixed, Removed.
2. Write each entry as one imperative line.
3. Drop internal-only and purely cosmetic changes.
4. If a change is user-facing and notable, keep it; otherwise omit.
5. Return only the notes, ready to paste into RELEASE_NOTES.md.

6. Add scripts only if needed

If the skill benefits from code, add a scripts/ directory. Don't add scripts for their own sake — many skills are better as pure instructions. When you do add them, keep them small and readable, and remember they run with real capabilities (see security).

7. Add references or assets where useful

For large supporting material, use references/ so it loads selectively rather than bloating instructions. Put templates and static files in assets/.

8. Test activation

Load the skill in your agent and try tasks that should — and shouldn't — trigger it. If it fails to activate, make the description more specific. If it activates too eagerly, narrow the triggers. Iterate until it behaves.

9. Keep scope clear

One skill, one job. A skill that tries to cover unrelated workflows becomes hard to name, hard to activate, and hard to maintain. Split broad skills into focused ones.

10. Version in Git

Treat skills like code: keep them in version control, write clear commit messages, and tag releases. Versioning also helps anyone consuming your skills update safely.

A complete example

---
name: release-notes
description: Draft release notes from a git log or diff. Use when the user asks for release notes, a changelog for a release, or to summarise recent changes for shipping.
---

Draft concise release notes from the provided changes.

1. Group entries under Added, Changed, Fixed, Removed.
2. Write each entry as one imperative line.
3. Drop internal-only and purely cosmetic changes.
4. Return only the notes, ready to paste into RELEASE_NOTES.md.

That is a complete, reusable skill. The same folder works across skills-compatible agents, including Claude and Codex.

Frequently asked questions

How long should instructions be? As long as needed and no longer. Move big material to references/.

Do I need scripts? No. Start with pure instructions and add scripts only when they add real value.

How do I know the description is good? Test it against tasks that should and shouldn't trigger the skill, then refine.

Where do I share it? Skills are folders — share via Git, a gist, or eventually a registry. The format needs no central service to work.