What are agent skills? How to write your first SKILL.md

If you keep pasting the same instructions into your coding agent ("run the tests first", "use our API error format", "never touch the migrations folder"), an agent skill is probably what you need.

Agent skills are a simple, open format for giving an AI agent a reusable procedure. You write it once, put it in a folder, and the agent loads it when a task calls for it. This guide covers what a skill is, how agents use one, and how to write your first, with a copy-paste example at the end.

What agent skills are

According to the Agent Skills overview, a skill is "a folder containing a SKILL.md file". That file holds some metadata (at minimum a name and a description) plus instructions that tell the agent how to do a specific task. A skill can also bundle scripts, reference docs, templates and other files.

The format was originally developed by Anthropic and released as an open standard, and it has since been adopted by a growing number of agent products (agentskills.io). In practice that means one skill folder can work across several tools:

• Claude Code says its skills "follow the Agent Skills open standard", and it adds its own optional extras on top (Claude Code docs).
• Cursor describes Agent Skills as "an open standard" and loads skills from .agents/skills/ and .cursor/skills/ in your project. For compatibility it also reads .claude/skills/ and .codex/skills/ (Cursor docs).
• Codex says its skills "build on the open agent skills standard" and scans .agents/skills from your working directory up to the repo root (Codex docs).

So if you put a skill in .agents/skills/ in your repo, Cursor and Codex both look there. Claude Code uses .claude/skills/. Check each tool's docs for the exact paths you need.

How agents use skills: progressive disclosure

Skills are cheap to keep around because agents don't load them all at once. The spec describes three stages (agentskills.io):

1. Discovery. At startup the agent loads only each skill's name and description, which is just enough to know when a skill might be relevant.
2. Activation. When a task matches a skill's description, the agent reads the full SKILL.md.
3. Execution. The agent follows the instructions, running bundled scripts or reading referenced files only if it needs them.

There's a practical lesson in this: the description does most of the work. If it's vague, the agent won't know when to use the skill. Codex's docs recommend front-loading "the key use case and trigger words" so a host can still match the skill when descriptions get shortened (Codex docs).

You can also call a skill directly. Claude Code and Cursor let you type /skill-name. In the Codex CLI or IDE extension, you type $ to mention a skill or run /skills (Claude Code, Cursor, Codex).

The SKILL.md format

Here's the structure from the specification:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...

SKILL.md starts with YAML front matter, then Markdown instructions. The spec defines these front matter fields:

Two other guidelines from the spec are worth following: keep the main SKILL.md under 500 lines, and move detailed reference material into separate files that the agent reads only when needed.

Individual tools add their own optional fields. For example, Claude Code and Cursor both support disable-model-invocation: true, which stops the agent from triggering a skill automatically, so it runs only when you call it (Claude Code, Cursor). If you want a skill to stay portable, stick to the spec fields. Claude Code's docs warn that uploading to claude.ai or the Skills API fails with a hard error when the front matter contains fields outside the spec.

How to write your first skill: a pre-deploy check

A good first skill is a procedure you already repeat by hand. For most vibe coders, that's "is this safe to ship?" Here's a portable skill that runs a short pre-deploy checklist.

Create the folder (use .agents/skills/ for Cursor and Codex, or .claude/skills/ for Claude Code):

mkdir -p .agents/skills/pre-deploy-check

Then save this as .agents/skills/pre-deploy-check/SKILL.md:

---
name: pre-deploy-check
description: Runs a pre-deploy checklist on the current branch (build, tests, lint, secrets, env vars, database security) and reports blockers. Use when the user asks if something is ready to ship, deploy, merge, or go to production.
---

# Pre-deploy check

Run these steps in order. Do not fix anything unless the user asks; report first.

## 1. Build and tests
- Run the project's build, test, and lint commands (check package.json scripts or AGENTS.md).
- Record each command and whether it passed.

## 2. Secrets
- Search the diff against the main branch for hardcoded keys, tokens, passwords, or connection strings.
- Flag any secret-looking value that is not read from an environment variable.
- Flag any server-only secret referenced with a public prefix (for example NEXT_PUBLIC_).

## 3. Environment variables
- List every environment variable the changed code reads.
- Check each one is documented in .env.example (names only, never values).

## 4. Database access
- If the diff adds or changes tables, check that Row Level Security (or the project's equivalent access control) is enabled and has a policy for each operation the app uses.

## 5. Report
Reply with:
- A one-line verdict: READY, READY WITH WARNINGS, or BLOCKED.
- A table of checks with pass / warn / fail.
- For each warn or fail: the file, the line, and a suggested fix.

A maintained copy of this skill, ready to install, is in our library as the pre-deploy check skill for coding agents.

This skill shows the habits that make skills work well:

• The description names the trigger phrases ("ready to ship", "deploy", "merge", "production"), so the agent can match it to your requests.
• The steps are written as instructions, with clear inputs and outputs. Codex's best-practice list says the same thing: "write imperative steps with explicit inputs and outputs."
• It does one job. "Keep each skill focused on one job" is another of Codex's recommendations.
• It reports before it acts, which keeps you in control of anything that changes code.

To test it, open your agent in the repo and ask, "Is this branch ready to deploy?" If the skill doesn't trigger, sharpen the description first. You can also call it directly with /pre-deploy-check in Claude Code or Cursor, or $pre-deploy-check in Codex.

Leveling up: scripts and references

Once a skill works, you can make it more reliable:

• Add a scripts/ folder for steps that should behave the same way every time, such as a secret-scanning command. The spec asks that scripts be self-contained, document their dependencies and give helpful error messages (spec).
• Add references/ for long material such as your API conventions. The agent loads these files only when it needs them, so they cost almost nothing until then.
• Install skills other people have written. For example, Supabase publishes agent skills for working with its platform, which you install with npx skills add supabase/agent-skills (Supabase quickstart). Read a third-party skill before you install it: Claude Code's docs warn that a skill can grant itself broad tool access through allowed-tools, so review those fields in any repository you don't control (Claude Code docs).
• Use the built-in skill creators. Codex ships a $skill-creator, and Cursor has a built-in /create-skill (Codex, Cursor).

Skills vs. AGENTS.md vs. MCP

These three are easy to mix up:

• AGENTS.md / CLAUDE.md is always-on project context: build commands, code style, conventions.
• Skills are procedures that load only when a task needs them.
• MCP servers connect your agent to outside tools and data, like a database or an issue tracker.

A good setup uses all three: short always-on context, a few focused skills, and only the MCP connections you actually need.

Keep reading

• How to write an AGENTS.md file for your coding agent
• Code review skill for AI coding agents (SKILL.md download)
• Cursor vs Claude Code vs Codex: how to pick an AI coding agent

FAQ

What is an agent skill?

An agent skill is a folder containing a SKILL.md file with a name, a description and instructions that an AI agent loads when a task needs them. It can also bundle scripts, references and assets.

Where do I put a skill so my agent finds it?

Put it in .agents/skills/ for Cursor and Codex, or .claude/skills/ for Claude Code. Cursor also reads .claude/skills/ and .codex/skills/ for compatibility.

Which fields does SKILL.md need?

Only name and description are required. The name is up to 64 lowercase letters, numbers and hyphens and must match the folder name. The description is up to 1,024 characters and says what the skill does and when to use it.

How is a skill different from AGENTS.md?

AGENTS.md is always-on project context loaded in every session. A skill is a procedure that loads only when a task matches its description, so it costs almost nothing until it is used.