How to Install a Claude Skill (and Where the Files Actually Go)

Installing a skill means putting its folder where your agent looks for skills, then starting a fresh session. Claude Code reads ~/.claude/skills. Most other agents read ~/.agents/skills. Below: the full directory list, three ways to get the folder there, and how to tell whether it worked.

The short version

• Claude Code → ~/.claude/skills
• Codex, Cursor, Gemini CLI, OpenCode, Kimi Code → ~/.agents/skills
• Antigravity → ~/.gemini/config/skills
• Start a new session afterwards. Agents scan for skills at session start.
• If your agent ignores it, the problem is almost always the directory or the session — in that order.

Before you start

You need three things:

1. An agent that reads skills — Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kimi Code CLI, or Antigravity.
2. The skill folder itself, as a download or a repository.
3. For the CLI method only: Node.js 22 or newer, on macOS or Windows.

Where skills live

This is the part people get wrong, so here it is in full:

Agent	Skills directory
Claude Code	~/.claude/skills
Codex	~/.agents/skills
Cursor	~/.agents/skills
Gemini CLI	~/.agents/skills
OpenCode	~/.agents/skills
Kimi Code CLI	~/.agents/skills
Antigravity	~/.gemini/config/skills

~/.agents/skills is a shared convention that several agents read, which is why one folder there often serves more than one tool at once.

If your agent is not on this list, do not guess. Check its own documentation for the skills directory. Installing to the wrong place fails silently — the agent simply never mentions the skill, and you are left wondering whether the skill is broken.

Method 1 — Copy the folder

Works for any skill from any source. Nothing to install first.

1. Download the skill and unzip it. You should end up with a folder containing SKILL.md.

2. Move that whole folder into the directory from the table above. Create the directory if it does not exist:

   mkdir -p ~/.claude/skills
   mv ~/Downloads/story-first-deck ~/.claude/skills/
   

3. Start a new session. Not a new message — a new session.

The result should look like this:

~/.claude/skills/
└── story-first-deck/
    ├── SKILL.md
    ├── references/
    └── scripts/

One mistake accounts for most failures here: nesting the folder one level too deep. If your path reads ~/.claude/skills/story-first-deck/story-first-deck/SKILL.md, the agent will not find it. SKILL.md should sit directly inside the Skill folder.

Method 2 — One command with the Skillry CLI

If the skill came from Skillry, a single command downloads it, unpacks it, and puts it in the right directory for your agent.

Sign in once:

npx --yes skillry-cli@latest login

That opens your browser. Approve access there, then confirm:

npx --yes skillry-cli@latest status

Then install. The default target is ~/.agents/skills:

npx --yes skillry-cli@latest install story-first-deck

For Claude Code, name the agent:

npx --yes skillry-cli@latest install story-first-deck --agent claude-code

--agent accepts shared, codex, cursor, gemini-cli, opencode, claude-code, kimi-code, or antigravity. For an agent that is not on that list, point at the directory yourself:

npx --yes skillry-cli@latest install story-first-deck --target ~/some/other/skills

Two rules: never combine --agent and --target, and add --force if you are replacing an existing copy — it keeps a backup of the old one.

The CLI stores its access token in the macOS Keychain or Windows Credential Manager. It is never written to a .env or JSON file, and you should never be asked to create or paste an API key.

Method 3 — Let your agent install it

Every Skill page on Skillry serves a machine-readable install guide at /skills/<slug>/install.md. Hand your agent that URL and ask it to follow the guide. It reads the page, picks the directory that matches itself, runs the install, and reports back where the files landed.

This is the fastest path when you are already in a session and do not want to leave it.

Check that it loaded

Three ways, quickest first:

1. Ask. "Which skills do you have available?" The skill should appear by name.
2. Use it. Give it the demo prompt from the skill's page. If the skill is loaded, your agent will say it is using it.
3. Look. ls ~/.claude/skills — confirm the folder is there and SKILL.md sits directly inside it.

When your agent ignores the skill

What you see	Usually means	Fix
Agent never mentions the skill	Wrong directory, or you did not start a new session	Re-check the table above; open a fresh session
SKILL.md is one level too deep	The zip contained a wrapper folder	Move the inner folder up one level
Agent knows it exists but does not use it	Your request does not match the skill's description	Try the skill's own demo prompt verbatim first
Errors about a missing model or tool	The skill depends on an outside service	Check the Dependencies and Outside costs sections on the skill's page
Everything got slower or vaguer	Too many skills installed	Delete the ones you do not use
Asked for an API key	Stop.	No legitimate install flow asks you to paste a key

To remove a skill: delete its folder and start a new session. To update one: replace the folder and start a new session.

A note on safety

Treat every skill package as untrusted until you have read it. Open SKILL.md before installing, and look at anything in scripts/ — those run on your machine.

The Skillry install flow should never ask you to paste an API key, token, or password. Its authorization happens in your browser and never shows you the token. A Skill may later need a credential for a declared runtime dependency; store that credential through the agent or service's documented secret mechanism, never inside SKILL.md or a chat message.

Questions people ask

Where exactly do skills go on my machine? It depends on the agent — see the table above. Every Skill on Skillry also ships its own install.md naming the exact directory for each supported agent, which is more reliable than any path you find in a blog post, including this one.

Do I need to restart after installing? Yes. Start a new session so the agent re-scans its skills directory.

Can I install into one project instead of globally? Several agents support a project-level skills folder alongside the user-level one. Project-level is the better choice when a skill is tied to one codebase or one client.

Do free and paid skills install differently? No. The steps are identical. Both require a signed-in account to download the archive; only the entitlement check differs.

Can one folder serve two agents? Yes. ~/.agents/skills is read by several agents at once. Keep one canonical copy so versions do not drift.

Is Windows supported? Yes, for the CLI. Paths follow the same shape under your user directory.

Next

Wondering whether a Claude Skill will run in Cursor or Codex? Here is what transfers and what does not.