Where Agent Skills Go: Claude Code, Cursor, Codex, Copilot

An agent skill is a folder whose name matches the name field in its SKILL.md, and each client reads it from a directory that client owns. Claude Code reads .claude/skills/<name>/SKILL.md in a project and ~/.claude/skills/<name>/SKILL.md in every one. Cursor reads .agents/skills/ or .cursor/skills/ in a project, and the same two under your home directory.

Both clients split skills into project scope and personal scope, and both use the folder name as the identity of the skill. The Agent Skills specification requires the name field to match the parent directory name, and Cursor restates that rule in its own documentation.

Claude Code adds three scopes the other clients do not have. A plugin carries skills in its own skills/ folder and namespaces them as /plugin-name:skill-name. Enterprise skills load from .claude/skills/ inside the managed settings directory. Skills enabled on a claude.ai account download into ~/.claude/skills/synced/, which is why synced is a reserved folder name that Claude Code skips.

Personal scope also differs by client, and that is where a directory which works locally stops working elsewhere. Cursor keeps ~/.cursor/skills/ on the machine until you turn on Sync Skills for Cloud Agents, and it copies neither ~/.agents/skills/ nor unsynced local skills to Cloud Agents, remote SSH sessions or self-hosted workers. Claude Code keeps ~/.claude/skills/ out of Cowork, cloud sessions and routines, which read the skills enabled on your account instead.

Agent Skills clients disagree about directories, which is why a skill written for one client often sits unread in another. Each client name below links to the page the row is drawn from, and every page was read on 19 September 2026.

Two rows need a note the table cannot hold. Anthropic's help centre article writes the filename in lowercase as skill.md and caps the description at 200 characters, while the platform documentation and the specification say SKILL.md and 1,024. The rows above follow the platform documentation. The Codex row covers the ChatGPT desktop app as well, because OpenAI ships skills into both products from the same .agents/skills locations.

The .agents/skills/ path is the nearest thing to a shared location, and Gemini CLI explains why it exists: the alias is documented as an interoperable path that stays compatible across different AI tools. Five of the seven rows above read it. Claude Code is the holdout, so a repository that mixes clients needs a .claude/skills/ entry beside the shared one rather than instead of it.

Each row below is the check that client documents. Listing a skill and using the skill are different questions, and only one of them has a command.

GitHub documents no list command for the cloud agent, so the only check there is whether Copilot applies the skill when your prompt matches its description. Anthropic documents the same gap for claude.ai, which is why that row ends in a prompt test.

Documentation pages describe intent, and clients enforce less than they describe. I built one scratch project on macOS, placed the same SKILL.md files in different directories, and ran two clients against it. Claude Code was version 2.1.272 and OpenCode was version 1.18.23.

Claude Code ran a skill from .claude/skills/hello/ when it was invoked as /hello, and answered Unknown command: /agentsonly for a skill that existed only in .agents/skills/. A control invocation of /nosuchskill in the same project returned the same message, so that message separates a failed load from a successful one. A symlink at .claude/skills/linked pointing into .agents/skills/agentsonly/ then worked, which means Claude Code takes the invocation name from the entry in its own directory while reading the file from the target. Codex documents following symlinked skill folders as well, and the other clients' pages do not say.

OpenCode listed skills from a project .agents/skills/ directory, a project .claude/skills/ directory and a home ~/.agents/skills/ directory, each with its path on disk. It also listed a skill whose name field said not-mismatch inside a folder called mismatch, under the frontmatter name, so the match rule its own documentation states was not enforced at discovery in that version. Every run happened on macOS, in one project, against project-level paths.

The symlink result is the one that matters for a team, because it means one authored copy can serve a client that reads .agents/skills/ and a client that does not.

Commit the skill directory. A skill checked into a repository is the one distribution method every client in the matrix supports, and each client picks the folder up from its own path without an install step.

Author the file once in .agents/skills/<name>/, the path five of the seven clients read, and add a symlink at .claude/skills/<name> for Claude Code. That arrangement was measured above rather than assumed. Windows needs a different mechanism for symlinks, and no client in this matrix documents junction behaviour.

Claude Code writes the per-developer visibility choices from its /skills menu into .claude/settings.local.json, so that file belongs in .gitignore. Keep personal skill directories out of the repository, and do not author a skill named synced, because Claude Code reserves that folder for account skills.

Portability breaks in three places. Claude Code accepts frontmatter fields that claude.ai and the Skills API reject with an error listing the allowed keys, so a skill meant for both surfaces should use the six specification fields only. Body features that only Claude Code implements, such as injecting shell output at load time, do nothing in claude.ai chat or through the API. Codex reads an optional agents/openai.yaml beside SKILL.md for display metadata and invocation policy, and the other clients ignore that file.

A skill is one shape of reusable capability, and an MCP server is the other. The server shape suits a capability that should run on a server rather than travel as a folder of instructions. Prepublish publishes it at the MCP server, with a remote endpoint, a local bridge through npx prepublish-mcp, and the same audit reachable by either route.

If you would rather not author the file, the channel skill generator writes a bundle in this layout: one SKILL.md plus a references/ folder, inside a zip whose root is the skill folder. The name it generates already satisfies the 64 character ceiling, and it is capped at 48 characters because that name becomes the frontmatter name, the zip top level and the download filename stem (prepublish-be/internal/domain/entity/channel_skill_render.go). Measured runs on 18 and 19 September 2026 produced a 9,623 byte SKILL.md for @maxinomics from 12 videos and 9 transcripts in 6 minutes 30 seconds.

Each row is a documented rule rather than a guess, and most of them come from the specification's validation rules or from a client that enforces them.

Everything here describes what seven vendors documented on 19 September 2026. Directories in this area have moved before and will move again. Claude Code merged custom commands into skills and still loads .claude/commands/ for older setups. Gemini CLI tells unpaid tier and Google One users that Antigravity CLI replaced it on 18 June 2026, while the skills page I read carries an April 2026 date. gh skill is in public preview and needs GitHub CLI 2.90.0 or later. The Copilot and Codex pages carry no visible last-updated date at all, so the only date attached to those rows is the day I read them.

Some cells rest on documentation alone, and the table says so rather than filling the gap. Codex does not document whether it reads .claude/skills/. Cursor, Copilot, Gemini CLI, OpenCode and Claude apps do not state whether they follow a symlinked skill folder, and only Claude Code and Codex document that they do. My OpenCode measurement came from one version on one operating system. The default filesystem on macOS is case-insensitive, so a lowercase skill.md was the same file as SKILL.md, and I did not test filename casing anywhere else.

Version gates sit under individual behaviours, and they matter when a step does not work on your machine. /skill-doctor needs Claude Code v2.1.252 or later. Syncing account skills in the terminal needs v2.1.273 or later. Cursor copies personal skills to Cloud Agents only after you turn sync on.

Re-check four things after a client upgrade. Confirm the directory still matches the matrix, because a compatibility path can be dropped as quietly as it was added. Re-run one explicit invocation per client, since that separates discovery from matching. Confirm the frontmatter fields you use still load in the client that is not yours. Re-read the documentation pages, because each carries its own last-updated date, and a directory claim is only as current as the page that made it.