msitarzewski · zm2529 · Mar 23, 2026
diff --git a/.gitignore b/.gitignore
@@ -75,4 +75,6 @@ integrations/aider/CONVENTIONS.md
 integrations/windsurf/.windsurfrules
 integrations/openclaw/*
 integrations/qwen/agents/
+integrations/codex/*
 !integrations/openclaw/README.md
+!integrations/codex/README.md
diff --git a/README.md b/README.md
@@ -44,7 +44,7 @@ Each agent file contains:
 
 Browse the agents below and copy/adapt the ones you need!
 
-### Option 3: Use with Other Tools (Cursor, Aider, Windsurf, Gemini CLI, OpenCode)
+### Option 3: Use with Other Tools (Cursor, Aider, Windsurf, Gemini CLI, Codex, OpenCode)
 
 ```bash
 # Step 1 -- generate integration files for all supported tools
@@ -58,6 +58,7 @@ Browse the agents below and copy/adapt the ones you need!
 ./scripts/install.sh --tool copilot
 ./scripts/install.sh --tool aider
 ./scripts/install.sh --tool windsurf
+./scripts/install.sh --tool codex
 ```
 
 See the [Multi-Tool Integrations](#-multi-tool-integrations) section below for full details.
@@ -509,12 +510,13 @@ The Agency works natively with Claude Code, and ships conversion + install scrip
 - **[GitHub Copilot](https://github.com/copilot)** — native `.md` agents, no conversion needed → `~/.github/agents/` + `~/.copilot/agents/`
 - **[Antigravity](https://github.com/google-gemini/antigravity)** — `SKILL.md` per agent → `~/.gemini/antigravity/skills/`
 - **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** — extension + `SKILL.md` files → `~/.gemini/extensions/agency-agents/`
+- **Codex** — skill directories (`SKILL.md` + `agents/openai.yaml`) → `./.codex/skills/`
 - **[OpenCode](https://opencode.ai)** — `.md` agent files → `.opencode/agents/`
 - **[Cursor](https://cursor.sh)** — `.mdc` rule files → `.cursor/rules/`
 - **[Aider](https://aider.chat)** — single `CONVENTIONS.md` → `./CONVENTIONS.md`
 - **[Windsurf](https://codeium.com/windsurf)** — single `.windsurfrules` → `./.windsurfrules`
 - **[OpenClaw](https://github.com/openclaw/openclaw)** — `SOUL.md` + `AGENTS.md` + `IDENTITY.md` per agent
-- **[Qwen Code](https://github.com/QwenLM/qwen-code)** — `.md` SubAgent files → `~/.qwen/agents/`
+- **[Qwen Code](https://github.com/QwenLM/qwen-code)** — `.md` SubAgent files → `./.qwen/agents/`
 
 ---
 
@@ -545,14 +547,15 @@ The installer scans your system for installed tools, shows a checkbox UI, and le
   [x]  2)  [*]  Copilot         (~/.github + ~/.copilot)
   [x]  3)  [*]  Antigravity     (~/.gemini/antigravity)
   [ ]  4)  [ ]  Gemini CLI      (gemini extension)
-  [ ]  5)  [ ]  OpenCode        (opencode.ai)
-  [ ]  6)  [ ]  OpenClaw        (~/.openclaw)
-  [x]  7)  [*]  Cursor          (.cursor/rules)
-  [ ]  8)  [ ]  Aider           (CONVENTIONS.md)
-  [ ]  9)  [ ]  Windsurf        (.windsurfrules)
-  [ ] 10)  [ ]  Qwen Code       (~/.qwen/agents)
-
-  [1-10] toggle   [a] all   [n] none   [d] detected
+  [ ]  5)  [ ]  Codex           (.codex/skills)
+  [ ]  6)  [ ]  OpenCode        (opencode.ai)
+  [ ]  7)  [ ]  OpenClaw        (~/.openclaw)
+  [x]  8)  [*]  Cursor          (.cursor/rules)
+  [ ]  9)  [ ]  Aider           (CONVENTIONS.md)
+  [ ] 10)  [ ]  Windsurf        (.windsurfrules)
+  [ ] 11)  [ ]  Qwen Code       (.qwen/agents)
+
+  [1-11] toggle   [a] all   [n] none   [d] detected
   [Enter] install   [q] quit
 ```
 
@@ -562,6 +565,7 @@ The installer scans your system for installed tools, shows a checkbox UI, and le
 ./scripts/install.sh --tool opencode
 ./scripts/install.sh --tool openclaw
 ./scripts/install.sh --tool antigravity
+./scripts/install.sh --tool codex
 ```
 
 **Non-interactive (CI/scripts):**
@@ -648,6 +652,27 @@ On a fresh clone, generate the Gemini extension files before running the install
 See [integrations/gemini-cli/README.md](integrations/gemini-cli/README.md) for details.
 </details>
 
+<details>
+<summary><strong>Codex</strong></summary>
+
+Each agent becomes a Codex skill directory containing `SKILL.md` and `agents/openai.yaml`.
+Codex is installed project-scoped into `.codex/skills/`, matching the repo's
+other project-local integrations. Chinese description text (`description`,
+`vibe`, and body) is supported, while `name` should remain English/slug-friendly
+for stable folder naming. If `name` is non-ASCII or derives an invalid slug,
+Codex conversion fails fast.
+
+```bash
+# Generate Codex integration files
+./scripts/convert.sh --tool codex
+
+# Install to current project (.codex/skills/)
+./scripts/install.sh --tool codex
+```
+
+See [integrations/codex/README.md](integrations/codex/README.md) for details.
+</details>
+
 <details>
 <summary><strong>OpenCode</strong></summary>
 
@@ -780,7 +805,7 @@ When you add new agents or edit existing ones, regenerate all integration files:
 
 - [ ] Interactive agent selector web tool
 - [x] Multi-agent workflow examples -- see [examples/](examples/)
-- [x] Multi-tool integration scripts (Claude Code, GitHub Copilot, Antigravity, Gemini CLI, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Qwen Code)
+- [x] Multi-tool integration scripts (Claude Code, GitHub Copilot, Antigravity, Gemini CLI, Codex, OpenCode, OpenClaw, Cursor, Aider, Windsurf, Qwen Code)
 - [ ] Video tutorials on agent design
 - [ ] Community agent marketplace
 - [ ] Agent "personality quiz" for project matching

diff --git a/integrations/README.md b/integrations/README.md
@@ -9,6 +9,7 @@ supported agentic coding tools.
 - **[GitHub Copilot](#github-copilot)** — `.md` agents, use the repo directly
 - **[Antigravity](#antigravity)** — `SKILL.md` per agent in `antigravity/`
 - **[Gemini CLI](#gemini-cli)** — extension + `SKILL.md` files in `gemini-cli/`
+- **[Codex](#codex)** — `SKILL.md` + `agents/openai.yaml` skills in `codex/`
 - **[OpenCode](#opencode)** — `.md` agent files in `opencode/`
 - **[OpenClaw](#openclaw)** — `SOUL.md` + `AGENTS.md` + `IDENTITY.md` workspaces
 - **[Cursor](#cursor)** — `.mdc` rule files in `cursor/`
@@ -30,11 +31,15 @@ supported agentic coding tools.
 # Gemini CLI needs generated integration files on a fresh clone
 ./scripts/convert.sh --tool gemini-cli
 ./scripts/install.sh --tool gemini-cli
+
+# Codex is project-scoped
+./scripts/convert.sh --tool codex
+./scripts/install.sh --tool codex
 ```
 
-For project-scoped tools such as OpenCode, Cursor, Aider, and Windsurf, run
-the installer from your target project root as shown in the tool-specific
-sections below.
+For project-scoped tools such as Codex, OpenCode, Cursor, Aider, Windsurf,
+and Qwen, run the installer from your target project root as shown in the
+tool-specific sections below.
 
 ## Regenerating Integration Files
 
@@ -103,6 +108,42 @@ See [gemini-cli/README.md](gemini-cli/README.md) for details.
 
 ---
 
+## Codex
+
+Each agent becomes a Codex skill with:
+
+- `SKILL.md`
+- `agents/openai.yaml`
+
+Generate Codex integration files first:
+
+```bash
+./scripts/convert.sh --tool codex
+```
+
+Then install it from your project root:
+
+```bash
+# project-scoped -> ./.codex/skills/
+./scripts/install.sh --tool codex
+```
+
+Chinese explanation content is supported in Codex description fields and body.
+Keep `name` English/slug-friendly to preserve stable directory naming.
+Codex converter fails fast when `name` is non-ASCII or produces an invalid slug.
+
+Recommended pattern:
+
+```yaml
+name: Frontend Developer
+description: Frontend specialist focused on modern web apps
+vibe: Detail-oriented and maintainability-focused
+```
+
+See [codex/README.md](codex/README.md) for details.
+
+---
+
 ## OpenCode
 
 Each agent becomes a project-scoped `.md` file in `.opencode/agents/`.

diff --git a/integrations/codex/README.md b/integrations/codex/README.md
@@ -0,0 +1,94 @@
+# Codex Integration
+
+Converts all Agency agents into Codex skills.
+
+Each converted skill includes:
+
+- `SKILL.md`
+- `agents/openai.yaml`
+
+Conversion output is written to:
+
+```text
+integrations/codex/
+  AGENTS.md
+  skills/
+    frontend-developer/
+      SKILL.md
+      agents/openai.yaml
+    backend-architect/
+      SKILL.md
+      agents/openai.yaml
+    ...
+```
+
+## Chinese Description Support
+
+Codex integration follows a simple rule: keep identifiers stable, but allow
+human-readable description fields to use Chinese when needed.
+
+Identifier layer (keep English / slug-friendly):
+
+- `name`
+- the slug derived from `name`
+- the skill directory name (for example `frontend-developer`)
+- the installation target directory name
+
+Description layer (Chinese is allowed):
+
+- `description`
+- `vibe`
+- the `SKILL.md` body
+- description fields in `agents/openai.yaml` such as `short_description`
+
+Why: the converter depends on `slugify(name)` to generate directories and
+install paths. If `name` is changed to Chinese, the slug may become invalid or
+empty, which would break directory naming and installation stability.
+`./scripts/convert.sh --tool codex` fails fast in that case, so keep Chinese
+content in `description`, `vibe`, and the body instead.
+
+### Recommended Pattern
+
+```yaml
+name: Frontend Developer
+description: Frontend specialist focused on modern web apps, React/Vue, and performance optimization
+vibe: Detail-oriented, maintainability-focused, and accessibility-aware
+```
+
+### Not Recommended
+
+```yaml
+name: Frontend Specialist CN
+description: Responsible for frontend architecture and implementation
+```
+
+Note: changing `name` away from a stable English slug-friendly value can break
+slug generation and installation paths. Put localized content in `description`,
+`vibe`, and the body instead.
+
+## Convert
+
+```bash
+./scripts/convert.sh --tool codex
+```
+
+## Install
+
+Codex is installed project-scoped to `./.codex/skills/`, matching the repo's
+other project-local integrations.
+
+```bash
+# Project-scoped
+./scripts/install.sh --tool codex
+```
+
+## Notes
+
+- `integrations/codex/AGENTS.md` is generated as an index and usage guide.
+- The installer does not copy `AGENTS.md` by default, so it will not overwrite
+  an existing project-level `AGENTS.md`.
+- Codex installation currently installs the full skill set (no agent filter).
+- Codex follows the same project-scoped install pattern as Cursor, OpenCode,
+  Aider, Windsurf, and Qwen in this repository.
+- UTF-8 Chinese content is written to `SKILL.md` and `agents/openai.yaml`
+  as-is, with no extra transcoding step.