Developer Setup

Written & tested for accuracy by a developer (not AI) · Updated October 2026

Developer Setup for Agent Skills

Agent skills for Claude Code and Codex on a Mac: how to use skills, where skills go, and how to add, share, remove and write your own.

Use a skill for a repeatable task you want done the same way each time, such as correcting "AI writing" habits. A skill is like a pre-written prompt that an agent loads on its own when the task is needed.

If you find yourself typing the same instructions to Claude Code or Codex again and again, you can write and save a skill. Write the instructions once, and an agent can use them whenever the task comes up. A skill gives an agent know-how, not a connection to anything new. To let an agent work with another app or an online service, use an MCP server or a command-line tool, as explained in MCP or Skills or CLI?.

To find useful skills, see Agent Skills Directories and Marketplaces.

How it works

Technically, a skill is a folder of instructions. The main file is named SKILL.md. It starts with the skill's name and a short description of when to use it, followed by the instructions. The folder can also hold reference files and small scripts. Your agent reads only the name and description until a request calls for the skill, so a skill takes up very little of the agent's working memory (its context) until it is used.

Skills follow the Agent Skills open standard, which Anthropic created and released for any tool to use, so the same skill works in Claude Code, Codex, and most other AI coding tools.

The "Set Up Your Mac" apps can add skills, in addition to installing Claude Code and Codex. This page explains what the app adds, then how to use, check and remove skills, where they are stored, and how to add, share and write your own, so an agent can take over the tasks you repeat. It is one topic in "Set Up Your Mac", my guide to setting up a Mac for software development.

Skills installed by the "Set Up Your Mac" apps

After the "Set Up Your Mac" app installs Claude Code or Codex, it offers a few skills I chose to get you started. Some are just instructions, and some run a small program. Choose the ones you want, and the app copies each one into the skills folder of every AI agent it finds on your Mac, so the skill works in every project.

The app never replaces a skill you already have, and it doesn't update or remove skills. The rest of this page shows how to do that yourself, and how to add more skills.

Use a skill in Claude Code or Codex

You don't need to do anything special to use a skill. When your request matches a skill's description, the agent loads the skill and follows its instructions. You can also run a skill yourself, by name:

  • Claude Code - type / and the skill's name at the start of a message, such as /<name>. Type /skills to see all your skills. The Claude Desktop app's Code tab reads the same skills folders when it runs on your Mac.
  • Codex - type $ and the skill's name, such as $<name>, or, in the Codex command-line tool, type /skills to choose from a list. The ChatGPT desktop app, which now includes Codex, uses the same skills.
  • Claude Desktop's Chat tab and claude.ai - these use the skills in your Claude account, not the folders on your Mac. Turn on Cloud code execution and file creation in Settings > Capabilities, then turn skills on or off in Customize > Skills. To add your own skill there, compress its folder into a ZIP file and upload it in Customize > Skills.

Check which skills you have

In Claude Code, type /skills to see your skills, or ask "What skills are available?" Type /context to see how much of the agent's context your skills take up. In the Codex command-line tool, type /skills. In the ChatGPT desktop app, open Skills in the sidebar to see the skills across your projects, or ask Codex to "List the skills available in this chat."

Every skill's name and description stays in the agent's context in every conversation, whether or not you use the skill. Claude Code sets aside about 1% of its context for the list of skills, and Codex up to 2%. With too many skills, Claude Code drops the descriptions of the ones you use least, and the agent may stop choosing them when it should. In Claude Code, /skill-doctor shows what each skill costs and how often you've used it, so you can turn off the ones you don't need.

Turn off or remove a skill

To remove a skill, move its folder out of the skills folder, or to the Trash. To keep a skill but stop your agent from using it:

  • Claude Code - type /skills, select the skill, and press Space to change its setting, then Esc to save. For a skill that came in a plugin, turn off or remove the plugin with /plugin.
  • Codex - add these lines to ~/.codex/config.toml, with the path to the skill's SKILL.md, then quit Codex and start it again:
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Where skills are stored on a Mac

