What are agent skills? SKILL.md across four agents

Agent skills are folders that teach a coding agent one task. Each folder has a SKILL.md file: a short description the agent can match, then the steps it should follow when that task comes up. The agent sees the descriptions first and loads the full file only when it uses the skill.

The free AI Agent Skills course is where the file gets written, including the name, the description, and what the skill should refuse to do. This entry is the comparison of where Claude Code, Codex, Cursor and Grok Build look for that folder.

A rule loads on the sessions it applies to. A skill waits until the task matches, or until you invoke it.

How agent skills work

You put SKILL.md in a folder the agent scans. The frontmatter has a name and a description. The body is the procedure: inputs, steps, and when to stop.

At the start of a session the host lists the skills it found, usually as a name and a description. If your request matches, or if you invoke the skill, the host reads the rest of the file. Scripts and reference docs stay on disk until the instructions say to open them. Cursor’s skills page calls that progressive loading. Codex’s build-skills page describes the same split.

You can also type the skill. In Claude Code, Cursor and Grok Build that is a slash command. In Codex you use /skills or a $ mention.

Agent skills in each tool

Claude Code

Create SKILL.md with YAML frontmatter and Markdown instructions. The directory name, or the frontmatter name when you set one, is the / command. The description is what Claude uses when it decides to load the skill on its own.

Project skills live in .claude/skills/ and are for sessions in that repository. Personal skills live in ~/.claude/skills/ and apply to your projects on that machine. A skill in a subdirectory loads the first time Claude reads or edits a file there, and it stays available for the rest of the session. Until then it is not in the / menu.

disable-model-invocation: true stops Claude from running the skill unless you invoke it. A Markdown file in .claude/commands/ still works and creates the same kind of command. The docs say to prefer a skill for new work, because a skill can hold supporting files.

Cowork sessions and cloud sessions do not read ~/.claude/skills/ on your machine. They load the skills enabled for your claude.ai account. See Extend Claude with skills.

OpenAI Codex

A skill is a directory with SKILL.md plus optional scripts and references. The file must include name and description. Codex starts with each skill’s name, description and path. That list uses at most 2% of the context window, or 8,000 characters when the window size is unknown. If many skills are installed, Codex shortens descriptions first, and it can omit some skills and show a warning. skills.max_context_tokens raises the budget, up to 10,000 tokens. The budget applies to the list, not to the SKILL.md Codex reads after it picks a skill.

You invoke one with /skills or $name. Codex can also pick a skill when the request matches the description. agents/openai.yaml can set policy.allow_implicit_invocation to false, so only the explicit $ mention runs it. The default is true.

Repo skills are .agents/skills in the working directory and in parent directories up to the repository root. User skills are ~/.agents/skills. Codex does not merge two skills that share a name. Both can show up in the skill selector. See Build skills.

Cursor

Cursor discovers skills from .agents/skills/, .cursor/skills/, ~/.agents/skills/ and ~/.cursor/skills/. For compatibility it also loads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/. It walks those roots and picks up every SKILL.md.

name is lowercase letters, numbers and hyphens, and it must match the parent folder. description is required. paths limits the skill to files that match a glob. disable-model-invocation: true means the skill loads only when you type /skill-name.

Type / and pick the skill to attach it to one message. Option+Enter on a Mac, or Alt+Enter on Windows, keeps that skill as a Custom Mode for the session. Cursor does not copy ~/.agents/skills/ to Cloud Agents. Personal skills in ~/.cursor/skills/ sync only after you turn on Sync Skills for Cloud Agents, and automation runs still do not load that synced copy. See Cursor skills.

Grok Build

Grok discovers skills in ./.grok/skills/ (walked up to the repo root), ~/.grok/skills/, each enabled plugin’s skills/ directory, extra paths under [skills] paths in ~/.grok/config.toml, and ~/.agents/skills/. It also reads Claude Code skills, with no extra setup.

