Fix ask-codex shell quoting guidance (#39)

Author: dzwduan

skills/ask-codex/SKILL.md

@@ -11,12 +11,30 @@ Send a question or task to Codex and return the response.
 
 ## How to Use
 
-Execute the ask-codex script with the user's arguments:
+Do not pass free-form user text to the shell unquoted. The question or task may contain spaces or shell metacharacters such as `(`, `)`, `;`, `#`, `*`, or `[`.
+
+If the user only supplied a question or task, execute:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/ask-codex.sh" "$ARGUMENTS"
+```
+
+If the user supplied flags such as `--codex-model` or `--codex-timeout`, reconstruct the command so those flags remain separate shell arguments and the remaining free-form question is passed as one quoted final argument.
+
+Example:
+
+```bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/ask-codex.sh" --codex-model gpt-5.4:high "Review the following round summary (M4)..."
+```
+
+Never run this unsafe form:
 
 ```bash
 "${CLAUDE_PLUGIN_ROOT}/scripts/ask-codex.sh" $ARGUMENTS
 ```
 
+because the shell will re-parse the question text and can fail before `ask-codex.sh` starts.
+
 ## Interpreting Output
 
 - The script outputs Codex's response to **stdout** and status info to **stderr**

tests/test-ask-codex.sh

@@ -15,6 +15,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
 source "$SCRIPT_DIR/test-helpers.sh"
 
 ASK_CODEX_SCRIPT="$SCRIPT_DIR/../scripts/ask-codex.sh"
+ASK_CODEX_SKILL="$SCRIPT_DIR/../skills/ask-codex/SKILL.md"
 
 echo "=========================================="
 echo "Ask Codex Tests (mock)"
@@ -403,6 +404,35 @@ else
     fail "codex-run.cmd records the question"
 fi
 
+# ========================================
+# Skill Guidance Tests
+# ========================================
+
+echo ""
+echo "--- Skill Guidance Tests ---"
+echo ""
+
+# Test: skill explicitly warns against unsafe bare $ARGUMENTS shell expansion
+if grep -Fq 'Never run this unsafe form' "$ASK_CODEX_SKILL" && grep -Fq '"${CLAUDE_PLUGIN_ROOT}/scripts/ask-codex.sh" $ARGUMENTS' "$ASK_CODEX_SKILL"; then
+    pass "skill warns against bare \$ARGUMENTS shell expansion"
+else
+    fail "skill warns against bare \$ARGUMENTS shell expansion" "explicit unsafe-form warning" "missing"
+fi
+
+# Test: skill documents the safe quoted simple invocation
+if grep -Fq '"${CLAUDE_PLUGIN_ROOT}/scripts/ask-codex.sh" "$ARGUMENTS"' "$ASK_CODEX_SKILL"; then
+    pass "skill quotes the question when no flags are present"
+else
+    fail "skill quotes the question when no flags are present" "quoted simple invocation" "missing"
+fi
+
+# Test: skill explains that free-form text must be a quoted final argument
+if grep -Fq 'one quoted final argument' "$ASK_CODEX_SKILL"; then
+    pass "skill requires one quoted final argument for free-form text"
+else
+    fail "skill requires one quoted final argument for free-form text" "quoted final argument guidance" "missing"
+fi
+
 # ========================================
 # Summary
 # ========================================