skill-2-codex

Files (12)

• SKILL.md
• external-sources.conf
• codex-format.md · references/
• convert.py · scripts/
• daily-sync.sh · scripts/
• diet.py · scripts/
• fmfield.py · scripts/
• install-daily.sh · scripts/
• manifest.py · scripts/
• scaffold.sh · scripts/
• sync-all.sh · scripts/
• validate.py · scripts/

SKILL.md (first lines)

# /skill-2-codex — port a Claude Code skill to Codex, one direction only

Converts an existing Claude Code skill (`SKILL.md` + supporting files)
into a Codex-compatible skill folder and installs it where told. This is
**one direction only**: Claude Code → Codex. It never reads from or writes
back into a Codex skill, and it never diffs an existing Codex copy against
the Claude source — every run fully regenerates the Codex folder from
scratch. Editing the Claude original does not auto-refresh the Codex copy;
re-run this skill to pick up changes.

Full frontmatter rules, directory layout, discovery paths, and the
Claude→Codex mechanism mapping table live in
[references/codex-format.md](references/codex-format.md) — read it before
doing the body-conversion pass (step 4). It was researched against
OpenAI's official docs; don't re-derive this from memory or guess at
syntax that isn't in that table.

## Arguments

- `$1` — the Claude Code skill's name (its directory name under
  `skills/`, e.g. `dev-makefiles`, `iterate-planner`).
- `$2` — install target: the literal word `global`, or a project path
  (e.g. `~/workspace/x85446/newcorder`).

If `$2` is missing, ask via AskUserQuestion — this is a genuine per-run
decision with no sane default, offer "Global (`~/.agents/skills` — every
Codex session on this machine)" as one option and let the user supply a
project path as the free-text "Other" answer. Don't guess a target.

## Steps

### 1. Locate the source skill

Search in this order, stop at the first match:

1. `~/workspace/x85446/claudecodetricks/skills/$1/` — the canonical
   backup, always the source of truth if it exists.
2. `~/.claude/skills/$1/` — global install.
3. `.claude/skills/$1/` under the current working directory — project
   install.

If none exist, report "no Claude Code skill named '$1' found" and stop.
Do not guess at a similarly-named skill.

Read the full source: `SKILL.md`, every other `.md` file alongside it,
and any `scripts/`/`assets/` subdirectories.

### 2. Scaffold the mechanical conversion

Run:

```
~/workspace/x85446/claudecodetricks/skills/skill-2-codex/scripts/scaffold.sh \
  <source-skill-dir> \
  ~/workspace/x85446/claudecodetricks/codex-skills/<name>
```

`<name>` is the skill's name with any leading `-` (Claude Code's "orphan"
marker) stripped — Codex has no equivalent to that convention. This
always writes into a dedicated `codex-skills/` tree in the backup repo,
parallel to `skills/` but never mixed into it — the two directory shapes
(Codex's `references/`/`scripts/`/`assets/`, no extra frontmatter) are
different enough from Claude Code's convention to keep them visibly
separate.

Read the script's stdout report — it tells you whether the source had
`disable-model-invocation: true` or an `argument-hint`, and how many
reference files it copied.

### 3. Verify `agents/openai.yaml`

`scaffold.sh` writes this file itself whenever the source carried
`disable-model-invocation: true`, because the mapping is fully confirmed
and mechanical. Your job is to confirm it exists and that the key is
**nested**:

```yaml
policy:
  allow_implicit_invocation: false
```

A top-level `allow_implicit_invocation: false` is silently ignored and
the skill keeps auto-firing — that is the single most common porting
mistake. If the scaffold report says `-> true` but no
`agents/openai.yaml` is present, write it by hand in the shape above.

The full schema (`interface`, `policy`, `dependencies`) is in
references/codex-format.md. Populate `interface.display_name` /
`short_description` only if the user asks for picker polish; `policy` is
the only part this conversion requires.

### 4. Body-conversion pass (the judgment-call part)

Open the scaffolded `SKILL.md` and read through its body once, applying
[references/codex-format.md](references/codex-format.md)'s mapping
table. Concretely, for each Claude-Code-specific mechanism found:

- **Agent/Task tool, `run_in_background`, background-completion
  notifications** → rewrite as plain-language subagent orchestration
  ("spawn N agents to handle X and Y in parallel, then merge their
  results") — Codex's runtime maps this onto its own mechanism; do not
  write a fabricated tool-call syntax. On the *first* occurrence in the
  file, add a one-line HTML comment flagging it as unconfirmed-shape:
  `<!-- codex-port: subagent orchestration rewritten in plain language;
  verify against https://developers.openai.com/codex/subagents -->`
- **`/loop` + `ScheduleWakeup` auto-resume** → rewrite using Codex's
  `CronCreate`/`CronList`/`CronDelete` tools. Explicitly note the 7-day
  recurring-job auto-expiry (no Claude Code equivalent) anywhere the
  original assumed indefinite auto-resume — the converted skill needs a
  "re-arm the cron job" note for runs that could outlive a week.
- **`Skill(child-name)` delegation or `/other-skill` invocation** →
  rewrite as Codex's `$other-skill` syntax. Add every such dependency to
  a new "Dependencies" note near the top of the converted body: these
  other skills must ALSO be ported (this skill, on themselves) before the
  converted skill will actually resolve them.
- **`AskUserQuestion`** → rewrite as plain "ask the user to choose
  between..." prose. No confirmed Codex equivalent — flag it inline the
  first time: `<!-- codex-port: no confirmed structured-picker equivalent
  in Codex; verify manually -->`.

From x85446/claudecodetricks, MIT.

More from x85446/claudecodetricks