agentleFS
ethosagentethosagent/ethos/.agents/skills/openai-reviewer/SKILL.md

openai-reviewer

Skill23 starsChanged 13 days agoMITView on GitHub

Run OpenAI Codex CLI as the code reviewer; Claude writes, Codex reviews, never self-review. Invoke for ALL review requests ("review", "check it", "look it over", "code review") and after any non-trivial code. The Stop hook also calls it.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All reviews go through this skill: When the user asks for any kind of review — explicit ("review this", "code review") or implicit ("check …

    line 11
  2. Distinctive:

    Before calling Codex, scan your own diff for things you would have caught yourself:

    line 16
  3. Very specific:

    Add --focus <security|performance|correctness|style|test> to narrow scope.

    line 51
  4. Very specific:

    Project rules in CLAUDE.md take precedence over Codex: If Codex demands an ethos-violating change (error handling for impossible …

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

OpenAI Code Review

Routing rule (hard)

All reviews go through this skill. When the user asks for any kind of review — explicit ("review this", "code review") or implicit ("check it", "look it over") — go through the two-pass flow below.

Two-pass review flow

Pass 1 — Self-review (Claude, fast): Before calling Codex, scan your own diff for things you would have caught yourself:

  • Typos, dead code, unused imports/variables
  • Lint and typecheck violations (run pnpm lint / pnpm typecheck if changes are non-trivial)
  • Ethos rule violations: error handling for impossible cases, abstractions for single-use code, speculative flexibility, comments restating what the code does
  • Tests missing for new behavior

Fix everything you find. Only then move to Pass 2.

Pass 2 — Codex review (architectural, 5-year horizon): Invoke openai-review. Codex looks for what you cannot easily see in your own work: brittle abstractions, hidden coupling, API choices that will be hard to evolve, premature flexibility, things that rot under scale or team turnover.

The split exists because LLM self-review is unreliable for the things you wrote yourself. Pass 1 catches mechanical issues; Pass 2 brings an outside perspective.

Style

Reviews run in the voice of Linus Torvalds, focused on what will break in 5 years:

  • Brittle abstractions and architectural foot-guns
  • Hidden coupling that surprises future maintainers
  • API choices that will be hard to evolve
  • "Cleverness" that obscures intent
  • Premature flexibility / speculative generality

The script bakes this framing into every Codex call.

Modes

openai-review defaults to uncommitted if no mode is given.

ModeWhen to use
uncommittedActive coding — staged + unstaged changes (default)
last-commitReview the latest commit only
against-mainWhole branch + uncommitted vs. main
against-originUnpushed commits vs. origin

Add --focus <security|performance|correctness|style|test> to narrow scope.

Acting on findings

Codex returns JSON. Apply judgment — not every finding is correct.

SeverityAction
critical, highFix
mediumJudgment call — fix unless it conflicts with project rules
lowUsually skip; surface to user only if relevant

Project rules in CLAUDE.md take precedence over Codex. If Codex demands an ethos-violating change (error handling for impossible scenarios, abstractions for single-use code, speculative flexibility), ignore it and explain why in one line.

Auto-loop (Stop hook)

A Stop hook runs openai-review against-main after every code-writing turn:

  • Approved (no critical/high) → turn ends cleanly
  • Issues + iteration < 2 → review fed back into your context, you continue fixing
  • Iteration cap (2) hit → remaining issues surfaced to user, turn ends

Override the loop for a turn with SKIP_CODEX_REVIEW=1 in the environment, or by user explicitly saying "ship it" / "skip review".

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.