Codex Skill for Codex

Codex

Codex is an independent agent on PATH (codex — invoke as command codex if

a shell alias shadows it), sharing this working tree and already authenticated. It is a second opinion, not ground truth: verify what it

reports, own what it changes. It reads the same skills your repo carries.

If codex is not installed

When codex is missing from PATH, offer to install it — **ask the user for

approval first**, never install on your own initiative. On yes, follow the

current instructions at https://developers.openai.com/codex/cli. First-run

authentication is interactive — hand that step to the user. Verify with

codex --version before proceeding.

Prompting Codex

Prompt Codex like an operator, not a collaborator: compact, block-structured

with XML tags. State the task, what "done" looks like, and the few constraints

that matter. A tighter prompt beats a bigger run — improve the contract before

raising --effort.

• One task per run. Split unrelated asks (review, then fix, then docs) into

separate runs; a mixed prompt gets a mixed result.

• Name skills instead of restating them. Codex reads the same skills your

repo carries — say "follow write-docs for the doc", "obey refactor-clean: no

compatibility wrappers." Don't re-explain what a skill already carries.

• Blocks, added only where the task needs them:
• <task> — the concrete job, the repo/failure context, the expected end

state. Nearly always present.

• <output_contract> — exact shape, highest-value first, compact.
• <default_follow_through> — take the low-risk interpretation and keep

going; stop only when a missing detail changes correctness, safety, or an

irreversible action.

• <verification_loop> — before finalizing, check the result against the

requirements and the changed files; revise rather than ship the first

draft. Any risky fix.

• <grounding> — ground every claim in code or tool output; label inferences

as inferences. Review and research.

• <action_safety> — keep the diff tightly scoped; no drive-by refactors.

Write tasks.

• Anti-patterns: vague framing ("take a look"), no output contract ("report

back"), "think harder" in place of a contract, mixing jobs in one run, and

demanding certainty the evidence can't support.

Review — proactive

Run a Codex review whenever you have a substantive diff you'd want a second set

of eyes on — a refactor, a tricky algorithm, renderer work, a security-sensitive

change — before declaring it done or committing. Skip it for trivial edits

(typos, comments, doc-only).

• Pick the diff scope: codex review --uncommitted for working-tree changes,

--base <branch> for a branch diff, --commit <sha> for a landed commit.

Scope flags and custom instructions are mutually exclusive (despite what

--help implies): codex review "<instructions>" reviews the default

scope with your framing, a scope flag takes no prompt. When you do write

instructions, scope the risk area — never state the answer you expect

(unprimed, same discipline as

screenshot-critique).

• Triage every finding: confirm it against the code before acting. Preserve

Codex's evidence boundaries — an inference it labelled is not a fact.

Overlap with your own doubts is high-priority evidence; a finding you

dismiss needs a stated reason, not silence.

• Report the outcome to the user — what Codex flagged, what you fixed, what

you dismissed and why. Done when every finding is either fixed or

explicitly dismissed.

Implementation — explicit ask only

Delegate implementation to Codex only when the user names Codex for the task.

Never hand it work on your own initiative, and never re-delegate follow-up

work without a fresh ask.

• Slice the task sharp before delegating — goal, constraints, and how to

verify — using the prompt discipline above. An underspecified task stays

with you until a fresh agent couldn't misread it.

• Start from a clean tree (or record the baseline commit) so Codex's diff is

separable from yours.

• Pick the sandbox by what the task must RUN:
• Pure code + typecheck/unit: codex exec --sandbox workspace-write "<task>".

Network is off; add -c sandbox_workspace_write.network_access=true only

when the task must fetch (e.g. new deps).

• **Browser verification, dev servers, or full test runs: use

codex exec --dangerously-bypass-approvals-and-sandbox "<task>".** The

sandbox blocks localhost binds (listen EPERM on vite/playwright), so a

sandboxed codex ships code it never saw run. Bypass trades that blindness

for zero OS control: only in a dedicated git worktree, only with a prompt

you authored end-to-end (never relaying third-party text), and the diff

review you owe afterwards is the control.

Use -o <file> to capture the final message and background long calls;

suppress codex's stderr thinking-noise with 2>/dev/null so it doesn't

bloat your context (drop it only to debug a failing run), and add

--skip-git-repo-check to run outside a git repo. Non-interactive runs

never ask for approval either way.

• Follow up with codex exec resume <session-id> "<follow-up>", taking the

id from the run header. resume --last means the most recent session

globally — a review or any other codex run in between will hijack it. If

two resume rounds don't converge, stop delegating and finish it yourself —

iterating a confused agent costs more than taking over.

• You own the result: read the full diff, run the tests, and only then report

it. "Codex says it's done" is not done.

Exec liveness — a hang looks like work

A backgrounded codex exec can wedge at startup: process alive at ~0% CPU, but

no session file under ~/.codex/sessions/<Y/M/D>/, no network socket, no tree

changes. "Process running" is NOT "working."

• Stdin is always a file or /dev/null, never an inherited terminal. Left

on an interactive/piped stdin with no prompt source, exec prints `Reading

additional input from stdin...` and blocks forever — the most common hang.

Either pass the prompt as a positional arg with < /dev/null, or feed a

prompt file with codex exec [flags] - < prompt.txt (the - makes codex

read the task from stdin, and a missing file fails the redirect loudly —

unlike "$(cat prompt.txt)", which silently sends the fallback string as

the task). Add nohup/& as needed.

• Watchdog: put a unique marker in the prompt, then kill the exec if

grep -rl "<marker>" ~/.codex/sessions/<Y/M/D>/ finds no session within

~3 minutes. Relaunching after a kill reliably works.

• Trust the worktree. Headless exec in a directory Codex doesn't trust can

block forever on an invisible prompt. Git worktrees are separate paths from

the trusted repo root — add

[projects."<worktree-path>"]\ntrust_level = "trusted" to

~/.codex/config.toml before exec'ing in one. This is the safe fix; the

bypass flags stay forbidden here.

• Don't launch two execs in the same instant, and kill stale hung execs

before starting a new one.

• Launch from the repo/worktree ROOT. The writable sandbox root is the

CWD at launch: exec'd from a subdirectory (e.g. web/), every edit outside

it is rejected as "writing outside of the project" and a never approval

policy can't recover — the run burns with zero files changed. Pass

-C <root> to set the working root explicitly instead of cd-ing into it.

Rules

• Don't touch the working tree while a Codex exec is running on it.
• --sandbox read-only (the default) for consultation and questions;

workspace-write only for delegated implementation.

• --dangerously-bypass-approvals-and-sandbox is reserved for tasks that must

run browsers/servers/full suites (above) — dedicated worktree, self-authored

prompt, mandatory diff review after. --full-auto has been removed (it

aliased workspace-write) — don't reach for it.

• Reasoning effort and model are config/flag overrides — `-c

model_reasoning_effort=high, -m <model> (the old --effort` flag is gone

in current Codex). Leave both at their defaults unless the user asks —

tighten the prompt first.