How to use the research-review agent skill for critical feedback

What the research-review skill makes the agent do

A skill is a folder with a SKILL.md file that tells an AI agent how to handle a particular kind of task. When this skill is installed and triggered, the agent gathers your research notes, drafts, and results, then sends them to a separate reviewer. By default the reviewer is a fresh Codex agent, but Gemini, Grok, or Claude Code can be selected instead. The reviewer is instructed to act as a tough senior ML reviewer and to look for where the work is broken.

The agent then answers the criticisms over several rounds, narrows down the core claims and the experiments needed to support them, and saves the outcome as a review document. That document includes a claims matrix and a prioritized TODO list.

Install the research-review skill

There are two ways to install it. For Claude Code, download the ZIP from this page and unzip it into ~/.claude/skills/ for a personal install, or into .claude/skills/ inside a specific project if you want it only there. In the Claude apps, you can upload the ZIP instead under Settings → Capabilities → Skills.

The skill source is a single SKILL.md file. It also refers to reviewer_route.py and a shared reviewer-backends.md contract that come from the wanshuiyin/Auto-claude-code-research-in-sleep repository, so the skill is not fully self-contained. Check that those files are available in your repository before you rely on it.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ in your project root
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what you need before the first review

The skill needs a selected review tool to be available. For the default route, that means Codex, using the spawn_agent and send_input tools, and access to an OpenAI model such as gpt-6-astra. For Gemini, Grok, or Claude Code, the skill uses an MCP route instead. The skill also needs reviewer_route.py and the reviewer-backends.md contract from the repository.

If the selected reviewer is unavailable, the skill records REVIEW_UNAVAILABLE. It does not fake a pass, and the agent reviewing its own work does not count as a fresh reviewer.

• A review tool: Codex (spawn_agent, send_input) or an MCP route for Gemini, Grok, or Claude Code
• Access to an OpenAI model such as gpt-6-astra for the default Codex reviewer
• reviewer_route.py and reviewer-backends.md from the repository

Trigger the skill with natural requests

You do not need a special command. Describe what you want in ordinary words. The skill is designed to start on phrases such as 'review my research', 'help me review', or 'get external review', and also when you ask for critical feedback on research ideas, papers, or experimental results.

Give the agent the context it needs. The skill asks it to read project narrative documents such as STORY.md or README.md, any memory or notes files, and paper drafts, then identify the core claims, methodology, key results, and known weaknesses before the reviewer is called.

• 'Review my research on the sparse attention results in notes/ and tell me what is missing.'
• 'Get external review of this draft before I submit to the venue.'
• 'Please write a mock NeurIPS review with scores for paper.md.'

Run a review and read the output

The first round sends a detailed prompt to the reviewer that asks it to find logical gaps, missing experiments, narrative weaknesses, and whether the contribution is sufficient for a top venue. The example in the source uses the reasoning effort setting ultra for the Codex reviewer.

After that, the agent responds to criticisms with evidence, asks targeted follow-up questions, and requests deliverables such as experiment designs or a results-to-claims matrix. It stops when both sides agree on the core claims and evidence requirements, a concrete experiment plan exists, and the narrative structure is settled. The full interaction and conclusions are then saved to a review document in the project root, and the project notes are updated.

• Round-by-round summary of criticisms and responses
• Final consensus on claims, narrative, and experiments
• Claims matrix showing which claims are allowed under each possible outcome
• Prioritized TODO list with estimated compute costs

Understand safety, data sharing, and reviewer independence

This skill runs scripts and uses the network. Your research content is shared with the reviewer service, so it leaves your machine. Do not use it on confidential or unpublished work that you are not willing to send to third-party model providers.

The default Codex reviewer is from the same model family as the agent that runs the skill. The skill records it as review_independence: same-family and acceptance_status: provisional. A cross-family result can only be recorded as accepted after a completed, in-scope review by a reviewer from a different model family. Agreement between models alone does not establish that.

• Content is sent to the reviewer service, so avoid confidential or unpublished material you cannot share
• Default Codex reviews are same-family and provisional
• The reviewer's output still needs your own judgement

Tips for getting useful feedback

Give the reviewer the primary artifacts, such as raw results files and the paper draft, and ask it to read them and check the claims itself. The skill asks for artifact-grounded verification, and an unreadable file counts as missing evidence. Be specific about what you want examined, because a vague request produces vague criticism.

Treat the output as a list of things to check, not a verdict. Respond to each criticism with evidence or a counterargument, and ask follow-ups on the points that matter most, such as the minimum experiment that would answer a concern.

• Name the specific claims and questions you want tested
• Point to raw result paths so the reviewer can verify them
• Ask 'what is the minimum experiment to satisfy concern Z?' for actionable follow-up