How to use the Auto Paper Improvement Loop agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to carry out a specific task, which tools it may use, and when to apply the procedure. This skill's SKILL.md is named auto-paper-improvement-loop.

After a paper has been generated and compiled, the skill makes the agent send it to an external AI reviewer (GPT-6-Astra via Codex MCP), implement the suggested writing fixes, and recompile the paper. It runs two review-fix-recompile rounds automatically and logs each round to a file in the paper folder. It targets writing quality such as theoretical inconsistencies, overclaims, missing content and presentation. It does not run new experiments.

• Input: a compiled paper directory produced by the paper-writing workflow.
• Output: the edited paper plus a cumulative log file named PAPER_IMPROVEMENT_LOG.md in the paper directory.
• Reviewer: GPT-6-Astra at xhigh effort via the Codex MCP tool (mcp__codex__codex), or another configured reviewer backend.
• Each review round uses a fresh reviewer thread rather than continuing the previous conversation.

Install the skill

Option 1: download the ZIP from the skill's page on this directory and unzip it into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder so that it applies only to that project.

Option 2: in the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install path: ~/.claude/skills/
• Project install path: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Set up the external reviewer before you run it

The review step depends on an external reviewer. The skill expects Codex MCP (mcp__codex) with access to the gpt-6-astra reviewer model, or another reviewer backend you have configured. If the reviewer is not available, the review step will not run.

The skill also needs a LaTeX toolchain or other compile step so it can recompile the paper after each round. Its allowed tools include Bash, Read, Write, Edit, Grep, Glob and Skill, along with the reviewer tools listed in its frontmatter.

• Codex MCP with access to gpt-6-astra, or another configured reviewer backend
• Claude Code or a compatible agent that provides the listed tools
• A compile step for your paper (LaTeX toolchain is implied by the compile workflow)
• Optional: python3 and the extract_paper_style.py helper, only if you use the style-ref option

Trigger the skill with a natural request

You can ask for the skill in plain language. The description lists these trigger phrases: 改论文, improve paper, 论文润色循环, auto improve, and requests to iteratively polish a generated paper.

You can also invoke it directly and pass the paper directory as the argument. The argument-hint is [paper-directory] followed by optional flags.

• "Improve paper in paper/ with the auto improvement loop."
• "Auto improve my generated paper."
• "Polish this compiled draft iteratively."
• "改论文" or "论文润色循环" with the paper folder named

Optional settings: human checkpoint, style reference and edit whitelist

HUMAN_CHECKPOINT is false by default, so the loop runs without stopping. When set to true, the loop pauses after each round's review to show the score and weaknesses, and you can approve fixes, give custom instructions, skip fixes or stop early.

The style-ref option lets you steer structural fixes only (section ordering, paragraph length, figure density) toward a reference paper. Accepted sources are a local TeX directory or file, a local PDF, an arXiv id, or an http(s) URL. Overleaf URLs and IDs are rejected; clone the project with /overleaf-sync setup first and pass the local path. Style reference material is never sent to the reviewer.

The edit-whitelist option restricts which files the fix step may touch. Rejected edits are logged to PAPER_IMPROVEMENT_LOG.md rather than silently dropped.

• Human checkpoint: /auto-paper-improvement-loop "paper/" — human checkpoint: true
• Style reference: add — style-ref: <source> to the request
• Edit whitelist: add — edit-whitelist <path> (the alias — edit_whitelist is also accepted)

Examples of what a run looks like

A typical run starts from a compiled draft. The agent sends the artifact to the reviewer, receives critique, applies the writing fixes it judges appropriate, recompiles, and records the round in the log. This repeats for two rounds, after which the loop stops.

Because the skill fixes writing rather than data, a good target is a draft whose results are already fixed and whose weaknesses are about clarity, claims or missing explanation.

• Round 1: the reviewer finds an overclaim in the introduction; the agent softens it and recompiles.
• Round 2: the reviewer flags unclear figure presentation; the agent adjusts the text and recompiles.
• Afterwards, you read PAPER_IMPROVEMENT_LOG.md to see every review and change.

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its allowed tools include Bash(*), so the agent can run shell commands, and the reviewer step sends your paper to an external reviewer service. Check the reviewer you have configured before you use the skill on unpublished work.

Only the reviewer sees the paper artifact and your prompt. The style reference material is kept away from the reviewer by design.

• The skill runs scripts (Bash) and makes network calls to the external reviewer.
• Read the SKILL.md before installing and confirm you trust the reviewer backend.
• Do not send confidential or unpublished material to a reviewer service you have not approved.

Tips for better results

Start from a draft that has already been compiled and reads reasonably well. The loop polishes writing; it does not add results.

Read the log after each run. Automated edits can introduce errors or overclaims, so check numbers, citations and claims yourself.

• Use the research loop instead when the paper needs new experiments or data.
• Turn on the human checkpoint if you want to approve each round's fixes.
• Keep your original draft under version control so you can compare changes.
• Do not run the skill on a timer or inside /loop; each run already contains its own two rounds.