docs/codex-setup.md

# Using agent-skills with Codex

This repository is also a [Codex plugin](https://developers.openai.com/codex/plugins/build). The same root-level `skills/` directory used by Claude Code is consumed by Codex, so no files are copied or duplicated.

## Install

```bash
codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills
```

> Requires Codex CLI v0.122 or later. On older releases the command was `codex marketplace add`. See the [Codex CLI docs](https://developers.openai.com/codex/cli).

The first command registers this repository as the `agent-skills` marketplace. The second command installs and enables the `agent-skills` plugin from that marketplace. Start a new Codex session after installation so the skills are discovered.

Local clones work too:

```bash
codex plugin marketplace add /path/to/your/clone
codex plugin add agent-skills@agent-skills
```

## Usage

After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 25 skills under `skills/` are available.

[Codex uses progressive disclosure](https://developers.openai.com/codex/skills): it starts with each skill's `name` and `description`, chooses skills on demand, then loads the full `SKILL.md` only when selected. Do not also paste `using-agent-skills/SKILL.md` into `AGENTS.md`, a system prompt, or other always-on context: that stacks the pack's meta-router on Codex's native router and adds unnecessary routing work. The meta-skill can remain installed with the pack; the warning is specifically against preloading its full instructions.

## How it works

- `.codex-plugin/plugin.json` — Codex plugin manifest at the repo root. Points `skills` at `./skills/` and provides the metadata required by Codex.
- `.agents/plugins/marketplace.json` — marketplace entry declaring the repo root (`./`) as the plugin source.
- `skills/<name>/SKILL.md` — unchanged. Codex and Claude Code share the same `name` + `description` frontmatter format, so one file serves both platforms.

Slash commands in `.claude/commands/`, personas in `agents/`, and the lifecycle hook under `hooks/` stay Claude Code-specific. On Codex, invoke the underlying skill directly instead of the slash command (e.g. `@spec-driven-development` instead of `/spec`).
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00			`# Using agent-skills with Codex`

fix: use root Codex plugin layout 2026-07-08 15:57:32 +02:00			This repository is also a [Codex plugin](https://developers.openai.com/codex/plugins/build). The same root-level `skills/` directory used by Claude Code is consumed by Codex, so no files are copied or duplicated.
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00
fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:53:34 +09:00			`## Install`
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00
			```bash
docs(codex): update install command for Codex CLI v0.122+ In Codex CLI 0.122 the marketplace subcommand moved from `codex marketplace` to `codex plugin marketplace`. Update README and docs/codex-setup.md so install snippets work on current Codex (verified on 0.128.0). Keep one historical reference in the v0.122 callout. 2026-05-08 13:24:21 +02:00			`codex plugin marketplace add addyosmani/agent-skills`
fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:53:34 +09:00			`codex plugin add agent-skills@agent-skills`
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00			```

docs(codex): update install command for Codex CLI v0.122+ In Codex CLI 0.122 the marketplace subcommand moved from `codex marketplace` to `codex plugin marketplace`. Update README and docs/codex-setup.md so install snippets work on current Codex (verified on 0.128.0). Keep one historical reference in the v0.122 callout. 2026-05-08 13:24:21 +02:00			> Requires Codex CLI v0.122 or later. On older releases the command was `codex marketplace add`. See the [Codex CLI docs](https://developers.openai.com/codex/cli).
feat: add codex cli reference in codex-setup 2026-04-19 17:11:49 +02:00
fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:53:34 +09:00			The first command registers this repository as the `agent-skills` marketplace. The second command installs and enables the `agent-skills` plugin from that marketplace. Start a new Codex session after installation so the skills are discovered.
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00
			`Local clones work too:`

			```bash
docs(codex): update install command for Codex CLI v0.122+ In Codex CLI 0.122 the marketplace subcommand moved from `codex marketplace` to `codex plugin marketplace`. Update README and docs/codex-setup.md so install snippets work on current Codex (verified on 0.128.0). Keep one historical reference in the v0.122 callout. 2026-05-08 13:24:21 +02:00			`codex plugin marketplace add /path/to/your/clone`
fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:53:34 +09:00			`codex plugin add agent-skills@agent-skills`
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00			```

			`## Usage`

docs: route to constraint-driven-development and refresh skill counts 2026-08-08 09:57:00 -07:00			After install, invoke a skill in Codex chat with `@` (e.g. `@spec-driven-development`) or just describe the task and let Codex pick the right skill. All 25 skills under `skills/` are available.
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00
docs: avoid double skill routing on native hosts 2026-09-05 11:45:31 +08:00			[Codex uses progressive disclosure](https://developers.openai.com/codex/skills): it starts with each skill's `name` and `description`, chooses skills on demand, then loads the full `SKILL.md` only when selected. Do not also paste `using-agent-skills/SKILL.md` into `AGENTS.md`, a system prompt, or other always-on context: that stacks the pack's meta-router on Codex's native router and adds unnecessary routing work. The meta-skill can remain installed with the pack; the warning is specifically against preloading its full instructions.

feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00			`## How it works`

fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:53:34 +09:00			- `.codex-plugin/plugin.json` — Codex plugin manifest at the repo root. Points `skills` at `./skills/` and provides the metadata required by Codex.
fix: use root Codex plugin layout 2026-07-08 15:57:32 +02:00			- `.agents/plugins/marketplace.json` — marketplace entry declaring the repo root (`./`) as the plugin source.
feat: add Codex plugin support without duplicating skills Register the repo as a Codex plugin so `codex marketplace add addyosmani/agent-skills` installs it in a single step. The plugin reads the existing `skills/` directory via a symlink — no files are copied, and `skills/<name>/SKILL.md` remains the single source of truth shared with Claude Code. - codex/.codex-plugin/plugin.json — Codex manifest, skills: "./skills/" - codex/skills → ../skills — symlink so the plugin dir stays self-contained while git tracks a single canonical skills/ at the repo root - .agents/plugins/marketplace.json — local marketplace entry, plugin at ./codex - docs/codex-setup.md — install and usage guide Verified end-to-end with codex-cli 0.121.0: skills appear in the plugin's Skills list after install. 2026-04-19 16:29:06 +02:00			- `skills/<name>/SKILL.md` — unchanged. Codex and Claude Code share the same `name` + `description` frontmatter format, so one file serves both platforms.

fix(codex): align plugin metadata and complete CLI setup 2026-08-05 13:53:34 +09:00			Slash commands in `.claude/commands/`, personas in `agents/`, and the lifecycle hook under `hooks/` stay Claude Code-specific. On Codex, invoke the underlying skill directly instead of the slash command (e.g. `@spec-driven-development` instead of `/spec`).