Guide · Agent skill
How to use the Research Refine agent skill (research-refine)
Updated · written with AI from the project's own documentation and checked against our catalogue data
Research Refine is an agent skill that takes a research problem you already care about, but whose technical approach is still fuzzy, and works it into a concrete, minimal method plan. It is written for researchers, students drafting a paper method, and teams that want a documented record of how a plan changed. After this guide you will know what the skill does, how to install it, how to phrase a request that triggers it, and what it needs to run.
Research Refinewanshuiyin/Auto-claude-code-research-in-sleep · MIT Download the skill Quick start
- 1Download and install. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 2Confirm the reviewer is reachable. Make sure a reviewer backend such as Codex MCP is configured and that the gpt-6-astra model or an equivalent is accessible.
- 3Prepare your inputs. Write one or two sentences describing the research problem and your rough approach. Optionally gather up to 15 local papers or notes to ground the work.
- 4Ask in natural language. Use a trigger phrase such as 'refine my approach' or '帮我细化方案', followed by your problem and approach.
- 5Let the review loop run. The agent freezes the problem anchor, drafts a method, gets reviewer feedback, and revises until the score reaches 9 or five rounds pass.
- 6Read the saved output. Open refine-logs/FINAL_PROPOSAL.md for the plan, and the round files for how it changed.
What is an agent skill, and what does research-refine make the agent do?
An agent skill is a folder containing a SKILL.md file that tells a coding or research agent how to carry out a specific kind of task. When installed, the agent reads that file and follows its workflow when a request matches the skill's description.
The research-refine skill turns a vague research direction into a problem-anchored method plan. It first freezes the original problem as a fixed anchor, scans grounding papers, proposes the smallest adequate method, and sends the draft to an external reviewer model named GPT-6-Astra, reached through an MCP connection. The agent then revises the plan and repeats until the reviewer's score reaches 9 or five rounds have passed.
- Freezes an immutable Problem Anchor that is reused in every round
- Prefers the minimal intervention that fixes the main bottleneck
- Aims for one dominant contribution plus at most one supporting contribution
- Uses modern methods (such as LLM, VLM, diffusion, RL) only where they fit the bottleneck
Install the research-refine skill
Download the ZIP of the skill from this page. The skill is distributed as a folder whose main file is SKILL.md.
For Claude Code, unzip the folder into ~/.claude/skills/ to make it available in all your projects, or into a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
Set up the reviewer connection before you start
The core loop depends on an external reviewer. The skill's default reviewer is the model gpt-6-astra, used through Codex MCP. The skill also lists other configured reviewer backends: mcp__codex, mcp__antigravity, mcp__grok, or mcp__claude-review. You need one of these configured and reachable, or an equivalent reviewer.
The skill file does not describe a fallback if no reviewer is available, so plan on having the MCP connection working before you begin.
- Reviewer backend: Codex MCP or another configured option (mcp__codex, mcp__antigravity, mcp__grok, mcp__claude-review)
- Reviewer model: access to gpt-6-astra or an equivalent configured reviewer
- Optional: WebSearch and WebFetch access for grounding papers
- Optional: a local folder of papers or notes, up to 15 files, for grounding
Trigger the skill with a natural request
The skill activates when your request matches its description. The description lists phrases such as 'refine my approach', 'decompose this problem', 'refine research plan', and their Chinese equivalents '帮我细化方案', '打磨idea', and '细化研究方案'. You can also ask for a concrete method that stays simple and focused rather than vague or overbuilt.
Give the agent both the problem and your current rough approach, separated clearly. The skill's own argument format is 'problem | approach'.
- Example: 'Refine my approach: I want to reduce hallucination in long-document QA, and my idea is a retrieval step plus a verifier.'
- Example: '帮我细化方案：……'
- Example: 'Decompose this problem and give me a minimal method I could implement.'
/research-refine "problem | approach" -- max rounds: 3, threshold: 9What the agent produces and where it saves it
The skill writes its work to a refine-logs/ folder. Each round produces a review file and a refinement file, and each refinement contains a full anchored proposal rather than only the changed parts. A checkpoint file records progress so an interrupted session can resume rather than start over.
At the end you get a final proposal and a report, plus a score history.
- REFINE_STATE.json: checkpoint state (phase, round, reviewer thread ID, last score)
- round-0-initial-proposal.md and round-N-review.md / round-N-refinement.md files
- REVIEW_SUMMARY.md, FINAL_PROPOSAL.md, REFINEMENT_REPORT.md, score-history.md
Safety notes: scripts and network access
This skill runs scripts and uses the network. Its allowed tools include shell commands (Bash), file reading and writing, search tools, WebSearch and WebFetch, and several MCP reviewer tools. The reviewer step sends your proposal draft to an external reviewer model, so do not include confidential material you are not willing to share with that service.
The skill's description says it relies on web search and model judgement, and that the file does not verify literature claims. Check every cited paper and claim yourself before relying on it.
- Review any scripts the skill runs before installing it
- Do not send unpublished or confidential data to the external reviewer
- Verify all literature claims independently
What people use it for
- Turning a broad idea such as 'improve model robustness' into one specific mechanism with a minimal validation plan
- Helping a student shrink an overbuilt method draft into a single dominant contribution
- Documenting how a research team's plan evolved across reviewed rounds
- Preparing a clear method section outline that can later be passed to a separate experiment-planning step
Frequently asked questions
Is the research-refine skill free to use?
The source file for this skill does not state a price or licence terms beyond the MIT licence listed for the repository. The reviewer model and MCP connections it relies on may have their own access requirements, so check those separately.
What do I need to run research-refine?
You need a configured reviewer backend, such as Codex MCP or another listed MCP option, with access to gpt-6-astra or an equivalent reviewer. Web search and a local folder of up to 15 papers are optional but helpful for grounding.
How do I install the research-refine skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
Can research-refine work without an external reviewer?
The skill's core loop depends on the external reviewer, and the skill file describes no fallback. Without a configured reviewer, it is not expected to work as described.
What if my session is interrupted during a refinement?
The skill saves checkpoint state to refine-logs/REFINE_STATE.json after each phase. If a run is in progress and the checkpoint is less than 24 hours old, the skill resumes from the saved phase instead of starting over.
How does research-refine compare with simple brainstorming?
The skill is designed for a structured, multi-round review loop with saved records. The skill file notes that this loop is slow and token-heavy, so for quick one-off brainstorming a simpler prompt is a better fit.
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
Research Refine suits researchers with a clear problem but an unclear method, students who want to avoid overbuilt ideas, and teams that need a documented review trail. It is a poor choice for quick brainstorming, for anyone without access to the external reviewer or MCP servers, or for tasks that need literature claims verified to a high standard.
Download the skill