Install Agent Skills in Claude Code, Codex and other agents

Before you start

You need a skill folder to install: the reviewing-api-changes skill from lessons 1 to 3, or any skill you downloaded. Claude Code covers the main steps, and the other agents are optional. A terminal and a text editor are enough until the plugin section.

Every path and command here comes from the pages under Sources, read on 4 November 2026 and checked again on 5 November. This lesson is not hands-on testing.

Install a skill in Claude Code in five steps

Claude Code has two places for a skill you install by hand. A personal skill lives in ~/.claude/skills/reviewing-api-changes/SKILL.md and loads in all your projects on this machine. A project skill lives in .claude/skills/reviewing-api-changes/SKILL.md, loads in sessions in that repository, and travels with it once you commit it. Claude Code's skills documentation lists both.

# Personal: every project on this machine
mkdir -p ~/.claude/skills
cp -r reviewing-api-changes ~/.claude/skills/

# Project: this repository, committed for your team
mkdir -p .claude/skills
cp -r reviewing-api-changes .claude/skills/
git add .claude/skills/reviewing-api-changes

1. Open the skill before you copy it. Read SKILL.md, then every script and reference file in the folder. Anthropic advises checking all bundled files for unexpected network calls or file access that doesn't match the skill's purpose.
2. Check the folder. SKILL.md has to sit directly inside it, and the folder name should match the name in the frontmatter, as the specification requires.
3. Copy the folder into ~/.claude/skills/ to use it in every project, or into .claude/skills/ to use it in one repository. Claude Code watches both, so you don't restart.
4. Ask What skills are available? and look for the skill. Then ask for something its description matches, or run it directly as /reviewing-api-changes.
5. For a project skill, commit the folder. Everyone who clones the repository gets it. To reach people outside the repository, package the skill as a plugin, as the plugin section below shows.

Where each agent looks for skills

The format is shared. One folder can work in several agents, and they differ in where they scan. The timeline below shows when Codex and Cursor took up the format, and the matrix lists five folders and which agent names each one. "Not listed" means the agent's docs page doesn't name that folder, which isn't the same as saying it fails.

Cursor reads .cursor/skills/ and ~/.cursor/skills/ as well, and Gemini CLI reads .gemini/skills/ and ~/.gemini/skills/. VS Code's Copilot sessions use .github/skills/ and ~/.copilot/skills/, and its Local chat sessions also read the .claude and .agents folders.

• Codex: run $skill-installer with a curated skill's name, such as $skill-installer linear, or drop the folder into .agents/skills. Codex scans that folder from where you launch it up to the repository root, so a skill at the root applies to every subfolder. The Codex skills post goes through the installer in detail.
• OpenClaw has its own registry and an openclaw command, which the OpenClaw skills post covers.
• Cursor takes skills from a GitHub repository only through a plugin, and the repository needs a .cursor-plugin/marketplace.json. Type / in Agent chat to run a skill by name. Cursor rules are a separate feature: saved instructions Agent reads at the start of a conversation.
• Gemini CLI installs from a git URL with gemini skills install https://github.com/user/repo.git. Add --scope workspace to keep the skill local to the project and --path to name a sub-directory of the repository.
• The --consent flag on that command skips Gemini CLI's interactive security confirmation, so leave it off until you have read the skill.
• VS Code: type /skills in chat with Local selected to open the Configure Skills menu.

Share skills with a plugin

A plugin is a folder of skills, agents, hooks and MCP servers with a manifest at .claude-plugin/plugin.json, and Claude Code loads it as one unit. That makes it the sharing route: teammates can install it, several projects can use the same copy, and you can publish it to a marketplace. Only name is required in the manifest. Put each skill at skills/review/SKILL.md in the plugin root. Skills saved inside .claude-plugin/ don't load, as the plugin guide warns.

Plugin skills carry the plugin's name, so /my-plugin:review and a standalone /review can both exist. To turn a project's skills into a plugin, copy .claude/skills into a new folder beside .claude-plugin/plugin.json. Then run claude plugin validate ./my-plugin, which checks the manifest and the frontmatter of every skill file and exits 0 when it passes. Try the plugin with claude --plugin-dir ./my-plugin.

You can hand a plugin over three ways: give people the folder or a zip of it, list it in a marketplace of your own, or submit it to Anthropic's directory. The install scope then decides who gets it. Claude Code plugins goes deeper on marketplaces.

Anthropic's skills repository shows the marketplace route: add the repository once, then install one of its bundles by name. Its README calls the skills demonstrations and tells you to test them in your own environment before relying on them.

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

# In a terminal, once per collaborator, after a project-scope entry is committed
claude plugin install <name>@<marketplace> --scope project