Each AI agent looks for skills in its own folders. Personal skills live in your home folder and work in every project. Project skills live inside a project's folder and work only in that project (commit them to Git and everyone who works on the project gets them too).

  • Claude Code - personal skills in ~/.claude/skills/, and project skills in .claude/skills/ inside the project.
  • Codex - personal skills in ~/.agents/skills/, and project skills in .agents/skills/ inside the project. Codex still reads ~/.codex/skills/, the folder it used before, but OpenAI now treats that folder as deprecated, so put new skills in ~/.agents/skills/.
  • Other AI coding tools - Cursor, GitHub Copilot, Gemini CLI, Zed and Warp also read ~/.agents/skills/, and some of them read ~/.claude/skills/ as well.

Each skill is a folder named after the skill, with its SKILL.md file inside, such as ~/.claude/skills/<name>/SKILL.md. The "Set Up Your Mac" app copies its skills into ~/.claude/skills/, ~/.codex/skills/ and ~/.agents/skills/, wherever the agent's own folder (such as ~/.claude) already exists.

To see your personal skills, open a terminal application and list both folders:

$ ls ~/.claude/skills ~/.agents/skills

You'll see the name of each skill's folder. If one of the folders doesn't exist yet, you'll see "No such file or directory" for it.

Folders whose names start with a dot, such as .claude, are hidden in the Finder. Press Command + Shift + . (period) in a Finder window to show them. See Show Hidden Files on Mac.

Add skills to Claude Code or Codex

You can add a skill in several ways. Whichever you choose, check who published a skill before you add it, because a skill can run programs on your Mac (see "Use skills safely" below).

Install a skill from GitHub

Most skills are shared on GitHub, usually in a repository that holds several skill folders. A skill is just a folder, so you can copy it into place yourself. First, download the repository with git clone, using the address from its GitHub page:

$ git clone https://github.com/<owner>/<repo>

Then copy the skill's folder, the one that holds its SKILL.md, into your skills folder. The first command below creates Claude Code's skills folder if it doesn't exist yet, and the second copies the skill into it:

$ mkdir -p ~/.claude/skills
$ cp -R <repo>/skills/<name> ~/.claude/skills/

For Codex, use ~/.agents/skills in place of ~/.claude/skills. Many repositories keep their skills in a folder named skills, but check the repository's own instructions for the right path.

Install skills with gh skill

The GitHub CLI's gh skill command, still a preview, lets you read a skill before you install it. You'll need the GitHub CLI, version 2.90 or later, which you can install with Homebrew (brew install gh). The first command below shows you the skill, and the second installs it for Claude Code in every project (--scope user):

$ gh skill preview <owner>/<repo> <name>
$ gh skill install <owner>/<repo> <name> --agent claude-code --scope user

Run the install again with --agent codex to add the skill to Codex. Add --pin with a version tag or commit to keep the skill from changing when you update, and run gh skill update --all to update the skills you installed this way.

Install skills with npx skills

Vercel's npx skills tool needs Node.js, which provides the npx command. This command installs skills from a GitHub repository for your user account (-g), for both Claude Code and Codex (-a):

$ npx skills add <owner>/<repo> -g -a claude-code -a codex

The tool asks which of the repository's skills you want. Its recommended setting keeps one copy of each skill and links each agent's folder to it, so one update reaches every agent. Its website, skills.sh, ranks skills by how many people install them.

Install skills from Claude Code plugins

Many skills come packaged in plugins, which can also add commands and MCP servers. Anthropic's plugin marketplace is built into Claude Code: type /plugin and choose Discover to browse it. To install a plugin you've already found, type /plugin install <plugin-name>@<marketplace> in Claude Code. A plugin's skills run with the plugin's name in front, such as /<plugin-name>:<skill-name>. Turn off or remove a plugin from the same /plugin menu.

Install skills with the Codex skill installer

