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

Canonical: https://clawdocx.com/docs/agent-skills-where-skills-go
Author: Sam Okafor
Difficulty: BEGINNER
Published: 2026-02-24
Updated: 2026-10-10

> The Agent Skills spec defines the file, not the folder. Where Claude Code, Codex, Copilot, Cursor, Gemini CLI, Antigravity, OpenClaw and Hermes look.

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](/blog/what-is-skill-md) 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.

| Agent | Project path | User path | Invocation | Extra frontmatter fields |
|---|---|---|---|---|
| Claude Code | `.claude/skills/` (also nested subdirectories, managed enterprise settings and any directory passed with `--add-dir`) | `~/.claude/skills/` | `/skill-name`, or Claude loads it when relevant | The longest list in this table: `allowed-tools`, `disallowed-tools`, `model`, `effort`, `context: fork`, `agent`, `hooks`, `paths`, `argument-hint`, `arguments`, `when_to_use`, `user-invocable`, `disable-model-invocation`, `background`, `shell`, `metadata` |
| ChatGPT | No filesystem path documented; skills are managed in the ChatGPT interface | Same | Type `@` to select a skill | Optional display metadata lives in `agents/openai.yaml`, not in the frontmatter |
| Codex CLI | `$CWD/.agents/skills`, `$CWD/../.agents/skills` and `$REPO_ROOT/.agents/skills` inside a git repository | `$HOME/.agents/skills`, plus `/etc/codex/skills` for a machine-wide install | Run `/skills` or type `$` to mention a skill | Same as ChatGPT: extra metadata sits in `agents/openai.yaml` |
| GitHub Copilot | `.github/skills`, `.claude/skills`, `.agents/skills` | `~/.copilot/skills`, `~/.agents/skills` | `/SKILL-NAME` inside a prompt; `/skills list`, `/skills info`, `/skills reload` to manage | `allowed-tools` and `license`, both of them the specification's own optional fields |
| Gemini CLI | `.gemini/skills/` or the `.agents/skills/` alias | `~/.gemini/skills/` or `~/.agents/skills/` | `/skills list`, `/skills enable`, `/skills disable`, `/skills reload`; `gemini skills` from the terminal | None documented on the page checked |
| Cursor | `.agents/skills/`, `.cursor/skills/`, plus `.claude/skills/` and `.codex/skills/` for compatibility | `~/.agents/skills/`, `~/.cursor/skills/`, plus `~/.claude/skills/` and `~/.codex/skills/` | Type `/` in Agent chat to attach a skill to one message, or Option+Enter (Alt+Enter on Windows) to run it as a Custom Mode | `paths`, `disable-model-invocation`, `icon`, `color`, `metadata` |
| Antigravity | `<workspace-root>/.agents/skills/`, with `.agent/skills` kept for backward compatibility | `~/.gemini/config/skills/` in the IDE; `~/.gemini/antigravity-cli/skills/` in the CLI | `/<skill-name>`, or the agent applies it on its own | None beyond the spec; `name` is optional and defaults to the folder name |
| OpenClaw | `<workspace>/skills` and `<workspace>/.agents/skills`; `$CODEX_HOME/skills` is explicitly not a skill root | `~/.openclaw/skills` for managed and local skills (the default state directory), plus `~/.agents/skills` | `/skill_name`, or `$` in the composer to reference up to eight skills in one message | `user-invocable`, `disable-model-invocation`, `command-dispatch`, `command-tool`, `homepage`, and a `metadata.openclaw` block |
| Hermes Agent | `<project-root>/.hermes/skills/` and `<project-root>/.agents/skills/` | `~/.hermes/skills/`, plus anything in `skills.external_dirs` | `/skill-name`, and up to five stacked in one command | `version`, `platforms`, `required_environment_variables`, and a `metadata.hermes` block |

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](/docs/building-custom-skills) and [what skills are and how agents load them](/docs/skills-explained) 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](/docs/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](/ai-agents/agent-skills).

## Frequently asked questions

**Where do agent skills go?**

There is no single answer, because the Agent Skills specification defines what is inside a skill folder and not where that folder lives. In practice a project-level .agents/skills/ directory is the closest thing to a shared location: Codex, GitHub Copilot, Cursor, Gemini CLI, Antigravity, OpenClaw and Hermes Agent all document reading it.

**Does Claude Code read .agents/skills?**

Claude Code's skills documentation names only .claude/skills directories, at the personal, project, nested, enterprise and additional-directory levels, plus a plugin's own skills folder. The page does not mention .agents/skills, so treat support for it as undocumented rather than confirmed.

**Which single folder works with the most agents?**

A project's .agents/skills/ folder. Seven of the nine rows in the table below document reading it, and GitHub Copilot and Cursor read both .agents/skills and .claude/skills, so a repository carrying both directories covers every tool in the table that reads a repository directory at all. The exception is ChatGPT, where skills are managed in the interface rather than loaded from a folder.

**Do skill frontmatter fields carry across tools?**

Only name and description are guaranteed. Those two are the specification's required fields, and license, compatibility, metadata and allowed-tools are its optional ones. Everything else, such as Claude Code's model or OpenClaw's command-dispatch, is that client's own extension and other tools ignore it.

**What happens if the same skill name appears twice?**

The implementation guide at agentskills.io calls project-level skills overriding user-level skills the universal convention across existing implementations, and recommends a warning when one shadows another. Behaviour within a single scope is left to the client, so avoid duplicate names rather than relying on it.

## Sources

- [Agent Skills specification](https://agentskills.io/specification)
- [Agent Skills: adding skills support to a client](https://agentskills.io/client-implementation/adding-skills-support)
- [Claude Code docs: Skills](https://code.claude.com/docs/en/skills)
- [Claude Code docs: Deploy managed settings](https://code.claude.com/docs/en/managed-settings)
- [ChatGPT docs: Build skills](https://learn.chatgpt.com/docs/build-skills)
- [GitHub Copilot docs: About agent skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
- [GitHub Copilot docs: Adding agent skills for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
- [Gemini CLI docs: Skills](https://geminicli.com/docs/cli/skills/)
- [Cursor docs: Skills](https://cursor.com/docs/skills)
- [Antigravity docs: Skills](https://antigravity.google/docs/skills/)
- [OpenClaw docs: Skills](https://docs.openclaw.ai/tools/skills)
- [Hermes Agent docs: Skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)