Gemini Delegate Skill

You are Claude acting as a supervisor. You plan, evaluate, and review. Gemini does the CJK/Chinese writing.

⛔ CRITICAL: Shell Compatibility (READ FIRST)

Claude Code's Bash tool runs git-bash (Unix shell) on Windows — NOT cmd.exe, NOT PowerShell.

NEVER use these CMD-only commands in Bash:

❌ BANNED (cmd.exe only)	✅ Use instead (bash)
cd /d C:\path	cd /c/Users/wenyu/path or cd "$HOME/path"
type file.txt	cat file.txt
dir	ls
copy src dst	cp src dst
del file	rm file
md dir	mkdir -p dir
set VAR=value	export VAR=value
%VAR%	$VAR or ${VAR}
ren old new	mv old new
cls	clear

Path format in Bash

• Windows: C:\Users\wenyu\mispricing-engine → Bash: /c/Users/wenyu/mispricing-engine or ~/mispricing-engine
• NEVER use backslashes \ in bash paths — always use forward slashes /
• NEVER use cd /d — this is CMD syntax and WILL fail in bash

When to use PowerShell

Only use PowerShell syntax (with powershell code fence) when calling .ps1 scripts directly via Desktop Commander or Windows-MCP. All other code blocks in this skill use Unix bash.

When to Delegate to Gemini

Delegate to Gemini (good for)

• Traditional Chinese content (reports, analyses, social media posts)
• 美洲更新 (Americas Update) weekly Threads series
• CJK translation with domain-specific terminology
• Chinese-language summaries of English analysis
• Any content requiring native-quality Chinese output
• Long-form Chinese writing (>200 characters)

Keep in Claude (bad for Gemini)

• Architecture decisions, code review, debugging
• English-only content
• Tasks requiring conversation history or memory context
• Security-sensitive operations
• Multi-step workflows with complex dependencies
• Code generation (Gemini's coding is weaker)

Core Workflow: Context File Pattern

Step 1: Claude writes the context file

Save to .ai/gemini_task_<name>.md in the repo:

# Task: <descriptive name>

## Context
- Repo: ~/mispricing-engine
- Key files to read: <list paths>
- Output file: <where to write result>

## Language
- Output language: Traditional Chinese (繁體中文)
- Tone: <formal/casual/hedged-framework-driven>
- Audience: <target audience>

## Instructions
<Clear, step-by-step instructions in English or Chinese>

## Constraints
- Do not modify files outside the listed paths
- Follow existing terminology conventions
- Use hedged language for market predictions (per feedback_threads_tone)

## Output
- Save output to <path>

Step 2: Launch Gemini (synchronous, from Claude Code Bash)

# Direct synchronous call
bash .claude/skills/gemini-delegate/scripts/run_gemini.sh \
  --prompt "Read .ai/gemini_task_<name>.md and execute all instructions inside." \
  --log-file .ai/gemini_log_<name>.txt

Or call the PowerShell script directly:

# From PowerShell only (NOT from Claude Code Bash)
& "C:\Users\wenyu\mispricing-engine\.claude\skills\gemini-delegate\scripts\run_gemini.ps1" `
    -Prompt "Read .ai/gemini_task_<name>.md and execute all instructions." `
    -LogFile "C:\Users\wenyu\mispricing-engine\.ai\gemini_log_<name>.txt"

Step 3: Check result

# Check for fallback sentinel first
if [ -f ".ai/gemini_log_<name>.txt.fallback_claude" ]; then
    echo "Quota exceeded — doing task myself"
elif [ -f ".ai/gemini_log_<name>.txt.done" ]; then
    cat ".ai/gemini_log_<name>.txt"
fi

Step 4: Claude reviews

• Read the output
• Check Chinese quality (terminology, tone, accuracy)
• Verify sensitive word replacements (per feedback_thread_sensitive_words)
• If 80%+ correct: fix remaining issues directly
• If fundamentally wrong: rewrite context file and re-run

Script Parameters

run_gemini.sh

Parameter	Default	Description
--prompt	(required)	Task prompt
--repo	~/mispricing-engine	Working directory
--model	gemini-2.5-pro	Gemini model
--log-file	<repo>/.ai/gemini_output.txt	Log file path
--verify-file	(none)	File that must exist + be non-empty after run (repeatable)
--verify-sentinel	(none)	String that must appear in every --verify-file

run_gemini.ps1

Parameter	Default	Description
-Prompt	(required)	Task prompt
-Repo	C:\Users\wenyu\mispricing-engine	Working directory
-Model	gemini-2.5-pro	Gemini model
-LogFile	<Repo>\.ai\gemini_output.txt	Log file path
-VerifyFile	@()	File(s) that must exist + be non-empty after run (array)
-VerifySentinel	""	String that must appear in every -VerifyFile

Sensitive Word Replacements (Threads v4)

When generating Threads posts, apply these replacements:

• Check feedback_thread_sensitive_words memory for current list
• Common replacements: avoid absolute predictions, use hedged framework-driven language
• Never use "一定", "保證", "必然" — use "可能", "傾向", "框架顯示"

Important Caveats

• Gemini has NO persistent memory — always give full context via file paths
• Gemini cannot read conversation history — summarize decisions in the context file
• Gemini's coding ability is weaker than Claude/Codex — do NOT delegate code tasks
• Always verify Gemini output for factual accuracy before publishing
• The .ai/ directory is gitignored — safe for task files and logs
• If .fallback_claude sentinel appears, do the task yourself immediately

⚠️ Non-interactive invocation: three critical rules

These three rules apply to every non-interactive Gemini CLI run (both
run_gemini.sh and run_gemini.ps1 in this skill already handle them
correctly; call them out explicitly if you are writing your own wrapper).

1. Gemini CLI has NO -C <dir> flag

-C is Codex CLI syntax. Gemini CLI uses the current working directory
as its workspace, plus anything listed in --include-directories. If
you try gemini -C /path/to/repo ... you get a cryptic argument error.

Correct pattern: cd / pushd into the target repo before invoking
Gemini, then cd / popd back afterwards.

# Bash
pushd "$REPO" > /dev/null
gemini --approval-mode yolo < prompt.txt
popd > /dev/null

# PowerShell
Push-Location $Repo
try {
    Get-Content $promptFile -Raw | & gemini --approval-mode yolo
} finally {
    Pop-Location
}

2. Always pass --approval-mode yolo

Gemini CLI's default approval mode prompts the user for each tool call.
In non-interactive mode (piped stdin, no TTY) there is no way to
approve, so tool calls are silently dropped — and Gemini falls back to
emitting write_file(...) as pseudo-code comments in its text output
instead of actually writing files. This looks like a planning log
rather than an execution failure, which is why it is hard to debug.

If you see Gemini output containing commented-out Python blocks like:

# I will construct the builder.py file content.
# print(default_api.write_file(file_path='...', content='...'))
# This requires writing the *entire* file.

you are hitting this bug. Fix: add --approval-mode yolo to the
gemini command (or use -y, which is the alias).

3. Pipe large prompts via stdin, not positional args

Windows cmd.exe has a ~32 KB command-line length limit. If you pass a
large prompt as a positional argument (e.g. gemini "$(cat brief.md)")
and the brief exceeds ~32 KB, the invocation fails with "Argument list
too long" in git-bash or silently truncates on Windows.

Correct pattern: write the prompt to a file, pipe it via stdin:

gemini --approval-mode yolo < prompt.txt

Both wrapper scripts in this skill already do this.

How the old pattern failed

Versions of run_gemini.sh and run_gemini.ps1 before the fix used:

gemini -m "$MODEL" -C "$REPO" "$(cat "$PROMPT_FILE")"

That had all three bugs: unknown -C flag, missing --approval-mode yolo, and positional arg instead of stdin. On tasks larger than a few
KB with files outside the session CWD, every tool call was silently
dropped and the output looked like planning comments.

---

⚠️ FOURTH RULE (added 2026-04-17): Verify file writes after Gemini exits

Even when the three rules above are followed and Gemini exits cleanly (rc=0), expected output files may be missing or partial on disk. Two failure modes observed in production use of Gemini CLI 0.37+:

Failure mode 1 — write_file: params must have required property 'file_path'

Gemini occasionally hits an internal tool-schema mismatch on the second or later write_file call within a single invocation. Symptom in stderr:

Error executing tool write_file: params must have required property 'file_path'

The first write_file call usually succeeds before this happens, so you might end up with partial deliverables — first file written, subsequent files missing — and Gemini still exits 0 because the error was caught internally.

Failure mode 2 — silent partial writes

Gemini can decide to "abandon" a write halfway through (rate-limit retry, model decided to re-plan) and the file ends up on disk with bad indentation, missing imports, or truncated mid-function. Process exits 0 with no stderr signal.

The fix: post-execution verification

ALWAYS check expected output files exist on disk + are non-empty + contain a sentinel string after gemini exits, regardless of stderr. Treat Gemini's exit code as advisory, not authoritative.

Bash pattern:

EXPECTED_FILES=(
    "docs/output1.md"
    "docs/output2.md"
)
SENTINEL="## My Required Heading"  # something that MUST appear in the output

cat brief.md | gemini --approval-mode yolo
GEMINI_RC=$?

# Verification (run regardless of exit code)
for f in "${EXPECTED_FILES[@]}"; do
    if [[ ! -s "$f" ]]; then
        echo "VERIFICATION FAILED: $f missing or empty" >&2
        exit 1
    fi
    if ! grep -q "$SENTINEL" "$f"; then
        echo "VERIFICATION FAILED: $f missing sentinel '$SENTINEL'" >&2
        exit 1
    fi
done
echo "All ${#EXPECTED_FILES[@]} files verified."

This skill's wrapper scripts (scripts/run_gemini.sh + .ps1) include a --verify-file PATH flag that does this check automatically — see those scripts for the canonical implementation.

Translation-quality caveat (also 2026-04-17)

When Gemini IS invoked correctly and DOES write the file successfully, the content quality for translation tasks is B-grade at best:

• Banned-words lists in the brief are routinely ignored
• Tone is consistently "translated-from-English" — not native target-language idiom
• Terminology drift across files even when the brief asks for consistency
• Dates in changelogs are wrong (Gemini guesses based on training, doesn't read system date)

Workflow that works for translation:

1. Use Gemini for first-draft generation (saves Claude ~60% of typing time)
2. Claude reviews EVERY translated file: banned-words audit, terminology consistency check, line-by-line accuracy spot-check
3. Claude rewrites the worst ~25% of lines manually
4. Run with --verify-file to catch missing/empty outputs immediately

Don't ship Gemini's translation output as final without Claude polish. Cost savings vs Claude-direct translation are real but modest; quality without polish is not production-grade.