Codex Skill Guide

Codex Skill Guide

Operating Contract

1. Run codex --version and codex exec --help first. Stop if Codex is unavailable, and only use flags shown by the installed CLI.
2. If the user did not specify a model or reasoning effort, use the installed default. Do not hardcode a model list; model names and supported reasoning levels change over time.
3. Select the smallest sandbox needed: --sandbox read-only for inspection and --sandbox workspace-write for requested local edits. Network access, extra writable roots, and broader modes are separate grants.
4. Assemble the command from supported options such as:
   • -m, --model <MODEL>
   • --config model_reasoning_effort="<LEVEL>"
   • --sandbox <read-only|workspace-write|danger-full-access>
   • -C, --cd <DIR>
   • --add-dir <DIR>
   • --json
   • --ephemeral
   • --skip-git-repo-check
   • --dangerously-bypass-approvals-and-sandbox
5. Do not use --skip-git-repo-check by default. Use it only when the user explicitly asks to run outside a Git repository or has approved that boundary bypass for this command.
6. Do not use deprecated compatibility shortcuts such as --full-auto; use the explicit sandbox shown by current help.
7. Preserve stderr. Keep it out of the parent context by writing it to a bounded artifact and reading only the exit status, short tail, or targeted diagnostics. Never redirect it to /dev/null.
8. For automation, batch work, cost investigation, or any run that needs measured usage, add --json and save stdout as JSONL. Read the final usage event and report input, cached input, output, and reasoning tokens when present.
9. Enforce a hard wall-clock timeout with the supervising runtime. Stop on non-zero exit or timeout; do not automatically retry an expensive run.
10. When continuing a genuinely conversational task, use codex exec resume --last via stdin. Do not resume a session for homogeneous record batches; start a fresh bounded --ephemeral run per tranche so accumulated history is not resent on every model call.

Safe Prompt Passing

Do not build Codex commands with echo "user prompt" | ...; user text can contain quotes, substitutions, or newlines. Prefer a quoted heredoc so the shell never reinterprets prompt contents:

(
for required_command in python3 head wc mkfifo; do
  command -v "$required_command" >/dev/null 2>&1 || {
    printf 'Missing required command: %s\n' "$required_command" >&2
    exit 127
  }
done
codex_skill_dir=${CODEX_SKILL_DIR:-$HOME/.claude/skills/codex}
[ -f "$codex_skill_dir/scripts/run_with_timeout.py" ] || {
  printf 'Missing Codex timeout helper: %s\n' \
    "$codex_skill_dir/scripts/run_with_timeout.py" >&2
  exit 1