One library, two folders: where your skills land in Claude, Codex, Cursor and Copilot

A skill is a folder with a SKILL.md in it. That format is now an open standard read by Claude Code, Codex, Cursor, Copilot and a long tail of other tools, which is the whole reason a team library like shareskills can exist. But the standard describes what goes inside the folder. It says nothing about where the folder should live on disk, and the tools disagree.

We checked each vendor’s own documentation this week rather than relying on what people repeat about them. Here is the honest position as of late September 2026:

• Claude Code reads .claude/skills/ in the project and ~/.claude/skills/ for the person. It does not read anything under .agents/.
• Codex reads .agents/skills/ in the project (and its parent folders) and ~/.agents/skills/ for the person. It does not read .claude/skills/.
• Cursor reads both, plus its own .cursor/skills/.
• GitHub Copilot reads both, plus .github/skills/.

So two of the four big clients read only one folder each, and they are different folders. Until now, every install from shareskills said the same thing: save these files under .claude/skills/<slug>/. For a Claude Code, Cursor or Copilot user that was right. For a Codex user it was quietly wrong: the files landed in a folder Codex never looks at, and the skill simply did not appear.

What changed

Every install response from the shareskills MCP server now names an install root on its own line, and uses it in every file path that follows:

# Install 'weekly-pipeline-review' (version 4) — save these 3 file(s) under `.agents/skills/weekly-pipeline-review/`
# install_root: .agents/skills

===== FILE: .agents/skills/weekly-pipeline-review/SKILL.md =====
...

The server picks the root from the MCP handshake. When a client introduces itself as Codex, the root is .agents/skills. For everyone else, including Claude, Cursor, Copilot and any client we have not heard of, the root stays .claude/skills, because every tool that reads .agents/skills other than Codex also reads .claude/skills, and Claude Code reads nothing else. When the server had to fall back to that default it adds one advisory line saying how to ask for the other root, so an agent running inside a proxy or an unfamiliar harness can correct it.

If you would rather not rely on detection, pass install_root=".agents/skills" or install_root=".claude/skills" on the install call. Anything else is rejected with an error that names the two valid values, and no install is recorded.

The same choice, everywhere it matters

• The install card on every skill page now shows both folders, with the tools that read each one beside it. The copyable prompt itself has not changed; your tool’s connection does the choosing.
• The connect page has a Codex tab. Token sign-in is a short config.toml block that reads the token from an environment variable, so nothing credential-shaped lands in a committed file. Browser sign-in is two commands: codex mcp add and codex mcp login.
• Update safety keeps up. When a skill update is checked for material changes before it reaches your team, a skill that writes into another skill’s folder is flagged whichever root it targets, and a skill documenting its own folder is left alone under either.
• First Sync, the wizard that sets up a new organisation, asks which folder layout your team uses. Pick one or both; the seeded shareskills-start skill then inventories and syncs every folder you enabled, and reports rather than guesses if the same skill turns up under both.

A note on AGENTS.md

Skills folders are one half of the convergence story. The other half is the project instruction file. Claude Code can now read a repository’s AGENTS.md when there is no CLAUDE.md, which means a repo set up for Codex or Cursor works in Claude Code without a second file. We took that at face value and gave the shareskills repository itself an AGENTS.md instead of a CLAUDE.md. It is worth knowing the two halves are separate, though: reading AGENTS.md did not make Claude Code read .agents/skills. The instruction file converged; the skills folder did not. That is exactly the gap this release closes from our side.

What to do about it

• If your whole team is on Claude, Cursor or Copilot, nothing changes. Your installs still land in .claude/skills and you can ignore this post.
• If anyone on the team uses Codex, reconnect it from the new Codex tab on the connect page and install a skill. You should see install_root: .agents/skills in the response and the skill in Codex’s list.
• If you run a mixed team, enable both layouts in First Sync. Keep one copy of each skill in the library; let each person’s tool decide where it lands.
• If you commit skills into a repository for a mixed team, a relative symlink from .agents/skills/<name> to .claude/skills/<name> (or the reverse) gives both families of tools the same folder without a second copy to keep in step. That is how our own repository is laid out now.

The point of a team library is one copy that everyone’s tools can reach. Two folder conventions were a small crack in that promise. They are now a detail the server handles for you.