Codex has a built-in skill that installs skills from OpenAI's own collection. Type $skill-installer in Codex, followed by the name of the skill you want. Type /plugins in Codex to browse plugins, many of which include skills.

Load new skills without restarting

Claude Code picks up a new or changed skill right away, without a restart. If you created the skills folder itself while Claude Code was running, type /reload-skills. Codex also notices new skills on its own. If a skill doesn't show up, quit Codex and start it again.

Share skills between Claude Code and Codex

Claude Code reads skills only from its own folders, while Codex and most other AI coding tools read ~/.agents/skills/. So a skill you add to one folder doesn't appear in the other agent. To use one skill in both, keep the real folder in ~/.agents/skills/, which most tools read, and add a symbolic link (a pointer to a folder somewhere else) in Claude Code's folder. Create ~/.claude/skills first if it doesn't exist yet, as shown above:

$ ln -s ~/.agents/skills/<name> ~/.claude/skills/<name>

Both agents follow the link, so when you change the skill, both see the change. The npx skills tool sets up links like this for you. The "Set Up Your Mac" app copies its skills into both folders, so its skills already work in both agents.

Create a Claude skill with a SKILL.md file

Any job you repeat is a candidate for a skill: a checklist you follow, the way you like commit messages written, or the steps to release your project. A skill needs only a folder and a SKILL.md file. Here's a small one:

---
name: commit-message
description: Writes a commit message for the staged changes. Use when the user asks for a commit message.
---

Read the staged changes with `git diff --staged`. Write a summary line of
under 72 characters, then a blank line, then a short paragraph that explains
why the change was made.

To use it in Claude Code, save it as ~/.claude/skills/commit-message/SKILL.md. For Codex, save it in ~/.agents/skills/commit-message/ instead, or link it as shown above.

A few rules make a skill work in every agent:

  • The name must match the folder's name, using lowercase letters, numbers and hyphens, up to 64 characters.
  • The description is what the agent reads to decide whether to use the skill, so say what the skill does and when to use it, in up to 1,024 characters.
  • The instructions should stay under 500 lines. Put long reference material in separate files in the skill's folder, and say in SKILL.md when to read them. The agent opens those files only when it needs them.

You can also ask your agent to write a skill for you. Describe the job, and ask Claude Code or Codex to turn it into a skill. Codex has a built-in skill for this, $skill-creator. For every option in the format, see the Agent Skills specification.

Skills versus slash commands and subagents

In Claude Code, custom slash commands are now skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create the /deploy command, and your old command files keep working. A skill can do more than a command, because its folder can hold scripts and reference files, and the agent can use it on its own when a request matches.

A subagent is something else: a separate helper, with its own context, that the main agent hands a task to and gets a result back from. A skill adds instructions to the agent you're already working with.

Use skills safely

A skill can tell your agent to do anything the agent can do, and a skill with a script runs that script with your permissions. Most skills are harmless, but not all. In February 2026, researchers at Koi Security found 341 malicious skills on ClawHub, the public skill marketplace for the OpenClaw AI agent. Some of them told Mac users to paste a terminal command that installed Atomic Stealer, malware that steals passwords.

Before you add a skill, check who published it, and read its SKILL.md and any scripts in its folder. In Claude Code, look for two things in SKILL.md. An allowed-tools line lets the skill use the tools it names without asking you. A ! followed by a command in backticks, such as !`git diff`, runs that command before Claude even reads the skill. Claude Code has a setting, disableSkillShellExecution, that stops those commands from running in the skills you install, though it also stops skills that use them for good reasons.

Find more skills

The "Set Up Your Mac" app offers a few skills to get you started. There are many thousands more, from Anthropic, OpenAI, other companies and individual developers. See Agent Skills Directories and Marketplaces for where to find them and which sources to trust.

You can also ask your agent to add a skill you've found. Give it the skill's GitHub address, and ask it to add the skill to Claude Code or Codex. Check what it plans to run before you approve it.

Learn more about agent skills

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.