Share Agent Skills Across Claude Code, Cursor & Codex

Put the canonical copy in .agents/skills/<slug>/SKILL.md, then symlink it into .claude/skills/<slug> for Claude Code. Cursor and Codex both load project skills from .agents/skills/ (Cursor also reads .cursor/skills/ and, for compatibility, .claude/skills/ / .codex/skills/). Claude Code's primary project path is .claude/skills/ — it does not treat .agents/skills/ as its main location. Claude Code and Codex both follow symlinked skill folders, so one tree is enough. Keep frontmatter to the portable Agent Skills fields (name, description, license, compatibility, metadata, allowed-tools) so the same file works across tools; Claude-only keys can break uploads elsewhere. Install ready-made skills from /skills/ or the homepage one-liners.

Last updated October 14, 2026 · Sources checked October 14, 2026

Key facts

Canonical path	`.agents/skills/<slug>/SKILL.md` — Cursor + Codex (and other Agent Skills hosts) discover it here
Claude Code bridge	Symlink `.claude/skills/<slug>` → `../../.agents/skills/<slug>` (Claude reads SKILL.md from the target; loads once even if several locations point at the same target)
Cursor also loads	`.cursor/skills/`, `~/.agents/skills/`, `~/.cursor/skills/`; compatibility: `.claude/skills/`, `.codex/skills/`, and the matching home dirs
Codex also loads	Every `.agents/skills` from CWD up to the repo root, plus `~/.agents/skills`, `/etc/codex/skills`, and bundled skills
Required frontmatter	`name` + `description` in SKILL.md (Cursor and Codex require both; Claude recommends description)
Portable fields	Agent Skills spec / claude.ai uploads: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` — extra Claude-only keys can fail packaging elsewhere
Skills ≠ AGENTS.md	Skills load on demand for a task; AGENTS.md / CLAUDE.md are always-on project instructions — see the migrate Cursor rules → AGENTS.md guide

Skills are not AGENTS.md

Agent Skills package a task-specific workflow: a SKILL.md with a name and description, plus optional scripts and references. The agent loads the full body only when the skill is relevant or you invoke it — so long procedures cost little until you need them.

AGENTS.md / CLAUDE.md are different: they are standing project instructions that load every session. If you stuffed a deploy checklist into AGENTS.md for three agents, move that checklist into a skill and keep AGENTS.md for the short always-on baseline. Same multi-agent problem, different file type — this guide is the skills counterpart to migrating Cursor rules into AGENTS.md.

Where each agent looks for skills

Agent	Primary project paths	User / other	Symlinks?
Claude Code	`.claude/skills/<name>/SKILL.md` (not `.agents/skills/` as primary)	`~/.claude/skills/`; enterprise / plugin / nested `.claude/skills/`	Yes — skill entry may be a symlink; reads target SKILL.md; loads once if several locations share a target
Cursor	`.agents/skills/`, `.cursor/skills/`	`~/.agents/skills/`, `~/.cursor/skills/`; also `.claude/skills/`, `.codex/skills/` and matching home dirs for compatibility	Cursor's skills docs do not mention symlinks or de-duplication. Because Cursor reads both `.agents/skills/` and `.claude/skills/`, check Customize → Skills for a duplicate entry after you add the Claude symlink
Codex	`.agents/skills` from CWD up to repo root	`~/.agents/skills`, `/etc/codex/skills`, bundled	Yes — follows symlink targets when scanning

Cursor walks skill roots recursively (category folders are organizational). Nested .cursor/skills/ or .agents/skills/ under a monorepo package are scoped to that directory. Codex does not merge two skills that share a name — both can appear in selectors.

One tree + Claude symlink

Answer-first pattern (from the repo root):

Canonical copy. Create .agents/skills/<slug>/SKILL.md with at least name and description. Optional scripts/, references/, assets/ sit beside it. Cursor and Codex pick this up as a project skill.
Claude Code symlink. Claude Code's project location is .claude/skills/. Bridge it without duplicating files:
```
mkdir -p .claude/skills
ln -s ../../.agents/skills/<slug> .claude/skills/<slug>
```
Claude Code reads SKILL.md from the symlink target and still loads the skill only once if several locations point at the same directory.
Commit both. Commit the real tree under .agents/skills/ and the symlink under .claude/skills/ (Git stores symlinks as symlinks on Unix). Teammates on Windows may need git config core.symlinks true or a small setup script that recreates the link.
Personal / global skills. For machine-wide skills, mirror the same idea under ~/.agents/skills/ and symlink into ~/.claude/skills/. Cursor also reads ~/.cursor/skills/.

You do not need a separate copy in .cursor/skills/ if the skill already lives in .agents/skills/ — Cursor loads both. Keep .cursor/skills/ for Cursor-only experiments (Custom Mode badge fields, etc.).

Frontmatter that stays portable

Claude Code follows the Agent Skills open standard and adds extra frontmatter (for example disable-model-invocation, context: fork, hooks, agent). Cursor documents name, description, optional paths, disable-model-invocation, icon, color, and metadata. Codex requires name + description in SKILL.md (UI/policy extras can live in agents/openai.yaml).

For a skill you want to share across tools and upload paths, Claude Code's docs are explicit: stick to the six spec-safe fields — name, description, license, compatibility, metadata, allowed-tools. Any other key can make claude.ai packaging or the Skills API fail with an unexpected-key error. Put Claude-only fields only in a Claude-specific copy if you accept maintaining two variants.

---
name: my-skill
description: When to use this skill; front-load trigger words.
license: MIT
---

# My skill

Imperative steps the agent should follow…

How to verify each agent sees the skill

Cursor: Customize → Skills, or type / in Agent chat and search the skill name. Since Cursor also scans .claude/skills/, confirm the symlinked skill does not show up twice. Nested monorepo skills should only surface when you work under that package.
Codex: Run /skills or type $ to mention the skill; or rely on implicit match via description. Restart Codex if a newly added folder does not appear.
Claude Code: Run /skills or invoke /<slug>. Confirm the project skill resolves through the symlink (same content as .agents/skills/<slug>/SKILL.md).

After the tree is shared

Install copy-ready skills (with one-liners for Claude + agents paths) from /skills/ and the homepage. For always-on instructions across the same three agents, use the Cursor rules → AGENTS.md guide and the config matrix (skills folders, MCP, permissions). Skills and instruction files solve different problems — keep both, don't merge them into one mega-file.

Sources

FAQ

Does Claude Code read .agents/skills/?

Claude Code's documented project and personal locations are under .claude/skills/. It does not list .agents/skills/ as a primary path. Symlink each skill into .claude/skills/ so Claude Code sees the same files Cursor and Codex already load from .agents/skills/.

Does Cursor read .claude/skills/?

Yes, for compatibility. Cursor's skills docs say it also loads .claude/skills/, .codex/skills/, and the matching home-directory paths, in addition to .agents/skills/ and .cursor/skills/.

Does Codex support symlinked skill folders?

Yes. Codex's skills docs state it supports symlinked skill folders and follows the symlink target when scanning repository, user, admin, and system locations.

What frontmatter is safe across tools?

For portable skills and claude.ai / Skills API uploads, use only name, description, license, compatibility, metadata, and allowed-tools. Claude Code accepts many more fields; those extras can break packaging outside Claude Code.

How is this different from AGENTS.md?

AGENTS.md (and CLAUDE.md) are always-on project instructions. Skills are on-demand task packages with SKILL.md. Use AGENTS.md for short standing rules; use skills for procedures you invoke when needed.

Where can I get install one-liners?

getaicodingagent.com/skills/ ships free SKILL.md packages with copy-paste installs aimed at ~/.claude/skills and ~/.agents/skills. The homepage converter covers instruction/config files; skills install from the skills pages.

Share one Agent Skills tree across Claude Code, Cursor, and Codex