SKILL.md starts with YAML frontmatter. Extra keys are ignored. name and description can be omitted. user-invocable defaults to true. The only value that counts as true is the literal true, so yes is false. false hides the skill from you and from the model. disable-model-invocation defaults to false and, when true, leaves the skill as a slash command only.

allowed-tools does not grant or restrict tools. Grok accepts model, effort, license and compatibility and does not apply them. See Skills, plugins and marketplaces.

Details checked against each vendor’s documentation in November 2026.

A real example

A skill that reviews a post before it is scheduled. The folder name matches name, which Cursor requires and which Codex and Grok accept:

---
name: post-schedule-check
description: Checks a flaviocopes.com draft before scheduling. Use when the user asks to schedule a post, publish a post, or pick a queue slot. Does not edit the date or the draft flag.
---

# Post schedule check

1. Read the post in src/posts/ and list every internal link.
2. Say which linked posts are still drafts or dated in the future.
3. Stop. Do not change frontmatter.

Save that as .agents/skills/post-schedule-check/SKILL.md for Codex and Cursor, and as .claude/skills/post-schedule-check/SKILL.md for Claude Code. For Grok, put the same folder in .grok/skills/post-schedule-check/. That is the project path the skills page lists. Grok also says it reads Claude Code skills, and it does not name the directory, so this entry does not treat the .claude/skills/ copy as enough on its own. One folder shared by a link is the setup Skill Cabinet is for, so the copies do not drift.

Invoke it with /post-schedule-check in Claude Code, Cursor and Grok Build, or with $post-schedule-check in Codex.

When to use agent skills

Use a skill when the same multi-step job comes up often and the steps should stay stable: a release check, a review with a fixed list, a deploy you want done the same way every time. Codex’s skills page is aimed at that repeatable work.

Skip it for a one-off request. Type the prompt. Skip it for a convention that should be present on every task in the repo. That belongs in CLAUDE.md or AGENTS.md, which load without a match against a description.

The course lesson Skills, prompts and rules draws that line, and Write valid, portable frontmatter is the minimum name and description the shared format asks for.

Pitfalls

A skill only in ~/.claude/skills/ is on Claude Code for local sessions, and Cursor loads that folder for compatibility. Codex looks in ~/.agents/skills/ and in .agents/skills/ inside the repo. It will not see the Claude-only folder. Cloud sessions add another split. Claude Code cloud sessions skip ~/.claude/skills/ on your machine, and Cursor does not copy ~/.agents/skills/ to Cloud Agents.

Codex’s skill list has a budget. Past it, descriptions get shortened and some skills drop out of the list, so the description has to say when to use the skill in the first sentence.

In Grok Build, user-invocable: false hides the skill from the model too, not only from the / menu. user-invocable: yes does not turn it back on. The field wants the literal true.

allowed-tools is not a permission boundary. Grok’s page says the field does not grant or restrict tools. Claude Code and Cursor have their own permission settings, and a line in SKILL.md does not replace them.

Related on flaviocopes.com

• The AI Agent Skills course is the long version: the folder layout, the description, and how to test that the skill triggers.
• Share one agent skill between Claude Code, Codex and Cursor links one folder so those three read the same SKILL.md.
• Skill Cabinet lists the skills on your Mac and which agents load each copy.
• What is an AGENTS.md file is the other shared file. Rules apply to the whole project. A skill applies to one kind of task.

Related glossary entries

• Slash commands: Slash commands are the /name controls inside a coding agent session. How they work in Claude Code, Codex, Cursor and Grok Build, and how to add your own.
• Rules: Project rules are durable instructions a coding agent loads for a repo. How they work in Cursor, Claude Code, Codex and Grok Build, and when to skip them.
• Plugins: A plugin bundles skills, hooks and tools you install together. How plugins and marketplaces work in Claude Code, Codex, Cursor and Grok Build.
• CLAUDE.md: CLAUDE.md is the Markdown file of project instructions Claude Code loads at the start of a session. How Codex, Cursor and Grok Build treat that same filename.

All AI glossary entries →

Want me to talk about your product? You can sponsor this site.