Where do agent skills go? .agents/skills, .claude/skills and .github/skills by agent

There is no one folder. The Agent Skills specification describes what goes inside a skill directory and says nothing about where that directory sits on disk, so every client picked its own. If you want one copy of a skill that the most tools can find, put it in a project-level .agents/skills/ folder: Codex, GitHub Copilot, Cursor, Gemini CLI, Antigravity, OpenClaw and Hermes Agent all document reading it. Claude Code is the exception worth planning around, because its documentation names only .claude/skills directories.

#Does the Agent Skills spec say where skills go?

No. The specification opens on the directory structure of a skill, not its location: "A skill is a directory containing, at minimum, a SKILL.md file", with optional scripts/, references/ and assets/ beside it.

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

The implementation guide for client authors says the quiet part outright. Recommending that clients scan both their own directory and a shared one, it notes that "the .agents/skills/ paths have emerged as a widely-adopted convention for cross-client skill sharing", and that "the Agent Skills specification does not mandate where skill directories live (it only defines what goes inside them)".

That is why this page exists. The file is portable. The path is a per-vendor decision, and the vendors did not all make the same one. If you have not written a skill yet, what a SKILL.md is covers the format first.

#Where does each agent look for skills?

Every path below is taken from that tool's own documentation, first checked on 23 and 24 September 2026 and re-checked against all twelve source pages on 8 October 2026. Where a tool reads several directories, they are listed in the order its docs give.

Three entries in that table are worth reading twice.

ChatGPT and Codex are one product family with two discovery models. OpenAI's documentation says that "Codex scans .agents/skills in every directory from your current working directory up to the repository root", and the table on the same page names three of those scopes explicitly: the working directory, a parent folder and the repository root. Either way a skill checked into a repository is found by anyone who clones it. ChatGPT itself has no documented filesystem path at all: its documentation covers invocation, with @ to select a skill in ChatGPT and $ or /skills in the CLI, but the app is not reading a folder on your machine.

GitHub Copilot and Cursor are the two that read both conventions. Copilot's repository list is .github/skills, .claude/skills and .agents/skills; Cursor's documentation says that "for compatibility, Cursor also loads skills from Claude and Codex directories". That makes either one a reasonable place to test whether a skill written for one tool behaves in another.

OpenClaw rules one path out in writing, which is rarer than it sounds. Its documentation says that "Codex CLI's native $CODEX_HOME/skills directory is not an OpenClaw skill root", and points at openclaw migrate plan codex to inventory those skills and openclaw migrate codex to copy them into the OpenClaw workspace. Worth knowing before you assume a Codex install carries over: the shared .agents/skills folders do, and the Codex-specific one does not.

#Does Claude Code read .agents/skills?

Its documentation does not say so. The Claude Code skills page names .claude/skills at every scope it supports: ~/.claude/skills/<skill-name>/SKILL.md for personal skills, .claude/skills/<skill-name>/SKILL.md in a project, the same path in a subdirectory, in the managed enterprise settings directory, and in any directory passed with --add-dir, plus <plugin>/skills/<skill-name>/SKILL.md for a skill that ships inside a plugin and ~/.claude/skills/synced/ for skills it syncs down from claude.ai. The page does not mention .agents/skills anywhere.

That is a statement about one page rather than about the product. It may read the shared folder and not document it, and undocumented behaviour can change without a changelog entry. The safe reading is that .claude/skills is the path Anthropic supports, and anything else is unconfirmed.

The practical consequence is small. Copilot and Cursor already read .claude/skills, so a repository that carries both directories covers every tool in the table that reads a repository directory at all, which is all of them except ChatGPT, where skills are managed in the interface instead:

my-project/
├── .agents/skills/
│   └── release-notes/
│       └── SKILL.md
└── .claude/skills/
    └── release-notes/
        └── SKILL.md

A symlink from one to the other keeps a single copy authoritative, at the cost of a file that Windows checkouts and some CI runners handle badly. Committing both copies is duller and more predictable.

#Which frontmatter fields survive the move?

Two, guaranteed. The specification makes name and description required and license, compatibility, metadata and allowed-tools optional, and marks allowed-tools experimental with support that "may vary between agent implementations".

name has real constraints, and they are the ones a portable skill trips over first. The specification requires 1 to 64 characters, lowercase alphanumerics and hyphens only, no leading or trailing hyphen, no consecutive hyphens, and a name that matches the parent directory.

Nearly everything in the last column of the table above is a client extension. Claude Code's model, effort and context: fork mean nothing to Gemini CLI. OpenClaw's command-dispatch means nothing to Cursor. The exceptions are allowed-tools, license and metadata, which are the specification's own optional fields and appear in that column only because the clients listing them go further than the two required ones. This is mostly harmless, because the implementation guide recommends lenient parsing: a client should "warn on issues but still load the skill when possible", skipping it only when the description is missing or the YAML is unparseable. Write to the specification's fields, add one client's extras if you need them, and expect other clients to ignore rather than reject them.

For writing the body itself, building custom skills and what skills are and how agents load them go further than this page does.

#What happens when two skills share a name?

Project beats user. The implementation guide calls it "the universal convention across existing implementations: project-level skills override user-level skills", and recommends logging a warning so the user knows a skill was shadowed. Within one scope, for instance the same name in both .agents/skills/ and the client's own folder, it says first-found or last-found are both acceptable as long as a client is consistent.

So collisions across scopes are predictable and collisions inside a scope are not. If you keep both .agents/skills/ and .claude/skills/ in a repository, keep the two copies identical, or give them different names and accept that both appear in the menu.

#What should you check before installing someone else's skill?

A skill is instructions an agent will follow and, when it bundles scripts/, code an agent may run. The implementation guide says as much to client authors: project-level skills "come from the repository being worked on, which may be untrusted (e.g., a freshly cloned open-source project)", and it suggests gating project-level loading on a trust check, which it says "prevents untrusted repositories from silently injecting instructions into the agent's context".

Read the SKILL.md and every bundled script before you copy a folder into any of the paths above. Our skill security audit is the checklist we use. Nothing on ClawDocx is an endorsement of a third-party skill, including any named in a source we cite.

#Where to put a skill, in one line each

• One project, one tool: that tool's own folder. It is the path its documentation supports and the one its /skills commands manage.
• One project, several tools: .agents/skills/ in the repository, and a second copy in .claude/skills/ if anyone on the team uses Claude Code.
• Every project you work on: the user-level equivalent, which is ~/.agents/skills/ for Codex, Copilot, Cursor, Gemini CLI and OpenClaw, and ~/.claude/skills/ for Claude Code.
• A whole machine or container: Codex documents /etc/codex/skills, and Claude Code reads .claude/skills/ from the managed settings directory an administrator deploys, which is /etc/claude-code/ on Linux and WSL, /Library/Application Support/ClaudeCode/ on macOS and C:\Program Files\ClaudeCode\ on Windows. Everywhere else, use the user-level folder in the image.

The full standard, its 46 listed clients and the security guidance around it are on our Agent Skills hub.