How to create an Agent Skill (SKILL.md)

Quick answer

1. Make a folder named after the skill, in lowercase with hyphens, for example review-changes, inside your tool's skills folder: .claude/skills/ for Claude Code, .agents/skills/ for Codex. Cursor reads either.
2. Add a SKILL.md that starts with YAML frontmatter containing name (the same as the folder name) and description (what it does and when to use it), followed by the instructions.
3. Ask for something that matches the description and the agent loads the skill on its own, or run it directly: /review-changes in Claude Code and Cursor, $review-changes in Codex.

How skills work

Agents load skills in stages. At the start of a session they only see each skill's name and description. When a request matches a description, the agent reads the full SKILL.md, and it opens extra files in the skill folder only if the instructions point to them. That's why you can install many skills without filling the context window, and why the description decides whether a skill ever gets used.

Skills are different from always-on instructions. Files such as CLAUDE.md, AGENTS.md and Cursor rules apply to every session. A skill only loads when it's relevant or when you call it. They're also different from MCP servers: a skill is instructions (plus optional scripts), while an MCP server gives the agent new tools.

Where the skill folder goes

• Claude Code: .claude/skills/<name>/SKILL.md in the project (commit it to share with your team) or ~/.claude/skills/<name>/SKILL.md for all your projects. In a monorepo it also loads .claude/skills/ from parent folders up to the repository root.
• Cursor: .agents/skills/ or .cursor/skills/ in the project, ~/.agents/skills/ or ~/.cursor/skills/ for all projects. For compatibility it also reads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/.
• Codex: .agents/skills/ in the folder you start Codex in and every parent folder up to the repository root, plus ~/.agents/skills/ (written as $HOME/.agents/skills in OpenAI's docs) for all projects.

One skill for all three tools

If you only use Claude Code and Cursor, .claude/skills/ is enough, since Cursor reads it too. If you also use Codex, keep the real folder in .agents/skills/ (read by Cursor and Codex) and link it into .claude/skills/ for Claude Code, which follows symlinked skill folders. On macOS or Linux, from the project root:

mkdir -p .agents/skills/review-changes .claude/skills
ln -s ../../.agents/skills/review-changes .claude/skills/review-changes

Write the SKILL.md

This skill reviews uncommitted changes before a commit. It uses only the fields all three tools understand. Save it as SKILL.md inside the review-changes folder:

---
name: review-changes
description: Reviews uncommitted git changes and flags risky edits, missing tests and leftover debug code. Use when the user asks what changed, wants a review before committing, or asks for a commit message.
---

# Review changes

1. Run git status and git diff HEAD to see what changed.
2. Summarize the changes in two or three bullet points.
3. List risks: missing error handling, hardcoded secrets or URLs, deleted or skipped tests, debug logging left in.
4. Suggest a one-line commit message in the imperative mood.

If there are no uncommitted changes, say so and stop.

Frontmatter rules

• The opening --- has to be the very first line of the file, or the frontmatter is read as plain text.
• name: up to 64 characters, lowercase letters, numbers and hyphens only, no hyphen at the start or end, no double hyphens, and the same as the folder name. Claude Code treats name as optional (it falls back to the folder name), but Cursor and Codex require it, so always set it.
• description: up to 1,024 characters under the open standard. Say what the skill does and when to use it, with the words people actually type. Put the main use case first: Claude Code cuts long descriptions in its skill list and Codex shortens descriptions when many skills are installed.

Keep the body short

Write direct, numbered steps with clear inputs and outputs. The open standard suggests keeping SKILL.md under 500 lines and moving detail into the skill folder:

review-changes/
├── SKILL.md
├── references/   # longer docs the agent reads only when needed
├── scripts/      # code the agent can run
└── assets/       # templates, schemas, example files

Point to those files with paths relative to the skill folder, for example "See references/checklist.md for the full checklist", and keep references one level deep.

Optional settings that differ by tool

• Manual-only skills (for steps with side effects, like deploying): add disable-model-invocation: true to the frontmatter in Claude Code and Cursor, and the agent won't load the skill on its own. In Codex, add an agents/openai.yaml file to the skill with allow_implicit_invocation: false under policy.
• Only for certain files: Claude Code and Cursor accept paths with glob patterns such as "**/*.tsx", so the skill only comes up when the agent works on matching files.
• Pre-approved tools: allowed-tools is an experimental field in the open standard. In Claude Code it lets the skill use the listed tools without asking, for the turn that invokes it.
• Claude Code extras: context: fork runs the skill in a subagent, argument-hint and $ARGUMENTS pass arguments, and dynamic context injection runs a shell command and inlines its output before Claude reads the skill.

For a skill you plan to share across tools, stick to name and description (plus the standard's optional license, compatibility and metadata) and put everything else in the instructions.

Use and test the skill

• Claude Code: ask "What did I change?" or run /review-changes. Edits to existing skill folders are picked up during the session; if you create a new top-level skills folder mid-session, run /reload-skills. Ask "What skills are available?" to confirm it loaded.
• Cursor: ask in Agent chat, or type / and pick the skill. Discovered skills are listed under Customize → Skills.
• Codex: ask in the CLI or IDE extension, run /skills, or type $review-changes. Codex picks up changes automatically; restart it if the skill doesn't appear.

Test it with a few differently worded requests. If it fires when it shouldn't, make the description narrower; if it never fires, add the words people actually say.

Let the agent draft it

Each tool has a built-in helper that interviews you and writes the folder:

• Claude Code: install Anthropic's skill-creator plugin with /plugin install skill-creator@claude-plugins-official; it can also run evals on a skill. See how to install Claude Code plugins.
• Cursor: type /create-skill in Agent chat. /migrate-to-skills converts eligible rules and slash commands into skills.
• Codex: run $skill-creator.

Read what it writes before relying on it, especially any scripts.

Share skills with your team

• In one repository: commit the project skills folder. Everyone who opens the repo gets the skill.
• Across repositories: package skills in a plugin. Claude Code installs plugins from marketplaces (Claude Code Plugins), Cursor imports skills from GitHub only through plugins (Cursor Plugins), and OpenAI recommends plugins for distributing Codex skills.

Ready-made skills to learn from

• Agent Skills (Anthropic): Anthropic's public repository of example and document skills, plus a skill template.
• Android Skills: Google's official skills for Android tasks such as Compose migration and AGP upgrades, installable as plugins for Claude Code and Codex.

Building MCP servers? Our own (paid) Agent Builder Rules + Prompts pack includes two Claude Code skills for MCP server work and evals.

Common problems and fixes

The skill never triggers

• Rewrite the description with the keywords people would use, and lead with the main use case.
• Run it directly (/name or $name). If that works, the problem is the description; if it doesn't, the skill isn't loading.
• Check the folder: SKILL.md must be spelled exactly like that, inside a folder whose name matches name, in one of the locations above.

The frontmatter is ignored

In Claude Code, broken YAML makes the skill load with empty metadata: /name still works but Claude can't match the description. Start with claude --debug to see the parse error, or check the whole folder with claude plugin validate .claude/skills (Claude Code v2.1.233 or later). The open standard's skills-ref validate ./my-skill checks the frontmatter and naming rules for any tool.

The skill triggers too often

Make the description more specific, or make the skill manual-only with the settings under Optional settings above.

A Codex skill is missing

Restart Codex, and check ~/.codex/config.toml for a [[skills.config]] entry that sets enabled = false for that skill's path.

FAQ

Do my old Claude Code custom commands still work?

Yes. Files in .claude/commands/ still work and create the same /name commands. Skills add a folder for supporting files and control over whether Claude can load them on its own.

Skill, rule or AGENTS.md?

Use AGENTS.md, CLAUDE.md or an always-on rule for facts every session needs (stack, conventions, test command). Use a skill for a specific procedure that only matters sometimes, so it doesn't take up context the rest of the time.

Can a skill run scripts?

Yes. Put them in scripts/ and tell the agent when to run them. They run with the agent's normal permissions, so review scripts in skills you didn't write.