• A marketplace comes from a GitHub owner/repo (add #ref to pin a branch or tag), a git URL, a local path or a hosted marketplace.json. Add it once, then install by name.
• Auto-update is on by default for Anthropic's official marketplace and for marketplaces added from claude.ai, and off for the rest, including the community marketplace. A plugin from a third-party marketplace stays at its installed version until you run claude plugin update my-plugin@my-marketplace or turn auto-update on in the Marketplaces tab.

Boris Cherny on plugin marketplaces, and how Codex and Cursor took up skills

Boris Cherny, who created Claude Code at Anthropic, put plugins third in a February 2026 thread of tips. A plugin can bring skills, MCP servers, agents, hooks and language servers in one install. His advice is to install from Anthropic's official marketplace, or to run a marketplace for your company. Then commit settings.json to the codebase, so the marketplace is added for your whole team. Each teammate still installs the plugin. The scope table above shows which settings file that is.

The folder you install reaches other agents because they adopted the same format. OpenAI Developers posted in December 2025 that Codex officially supports skills, which you can call by name with $ or let Codex pick from your prompt. Cursor announced in January 2026 that Agent Skills are available in Cursor. Before you copy a skill, pick a folder from the matrix that every agent you use reads, such as .agents/skills/ for Codex and Cursor. Then test it in each agent.

A screenshot of X's own embed of the post, taken on 5 November 2026, with the time in UTC. X cuts the post short with Show more. Select it to open the post on X.

Common mistakes

• Copying a whole repository into the skills folder. Each skill needs its own folder with SKILL.md directly inside it, as in ~/.claude/skills/reviewing-api-changes/SKILL.md.
• Naming the folder one thing and the name field another. The specification says the two must match.
• Committing a project-scope plugin entry and assuming the team has the plugin. The entry enables it, but each collaborator still runs the install once.
• Uploading a Claude Code skill to claude.ai unchanged. An upload accepts only name, description, license, compatibility, metadata and allowed-tools, and any other frontmatter key makes it fail.
• Treating a popular repository as a safe one. Anthropic singles out skills that fetch external URLs as a particular risk, because the fetched text can carry instructions, and even a trustworthy skill can be compromised if its external dependencies change over time.

Try it yourself

Install the reviewing-api-changes skill, or any skill you have, twice. Put it in the .claude/skills/ folder of a scratch repository and ask What skills are available?. Then copy it to ~/.claude/skills/ and ask again. Last, wrap the project copy in a plugin, load it with --plugin-dir and note how its command changes to /my-plugin:reviewing-api-changes.

Delete the scratch repository and the personal copy afterward. The test should leave nothing behind.

• Does the skill list from both places, and which copy runs when you call it by name?
• Does the plugin copy show up under the plugin's name?
• Did you open every file in the skill before you copied it?

Next: Claude Code advanced

That closes the Agent Skills course. You can now write, test and install a skill, so the natural next step is to tune the agent that runs it. Claude Code advanced starts with the settings files, then moves on to headless runs, CI and the Agent SDK.

Skills tell an agent how to do a job. The MCP course comes later and covers the servers that give it tools and data to do the job with.

Frequently asked questions

Sources

1. Claude Code docs: Skills (read November 5, 2026)https://code.claude.com/docs/en/skills
2. Claude Code docs: Install and manage plugins (read November 5, 2026)https://code.claude.com/docs/en/discover-plugins
3. Claude Code docs: Create a plugin (read November 5, 2026)https://code.claude.com/docs/en/plugins/create
4. Claude Platform docs: Agent Skills overview (read November 4, 2026)https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
5. Anthropic skills repository (read November 4, 2026)https://github.com/anthropics/skills
6. Agent Skills specification (read November 4, 2026)https://agentskills.io/specification
7. OpenAI: Build skills (Codex) (read November 4, 2026)https://learn.chatgpt.com/docs/build-skills
8. Cursor docs: Agent Skills (read November 4, 2026)https://cursor.com/docs/context/skills
9. Gemini CLI docs: Agent Skills (read November 4, 2026)https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md
10. VS Code docs: Agent Skills (read November 4, 2026)https://code.visualstudio.com/docs/copilot/customization/agent-skills
11. Boris Cherny on X: tip 3, install plugins, MCPs and skills, 11 February 2026 (read November 5, 2026)https://x.com/bcherny/status/2021699862522364149
12. Alex Albert on X: introducing Skills, 16 October 2025 (read November 5, 2026)https://x.com/alexalbert__/status/1978877498411880550
13. OpenAI Developers on X: Codex supports skills, 19 December 2025 (read November 5, 2026)https://x.com/OpenAIDevs/status/2002099762536010235
14. Cursor on X: Agent Skills in Cursor, 23 January 2026 (read November 5, 2026)https://x.com/cursor_ai/status/2014753596223770841
15. Anthropic: Donating Agent Skills to the Agentic AI Foundation (read November 5, 2026)https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation