# How to Use Your Claude Skills in Codex and GitHub Copilot

Run one folder of Claude skills in Claude Code, OpenAI Codex and GitHub Copilot, so every skill you build works in every tool your clients use. Where each tool looks, the one-line link that serves Codex, and the frontmatter that quietly stops working when you move.

From the book: [Claude Skills: The Paid Work Playbook](https://youcanbuildthings.com/books/claude-skills-paid-work.md)

Web page: https://youcanbuildthings.com/articles/use-claude-skills-in-codex

Hello builders,

Every skill you build for Claude Code can also work in OpenAI Codex and GitHub Copilot, so one folder of skills follows you into whatever tool a client or employer has standardized on. A developer on X put the usual experience in three sentences, ending with "Portable on paper. I have not seen a clean import without a rewrite." If you want to use Claude skills in Codex, there are two jobs: put the folder where Codex looks, and move the behavior out of the frontmatter fields Codex doesn't read.

The `SKILL.md` format is an open standard now, published at [agentskills.io](https://agentskills.io/specification), so the file itself travels. Which folder does each tool open, and which lines of the file does it read? That's what we walk through here.

## Where each tool looks

GitHub Copilot is the easy one. Its docs list the Claude folder by name:

> Project skills, stored in your repository (.github/skills, .claude/skills, or .agents/skills)
> Personal skills, stored in your home directory and shared across projects (~/.copilot/skills or ~/.agents/skills)

([GitHub Docs, "About agent skills"](https://docs.github.com/en/copilot/concepts/customizations/agent-skills))

A repo where we already keep `.claude/skills` works in Copilot with nothing copied. The same page adds that supported locations depend on the surface, so check the setup guide for the Copilot surface you use.

Codex is stricter. Its [build-skills page](https://learn.chatgpt.com/docs/build-skills) says it "scans .agents/skills in every directory from your current working directory up to the repository root", and it lists these locations:

- `$CWD/.agents/skills`, where you launch Codex
- `$CWD/../.agents/skills`, a folder above it inside a Git repository
- `$REPO_ROOT/.agents/skills`, the top of the repository
- `$HOME/.agents/skills`, your personal skills
- `/etc/codex/skills`, admin skills for the whole machine

We can check the page ourselves, and I searched it for `.claude/skills` and for `~/.codex/skills`, the path I keep seeing in threads, and found neither. Then I tried it with Codex 0.163.0, installed and signed in. With my test skill only in `.claude/skills`, I asked `codex exec` for every skill it had, and `writing-client-updates` was missing from the list. With a copy in `.agents/skills`, the same command printed it.

## One folder, one link

A second copy means two files to keep in step, and another developer on X described hand-copying the same `SKILL.md` into three tool folders across 3 machines "until I lost track of which one was current". The Codex page says it "supports symlinked skill folders and follows the symlink target", so we point Codex at the folder we already have.

With Codex installed and signed in, run this from the root of a repo that has a `.claude/skills` folder:

```bash
mkdir -p .agents
ln -s ../.claude/skills .agents/skills
codex exec "List the names of every skill available to you in this session, one per line." < /dev/null
```

When it works, every folder name under `.claude/skills` shows up in the list. The first lines of mine, with Codex's own built-in skills around it:

```text
imagegen
openai-docs
skill-creator
skill-installer
writing-client-updates
```

I ran exactly those three lines. If `.agents/skills` already exists as a real folder, `ln` puts the link inside it, so move any old copies out first. The same Codex page says it "doesn't merge" two skills that share a name, so a leftover copy we forgot shows up twice. I've only tested the repo version; for a personal folder the docs point at `$HOME/.agents/skills`.


## The fields that stop working

Claude Code accepts a long list of frontmatter fields, and the open standard defines six: `name`, `description`, `license`, `compatibility`, `metadata` and `allowed-tools`. Codex's page says a `SKILL.md` "must include name and description". When I added `when_to_use` and `paths` to my skill, Codex listed it and printed no warning about the skill, so you get no signal when a field is ignored. A claude.ai or Skills API upload of the same file stops with a hard error, which the book prints in full; it starts "Unexpected key(s) in SKILL.md frontmatter".

Here's the port of 11 skills from the book:

![Use Claude skills in Codex: regression-run.md. Copied 11 skills to .agents/skills, stripped to 6 fields. 4 lost when_to_use, folded into description by hand; 2 lost paths, a prose scope line added to each body; 1 lost hooks, guarantee now advisory and noted in the scope note; 1 lost model, no behavioral change. Trigger grid in second tool 14/16 clean, both failures the two skills that relied on paths.](https://youcanbuildthings.com/images/articles/use-claude-skills-in-codex/claude-skills-codex-port-results.png)

Four skills lost `when_to_use`, two lost `paths`, one lost `hooks` and one lost `model`, and the trigger grid in the second tool came back 14 of 16. Both failures were the two skills that had relied on `paths`. Notice what those three fields are for in the book: `when_to_use` helps matching, `paths` scopes a skill to a folder, and `hooks` enforces a rule. All three are Claude Code extensions.

We move the behavior into the parts every tool reads:

- **`when_to_use`**: fold the conditions into `description` by hand.
- **`paths`**: add one plain scope line to the body, such as "Only use this for files under `clients/`."
- **`hooks`**: write the rule into the body and note in your README that it is advisory outside Claude Code.
- **`model`**: nothing to move. The book saw no change when it dropped.

Here's the fold we write for the running skill, which passes `agentskills validate` (from `pip install skills-ref`) with exit 0:

```yaml
---
name: writing-client-updates
description: >
  Writes a client-facing status update from raw notes, meeting minutes, or a
  list of tickets. Use when the user asks for a client update, a status report,
  or a weekly summary for a customer, or pastes notes and names a client.
---
```

## Log the port

Then we write down what moved and what we changed, one line per skill, in the same shape the book uses:

```markdown
## regression-run.md — port to Codex

Linked .claude/skills into .agents/skills. Codex lists: 11 of 11.
- writing-client-updates: when_to_use folded into description
- <skill>: paths -> scope line added to body
- <skill>: hooks -> rule now advisory, noted in README
Trigger tests in Codex, 3 runs each: __ of __ clean
Failures:
```

For each skill we write a few requests that should fire it and a few that should leave it alone, then type each one into a fresh Codex session three times and count. Where did your boundaries live? In the book's port the two failures were the skills that had leaned on `paths`, so look there first.

I'd run this against Codex even if you never plan to use Codex. Copilot opens your Claude folder as it is, so it can't show you much, and the port to Codex is what told the book which two skills leaned on `paths`.

Make the link in one repo tonight, ask Codex for its skill list, and fold one `when_to_use` into its description.

Now go build something this weekend!

John Cook

---

Get the book: Claude Skills: The Paid Work Playbook, $12.99 on Amazon: https://amzn.to/4xkonel