codex-review
Use when the user asks to review a branch, PR or diff with codex ("review this with codex", 用 codex 审一下, "codex review PR N"). Runs `codex exec` from the shell with a hand-written, repo-aware prompt; falls back to one OpenRouter GPT call only when codex is out of quota. Covers the invocation contract and the failure modes that make codex look dead or silently produce no report.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 76
- Forks
- 17
01 前言 Front Matter
- name
- codex-review
- description
- Use when the user asks to review a branch, PR or diff with codex ("review this with codex", 用 codex 审一下, "codex review PR N"). Runs `codex exec` from the shell with a hand-written, repo-aware prompt; falls back to one OpenRouter GPT call only when codex is out of quota. Covers the invocation contract and the failure modes that make codex look dead or silently produce no report.
02 资源文件 1
- 脚本openrouter_review.py4.2 KB
03 SKILL.md 正文
Codex review
"Review with codex" means codex exec from the shell, with a prompt you write yourself that knows this repo. Do not substitute a subagent of your own model or a generic built-in review command: the point is a second model family reading the diff against this repo's own invariants.
Invocation
codex exec -C <repoDir> -s read-only -c approval_policy="never" \
--output-last-message "$TMPDIR/codex_review.txt" "$(cat "$TMPDIR/prompt.txt")" </dev/null
Read the report from the --output-last-message file.
Four ways this fails silently
- End with
</dev/null. It forces stdin to EOF at once. Backgrounded without it, codex waits forever. - Never pipe codex's stdout. A pipe makes it think stdin is wanted; it hits EOF, exits 0, and never writes the
--output-last-messagefile. For a log, redirect:> log 2>&1 </dev/null. - Run it in the foreground. Backgrounded with
> file, the output is buffered and the file sits at one line, which looks like a hang. -s read-onlyneeds-c approval_policy="never". Without it, a session with no TTY waits for an approval that never comes.
Writing the prompt
Inline the diff and forbid exploring: "Do NOT explore the repository, do NOT open files, do NOT run commands. Review only the diff inlined below."
Four parts:
- Stack facts it needs. Module layout, the database and its migration discipline, earlier behaviour the diff relies on without restating. codex cannot see the repo; anything load-bearing goes here.
- What the change should do. One paragraph, so it reviews against intent instead of guessing it.
- Numbered review targets that are this diff's own invariants. "Does X hold on every path", "does anything change Y without going through Z". This is where the value is; a generic checklist is not.
- Output discipline. Concrete defects only, with
file:lineand the input or sequence that triggers each one, ranked by severity; one line per clean target; no summary of the diff, no praise.
The diff: git diff {{BASE_BRANCH}}...HEAD -- {{REVIEW_GLOBS}}.
Fallback: OpenRouter (optional, billed per call)
Only when codex exec exits on a usage limit (its log ends with "You've hit your usage limit" and the output file is never written). Send the same prompt as one call:
set -a && . {{OPENROUTER_ENV_FILE}} && set +a && \
python3 <this skill's directory>/openrouter_review.py --prompt "$TMPDIR/prompt.txt" --out "$TMPDIR/review.md"
- One call per review. The script re-sends the same request only on a 5xx, a timeout or a connection failure, at most twice. If the result is weak, stop and give it to the user; never rewrite the prompt and run again on your own.
- Before use, list
https://openrouter.ai/api/v1/modelsforopenai/gpt-*; pass--modelwhen a newer flagship exists. - Never print the key.
- Report it as what it is: codex did not run; GPT through OpenRouter did.
Reading the result
codex reports existing behaviour as a finding when the diff makes it visible. Decide deliberately: fixing the visibility belongs in this change; fixing the old quirk itself is often a separate decision with its own blast radius. Say which one you are doing and record the other.
Rule
The reviewer model must differ from the model that wrote the change.
04 同仓库更多 Skills
doc-review
Use when reviewing docs in this repo (team version).
zh-hant-converter
Use when Simplified Chinese text needs a Traditional Chinese version — internal team docs converted with opencc s2hk, or a product's Simplified Chinese UI copy mirrored into its Traditional Chinese locale — or when the user says 转繁, 同步繁体, or "convert to zh-Hant".
cleaning-dev-caches
Use when this Mac's disk is nearly full, or the user asks to clear re-downloadable caches (「清缓存」「硬盘满了」, "clear caches") — Homebrew, npm / pnpm / yarn / bun / uv / pip, Gradle, Playwright browsers, Edge and VS Code updater caches, simulator dyld caches, unused Rust toolchains. Not for build output (cleaning-dev-build-artifacts) or personal files.
cleaning-dev-build-artifacts
Use when this Mac's disk is nearly full, or the user asks to clean build output — Rust target/ dirs or Claude Code worktrees (.claude/worktrees) under {{DEV_ROOT}} (「清编译产物」「清 target」「清 worktree」「硬盘满了」, "clean build artifacts"). Not for package-manager or app caches (cleaning-dev-caches) or personal files.
ios-keyboard-page-shift
Use when, on iPhone Safari or an iOS WebView, a page or a full-screen app shell (top bar, scrolling list, bottom input) moves up when a text field is focused and stays up after the keyboard closes, leaving the top bar off-screen, the input mid-screen and an empty band below it, or when an earlier fix for that symptom did not hold.
doc-review
Use when a document for people to read has been fact-checked and polished and is one step from being pushed or published — the last gate before `git push` — or when the user asks for a final review (终审).