What Are AI Agent Skills? Claude Code, Cursor, Codex

What goes in a SKILL.md file?

A short frontmatter block that says what the skill is for, then the instructions in plain Markdown. Scripts, templates and reference notes can sit in the same folder.

---
name: release-notes
description: Write release notes from the pull requests merged since the last tag.
tags: [release, writing]
---
# Release notes

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the pull requests merged since then.
3. Group them under Features, Fixes and Internal.
4. Write one plain sentence per change. Link the pull request.
5. Leave out anything that only touched tests or CI.

The description does most of the work. The agent reads the descriptions of every installed skill and opens the full file only when a task matches one, so a description that names the job and when to use it (“Write release notes from the pull requests merged since the last tag”) beats a vague one (“Helps with releases”).

Deftro reads the tags (or keywords) field to put a public skill on its topic pages. Keep the steps concrete: commands to run, files to read, what to leave out.

Where do agents look for skills?

Each agent has its own folder in the project. Deftro writes the same skill into whichever of them the project uses.

Folders inside the project travel with the repository: commit them and everyone who clones it gets the same skills.

How is a skill different from a prompt?

A prompt is text you paste into a chat for one task. A skill lives in the repository, and the agent decides on its own when to load it.

• A prompt is for a chatbot such as ChatGPT, Claude or Gemini. You choose it, fill in its blanks and send it. See the prompt library.
• A skill is for a coding agent such as Claude Code, Cursor or Codex. It can include scripts and reference files, and it stays installed until you remove it. See the skills hub.
• A skill gives the agent instructions, not new abilities. To let an agent call an API or query a database you need a tool, usually an MCP server. Skills vs MCP covers the difference.

How do I install a skill?

Copy its folder into the agent's skills directory, or run one command and let the Deftro CLI write it for every agent in the project.

npx @deftro/cli install <handle>/<slug>

The CLI looks for .claude, .cursor, .agents and .codex in the project and writes the skill for each one it finds. The step-by-step version is in How to install Claude Code skills.

Should I read a skill before installing it?

Yes. A skill runs with your agent's access to your files and terminal, so read all of it, including the files beside SKILL.md, before you install it.

Should you trust an agent skill? lists what to look for and how a team can review each version before anyone runs it.