One skill folder, four tools: SKILL.md in Codex, Cursor and Gemini CLI

A skill is a folder with a SKILL.md file inside, and the format is an open one that several coding tools read. A skill you wrote or bought for one tool can often be used in another without changes. Here is where each tool looks, how to check that a skill loaded, and what trips people up.

What the format asks for

The folder name is lowercase letters, numbers and single hyphens. Inside is SKILL.md, which starts with a short header that every tool asks for: a name, which must match the folder name, and a description saying what the skill does and when to use it. The open specification at agentskills.io sets limits (a name up to 64 characters, a description up to 1,024) and recommends keeping the body under about 500 lines. Scripts or notes go in the same folder.

Where each tool looks

• Claude Code: .claude/skills/ in the project, and ~/.claude/skills/ for all your projects.
• Codex: .agents/skills/ in the folder you run it from and in the folders above it up to the repository root; ~/.agents/skills/ for all your projects; /etc/codex/skills/ for an administrator.
• Cursor: .agents/skills/ and .cursor/skills/ in the project; ~/.agents/skills/ and ~/.cursor/skills/ for all your projects. It also reads .claude/skills/ and .codex/skills/, and the same two in your home folder.
• Gemini CLI: .gemini/skills/ or the alias .agents/skills/ in the workspace; ~/.gemini/skills/ or ~/.agents/skills/ for you. If both exist in the same place, .agents/skills/ wins.

The shortcut: one folder for three tools

Codex, Cursor and Gemini CLI all read .agents/skills/ and ~/.agents/skills/, so you do not need three copies. Claude Code looks in its own folder, so copy or link the same skill folders into .claude/skills/ if you use it too.

mkdir -p ~/.agents/skills
cp -R my-skill ~/.agents/skills/

Check that it loaded, and call it

• Codex: run /skills, or type $ and the skill's name. It can also choose a skill by itself when your task matches the description. If a new skill does not show up, restart Codex.
• Cursor: open Customize in the sidebar and go to Skills. In Agent chat, type / and pick the skill, or let the agent decide.
• Gemini CLI: /skills list shows them and /skills reload refreshes the list after you copy a folder. When a task matches, the model asks to activate the skill and you get a consent prompt with its name and folder.

Things that trip people up

• The name must match the folder. Cursor's documentation says so and so does the open specification.
• The same name in two places. Codex does not merge skills that share a name, so both appear in its lists. Gemini CLI lets the workspace skill beat the user one. Rename one of them.
• Stopping automatic use. Codex has an optional agents/openai.yaml where policy.allow_implicit_invocation: false keeps a skill for explicit $name calls only. Cursor has disable-model-invocation: true in the skill header.
• Installing from a git repository in Gemini CLI: gemini skills install <git-url> --consent. The --consent flag skips the security confirmation, so use it only on a repository you have read.
• Names and plans change. Google's page says Gemini CLI was replaced by Antigravity CLI on 18 June 2026 for unpaid-tier and Google One users. Check which one you have and read its documentation.

Read a skill before you install it

A skill is instructions that an agent follows with your permissions, and it can ship scripts. Open the SKILL.md, look at every file in the folder, and be wary of anything that downloads and runs code. The free skill-check skill in our GitHub repository is a read-only checklist for exactly this.

How to write your own is in how to write a SKILL.md, and all the guides are in the guides index. This page follows the documentation of Codex, Cursor and Gemini CLI, and the open specification, as we read them on 30 October 2026. We have run skills only in Claude Code, so check the current documentation of your tool and version.

If you want ready-made ones, we put twelve plain-text coding skills (a tour of an unfamiliar repository, a plan in small steps, test first, a safe refactor, finding the cause, a review, a commit and PR draft and more) in this layout: Dev Skills for Codex, Cursor and Gemini CLI. The files pass the specification's format checks; we have not run them inside those three tools. Codex and ChatGPT are trademarks of OpenAI; Cursor and Gemini belong to their owners. We are not affiliated with any of them.