diff --git a/plugins/codex/skills/codex-cli-runtime/SKILL.md b/plugins/codex/skills/codex-cli-runtime/SKILL.md
index 0e91bfb5..8236d1ed 100644
--- a/plugins/codex/skills/codex-cli-runtime/SKILL.md
+++ b/plugins/codex/skills/codex-cli-runtime/SKILL.md
@@ -9,7 +9,16 @@ user-invocable: false
 Use this skill only inside the `codex:codex-rescue` subagent.
 
 Primary helper:
-- `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "<raw arguments>"`
+- `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task --prompt-file /path/to/prompt.txt [OPTIONS]`
+
+For complex prompts with special characters, quotes, or multi-line content, always use `--prompt-file`:
+1. Write the prompt to a temp file: `printf '%s' 'your prompt here' > /tmp/codex-prompt.txt`
+2. Pass it via `--prompt-file /tmp/codex-prompt.txt`
+
+This avoids shell escaping issues that break prompts containing `$`, backticks, quotes, or newlines.
+
+Legacy positional form (avoid for complex prompts):
+- `node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" task "simple prompt"`
 
 Execution rules:
 - The rescue subagent is a forwarder, not an orchestrator. Its only job is to invoke `task` once and return that stdout unchanged.
diff --git a/tests/commands.test.mjs b/tests/commands.test.mjs
index c34b0605..19a4b4a3 100644
--- a/tests/commands.test.mjs
+++ b/tests/commands.test.mjs
@@ -192,7 +192,7 @@ test("internal docs use task terminology for rescue runs", () => {
   const promptingSkill = read("skills/gpt-5-4-prompting/SKILL.md");
   const promptRecipes = read("skills/gpt-5-4-prompting/references/codex-prompt-recipes.md");
 
-  assert.match(runtimeSkill, /codex-companion\.mjs" task "<raw arguments>"/);
+  assert.match(runtimeSkill, /codex-companion\.mjs" task --prompt-file/);
   assert.match(runtimeSkill, /Use `task` for every rescue request/i);
   assert.match(runtimeSkill, /task --resume-last/i);
   assert.match(promptingSkill, /Use `task` when the task is diagnosis/i);