Guide · Agent skill
How to use the research-review agent skill for external AI review
Updated · written with AI from the project's own documentation and checked against our catalogue data
research-review is an agent skill that asks a separate AI reviewer to critique your research ideas, paper drafts or experimental results. It is written for researchers who want a harsh second opinion before submission, and for teams that want a cross-model review instead of one AI's judgement. After this guide you will know what the skill does, how to install it, how to trigger it with a normal request, and what it sends and needs.
Research Review via External Reviewerwanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill Quick start
- 1Download and unzip. Download the research-review ZIP from this page and unzip it. Keep the SKILL.md file inside the skill folder.
- 2Place the skill folder. Copy the folder to ~/.claude/skills/ for all projects, or to .claude/skills/ in one project. In the Claude apps, upload it under Settings → Capabilities → Skills instead.
- 3Add the Codex MCP server. Run the claude mcp add codex command shown above, pointing at your ARIS clone, so Claude Code can reach the default reviewer.
- 4Confirm reviewer access. Make sure you have credentials for the reviewer you will use, such as OpenAI for Codex.
- 5Ask for a review. Make a plain request such as 'review my research' and name the scope, for example a paper section or a results folder.
- 6Continue across rounds. After you revise the work, ask for another round so the agent continues the same reviewer thread.
What is an agent skill, and what does research-review make the agent do?
An agent skill is a folder containing a SKILL.md file that tells a compatible AI agent how to perform a specific task. The skill's description tells the agent when to use it, so you can often just ask for the task in plain language.
When research-review is installed, the agent gathers your research notes, drafts and results into a briefing file. It then sends that briefing to a separate AI reviewer, by default OpenAI Codex, or a Gemini, Grok, Claude Code or manual route you choose. The reviewer is told to act like a strict ML conference reviewer and to look for logical gaps, missing experiments, weak narrative and whether the contribution is strong enough for a top venue.
- Reads project narrative documents such as STORY.md, README.md or paper drafts
- Reads memory or notes files for key findings and experiment history
- Identifies core claims, methodology, key results and known weaknesses
- Writes the full briefing to RESEARCH_REVIEW_REQUEST.md and points the reviewer at that file
- Can continue the same reviewer thread across rounds
Install research-review in Claude Code or the Claude apps
Download the ZIP from the skill's page on this directory and unzip it. For Claude Code, place the skill folder in ~/.claude/skills/ to make it available everywhere, or in a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/ (available in all projects)
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Set up the default Codex reviewer
The default backend is Codex, which reaches the reviewer through the Codex MCP server. Before the first review, add that server to Claude Code. The command below comes from the skill's prerequisites. Replace the path with the location of your own ARIS clone.
You also need access and credentials for the reviewer you choose, for example an OpenAI account for Codex. The skill does not provide these.
claude mcp add codex -s user -- python3 "$HOME/aris_repo/mcp-servers/codex-exec/server.py"How do you trigger research-review with a natural request?
You do not need a special command. Ask in plain language, and the agent should match the skill's description. The skill's description lists these trigger phrases: 'review my research', 'help me review', and 'get external review'. You can also ask for critical feedback on research ideas, papers or experimental results.
The skill's argument hint is [topic-or-scope], so you can name the part of the work you want reviewed. To choose a non-default reviewer, the skill's source says the agent resolves a reviewer selection from your request, from a project file at .aris/reviewer.json, and then from the default.
- 'Review my research on sparse attention for a NeurIPS submission.'
- 'Help me review the results in experiments/ablation_v3 before I write the rebuttal.'
- 'Get external review of my paper draft, focusing on the methodology section.'
What happens during a review round?
The first round sends a prompt with the briefing file to the reviewer. The prompt asks the reviewer to find where the work is broken, using four questions: logical gaps or unjustified claims, missing experiments, narrative weaknesses, and whether the contribution is sufficient for a top venue. The skill tells the reviewer to verify referenced files itself rather than trust the author's notes.
Follow-up rounds reuse the reviewer thread so the reviewer keeps context from earlier rounds. Your own changes and new experiments can then be reviewed against the earlier critique.
- Round 1 starts a new review thread
- Later rounds continue the same thread
- The skill's source says an unavailable selected reviewer does not silently fall back to another one
What are the safety and cost notes?
This skill runs scripts and uses the network. The briefing is transmitted to the reviewer backend you choose, so do not use it for confidential or unpublished work you do not want sent to a third-party AI service. The skill is also slow and token-expensive, so it is not suited to quick proofreading or grammar checks.
The skill's source warns not to wrap it in /loop, /schedule or CronCreate. Repeated timed runs re-fire the verdict without giving the reviewer memory of earlier rounds. If you want a review after work finishes, schedule the waiting step and run the review once.
- Briefings are sent to the chosen external reviewer
- Requires credentials for that reviewer
- Do not run it on a timer or schedule
What people use it for
- Getting a harsh pre-submission critique of a paper draft from a reviewer that did not write it
- Checking whether experimental results support the claims before a rebuttal or resubmission
- Comparing critiques from different reviewer backends to avoid relying on one AI's judgement
Frequently asked questions
How do I install the research-review skill?
Download the ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for all projects, or in .claude/skills/ inside one project. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
What do I need to run research-review?
You need Claude Code or another SKILL.md-compatible agent, and access and credentials for your chosen external reviewer. For the default Codex backend, you also need the Codex MCP server added to Claude Code with the python3 command shown in this guide.
Is research-review free, and what is its licence?
The skill is listed under the MIT licence. The source does not state prices for the reviewer services, so check your reviewer provider's terms, since the skill is noted as token-expensive.
Which AI reviewers can research-review use?
The default is OpenAI Codex. The skill also supports Gemini, Grok, Claude Code, and a manual route you choose. Each one needs its own access and credentials.
Why does my review fail or not start?
Check that the selected MCP server is available in Claude Code, since the skill needs it for the chosen backend. The skill's source says an unavailable selected route does not silently fall back to another reviewer, so fix the selected one or choose a different route.
How is this different from a grammar checker or a single AI review?
It is built for deep methodological critique, not proofreading. It sends the work to a separate reviewer model, which gives a cross-model second opinion, though this means your briefing leaves your machine.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use research-review if you want a strict, multi-round critique of a paper or results from a reviewer outside your usual AI, and you are comfortable sending the briefing to that service. Skip it for quick proofreading, for confidential work you cannot share with a third party, or when you need a fast answer.
Download the skill