Based on each vendor’s official docs, checked October 20, 2026

Portable agent skills: one SKILL.md for every coding agent

Claude Code, OpenAI Codex, Cursor, GitHub Copilot and Google Antigravity all support skills: a folder with a SKILL.md file of instructions, plus optional scripts and reference files. All five point to the same open Agent Skills format, so one skill can serve every agent. What differs is the folder each agent scans and a few agent-only extras. This guide maps those differences using each vendor’s docs and the agentskills.io specification, checked October 20, 2026.

1. 1. Create one folder per skill

   Name the folder in lowercase letters, numbers and hyphens. Put SKILL.md inside it, and optionally scripts/, references/ and assets/ folders.

   .agents/skills/
   └── code-review/
       ├── SKILL.md
       ├── scripts/
       └── references/

2. 2. Write portable frontmatter

   Set both name and description. The specification requires both, and name must match the folder name. Some agents treat name as optional, but including it costs nothing and keeps the skill valid everywhere.

   ---
   name: code-review
   description: Reviews staged changes for bugs, missing tests and risky edits. Use when the user asks for a review or before committing.
   ---
   
   # Code review
   
   1. Run `git diff --staged`.
   2. ...

3. 3. Write a description that triggers

   Agents load only each skill’s name and description at startup, then read the full SKILL.md when a task matches. Say what the skill does and when to use it, and put the key trigger words first. Codex notes that it may shorten descriptions when many skills are installed.

4. 4. Keep SKILL.md short and link out

   The specification recommends keeping SKILL.md under 500 lines and about 5,000 tokens, and moving detail into files under references/ that you link with relative paths, one level deep.

5. 5. Put it where every agent can find it

   Use .agents/skills/ in the repository for Codex, Cursor, GitHub Copilot and Antigravity. Claude Code reads .claude/skills/, so it needs a copy or link there (see the table below).

Which folder each agent reads

Claude Code: project .claude/skills/, personal ~/.claude/skills/, plus plugin skills. Its docs do not list .agents/skills/.

OpenAI Codex: .agents/skills/ in every folder from the current directory up to the repository root, personal ~/.agents/skills/, admin /etc/codex/skills, plus built-in system skills. Codex follows symlinked skill folders.

Cursor: project .agents/skills/ and .cursor/skills/, personal ~/.agents/skills/ and ~/.cursor/skills/. For compatibility it also loads .claude/skills/, .codex/skills/, ~/.claude/skills/ and ~/.codex/skills/.

GitHub Copilot: project .github/skills/, .claude/skills/ or .agents/skills/; personal ~/.copilot/skills/ or ~/.agents/skills/. This applies to the Copilot cloud agent, code review, the Copilot CLI, and agent mode in VS Code and JetBrains IDEs.

Google Antigravity: project .agents/skills/ (the older .agent/skills/ still works). Personal skills are in ~/.gemini/config/skills/ for the app and IDE, and ~/.gemini/antigravity-cli/skills/ for the CLI.

The one-folder setups that work

Option 1, .agents/skills/ plus Claude Code: keep skills in .agents/skills/, which four of the five agents read, and give Claude Code its own .claude/skills/ copy or link. Codex documents that it follows symlinks; Claude Code’s docs don’t say either way, so check that your linked skill appears in Claude Code before you rely on it.

Option 2, .claude/skills/ only: Claude Code, Cursor and GitHub Copilot all read .claude/skills/. Codex and Antigravity don’t, so this covers three of the five agents.

For personal skills, ~/.agents/skills/ covers Codex, Cursor and Copilot; Claude Code and Antigravity use their own home folders.

The format all five share

From the Agent Skills specification: name is required, up to 64 characters, lowercase letters, numbers and single hyphens, and must match the folder. description is required, up to 1,024 characters. Optional fields are license, compatibility (up to 500 characters, for environment requirements), metadata (string key-value pairs) and allowed-tools (experimental; support varies by agent).

The Markdown body has no required structure. Step-by-step instructions, input and output examples and edge cases are the recommended sections.

What stays agent-specific

Invocation differs: Claude Code turns a skill into a /skill-name command, Codex uses /skills or a $skill-name mention, Cursor lists skills under / in Agent chat, and Antigravity turns them into slash commands.

Extras are not portable: Claude Code adds frontmatter such as disable-model-invocation and subagent execution; Codex reads an optional agents/openai.yaml for display name, invocation policy and MCP tool dependencies, and lets you disable a skill in ~/.codex/config.toml. Treat these as add-ons; the shared name and description are what every agent reads.

Distribution differs too. Each vendor packages skills in its own plugin format, such as Claude Code plugins, Codex plugins, agy plugin install in Antigravity, and gh skill for Copilot.

Tips

• Validate a skill with the reference library: skills-ref validate ./my-skill.
• Keep one job per skill; split a skill when its description needs the word "and" twice.
• Prefer instructions over scripts unless you need deterministic behavior, as OpenAI’s docs advise.
• Never put secrets in a skill folder; skills are committed with the repository.

Next steps

Sources

• https://agentskills.io/specification · checked 2026-10-20
• https://code.claude.com/docs/en/skills · checked 2026-10-20
• https://developers.openai.com/codex/skills · checked 2026-10-20
• https://cursor.com/docs/skills · checked 2026-10-20
• https://docs.github.com/en/copilot/concepts/agents/about-agent-skills · checked 2026-10-20
• https://antigravity.google/docs/skills · checked 2026-10-20
• https://antigravity.google/docs/cli/gcli-migration/ · checked 2026-10-20