feat: add Codex plugin support without duplicating skills

.agents/plugins/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "agent-skills",
+  "plugins": [
+    {
+      "name": "agent-skills",
+      "description": "Production-grade engineering skills covering every phase of software development: spec, plan, build, verify, review, and ship.",
+      "source": {
+        "source": "local",
+        "path": "./codex"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

README.md

@@ -114,7 +114,19 @@ Use agent definitions from `agents/` as Copilot personas and skill content in `.
 </details>
 
 <details>
-<summary><b>Codex / Other Agents</b></summary>
+<summary><b>Codex</b></summary>
+
+Install directly via the Codex plugin marketplace (Codex CLI v0.122+):
+
+```bash
+codex plugin marketplace add addyosmani/agent-skills
+```
+Once installed, invoke skills in chat using @ (e.g., @spec-driven-development). See [docs/codex-setup.md](docs/codex-setup.md) for local installation and troubleshooting.
+
+</details>
+
+<details>
+<summary><b>Other Agents</b></summary>
 
 Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See [docs/getting-started.md](docs/getting-started.md).
 

codex/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "agent-skills",
+  "version": "1.0.0",
+  "description": "Production-grade engineering skills for AI coding agents — covering the full software development lifecycle from spec to ship.",
+  "author": {
+    "name": "Addy Osmani",
+    "url": "https://github.com/addyosmani"
+  },
+  "homepage": "https://github.com/addyosmani/agent-skills",
+  "repository": "https://github.com/addyosmani/agent-skills",
+  "license": "MIT",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Agent Skills",
+    "shortDescription": "Senior-engineer workflows for AI coding agents: spec, plan, build, test, review, ship.",
+    "category": "Productivity"
+  }
+}

codex/skills

@@ -0,0 +1 @@
+../skills

docs/codex-setup.md

@@ -0,0 +1,43 @@
+# Using agent-skills with Codex
+
+This repository is also a [Codex plugin](https://developers.openai.com/codex/plugins/build). The same `skills/` directory used by Claude Code is consumed by Codex — no files are copied or duplicated.
+
+## Install (one command)
+
+```bash
+codex plugin marketplace add addyosmani/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).
+
+Codex clones the repo into `~/.codex/plugins/agent-skills/`, registers the marketplace in `~/.codex/config.toml`, and makes the plugin available. Restart Codex if it's already running.
+
+Local clones work too:
+
+```bash
+codex plugin marketplace add /path/to/your/clone
+```
+
+## 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 21 skills under `skills/` are available.
+
+## How it works
+
+- `codex/.codex-plugin/plugin.json` — Codex plugin manifest. Points `skills` at `./skills/`.
+- `codex/skills` — git-tracked symlink to `../skills` (9 bytes, mode `120000`). Keeps the plugin directory self-contained without duplicating the skills themselves. macOS and Linux handle this natively.
+- `.agents/plugins/marketplace.json` — marketplace entry declaring the plugin at `./codex`. Codex requires plugins to live in a subdirectory of the marketplace root.
+- `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/` and personas in `agents/` stay Claude Code-specific — Codex has no native equivalent for either. On Codex, invoke the underlying skill directly instead of the slash command (e.g. `@spec-driven-development` instead of `/spec`).
+
+## No symlinks (Windows or personal preference)
+
+If symlinks don't work on your machine, replace the symlink with a real copy of the skills inside the plugin directory. Run this from the repo root after cloning:
+
+```bash
+rm codex/skills
+cp -R skills codex/skills
+```
+
+This is a **local-only** change — don't commit it. The upstream repo keeps the symlink so `codex plugin marketplace add addyosmani/agent-skills` stays a one-liner for everyone else.