Researchclaw

ResearchClaw Skill — Autonomous Research Pipeline

This skill wraps AutoResearchClaw, a 23-stage pipeline that takes a research topic and produces a conference-grade LaTeX paper with real citations, sandbox-executed experiments, multi-agent peer review, and citation verification.

Honesty policy: This skill does not fabricate capabilities. Every command maps to real upstream functionality. If something fails, the skill reports the actual error and suggests concrete fixes — it never pretends the problem does not exist.

Commands

---

/researchclaw — Help

When invoked without a subcommand, display this command list and a one-line status summary:

1. Check if researchclaw CLI is installed: which researchclaw 2. Check if config.yaml exists in the current directory 3. Print the command table above 4. Suggest the most logical next step based on what is missing

---

/researchclaw:setup — Prerequisites Installation

MANDATORY: Ask the user before installing anything. Present what is missing and get explicit approval.

Run the prerequisite check script:

bash "${CLAUDE_SKILL_DIR}/scripts/check-prereqs.sh"

The script checks each dependency and outputs a JSON report. Based on the report:

1. Python 3.11+: Check python3 --version. If missing or too old, suggest pyenv install 3.11 or system package manager. 2. pip / uv: Check pip3 --version or uv --version. Suggest uv if not present (faster). 3. Docker: Check docker info. If Docker daemon is not running, tell the user honestly — this skill cannot start Docker for you on most systems. 4. LaTeX: Check pdflatex --version. If missing, suggest sudo apt-get install texlive-full (Linux) or brew install --cask mactex (macOS). Be honest: this is a large download (2-4 GB). 5. AutoResearchClaw: Check pip3 show researchclaw. If not installed:

   pip3 install researchclaw

Or from source:

   git clone https://github.com/aiming-lab/AutoResearchClaw.git
   cd AutoResearchClaw
   pip3 install -e ".[all]"

After installation, re-run the check script to verify everything passes.

What this skill CANNOT do:

• Start the Docker daemon (requires system-level access)
• Install LaTeX without sudo on Linux
• Fix network/firewall issues blocking API access
• Provide LLM API keys — the user must supply their own

---

/researchclaw:config — Interactive Configuration Wizard

Generate a working config.yaml by asking the user a series of questions. Use AskUserQuestion for each batch.

Batch 1 — Essential settings (MUST ask):

1. Research topic: What do you want to research? (free text) 2. LLM provider: Which LLM API? Options: openai, anthropic, azure, deepseek, local 3. API key: Provide your API key, or the environment variable name that holds it (e.g., OPENAI_API_KEY) 4. Model: Which model? Suggest defaults per provider:

• openai: gpt-4o
• anthropic: claude-sonnet-4-20250514
• deepseek: deepseek-chat

Batch 2 — Experiment settings (ask with smart defaults):

5. Experiment mode: simulated (no code execution, fastest), sandbox (local execution), or ssh_remote (GPU server). Default: simulated 6. Auto-approve gates: Skip human approval at stages 5, 9, 20? Default: true for first run 7. Output directory: Where to save artifacts. Default: artifacts/

Batch 3 — Optional advanced settings (offer but don't require):

8. Paper template: neurips, icml, iclr, or generic. Default: neurips 9. Max iterations: For iterative pipeline mode. Default: 3 10. Literature sources: arxiv, semantic_scholar, or both. Default: both

After collecting answers, generate config.yaml using the template in assets/config-template.yaml. Write it to the current directory and show the user the generated file.

Validation: After generating, run:

researchclaw validate --config config.yaml

If validation fails, explain what went wrong and offer to fix it.

---

/researchclaw:run — Execute the Pipeline

Pre-flight checks (always run before starting):

1. Run /researchclaw:validate logic silently 2. If any check fails, report it and ask the user whether to proceed or fix first

Start the pipeline:

researchclaw run --topic "$ARGUMENTS" --config config.yaml --auto-approve 2>&1 | tee researchclaw-run.log

If $ARGUMENTS is empty, read the topic from config.yaml.

During execution:

• The pipeline runs 23 stages. Each stage produces output in artifacts/<run-id>/stage-N/
• Monitor progress by checking which stage directories exist
• If the pipeline fails, capture the error output and run /researchclaw:diagnose logic automatically

After completion:

• Report which stages succeeded and which failed
• Show the path to the generated paper (typically artifacts/<run-id>/stage-17/paper_draft.md or the final PDF)
• Show total execution time

---

/researchclaw:status — Pipeline Status

Check the current state of a pipeline run:

ls -la artifacts/ 2>/dev/null | tail -5

For the most recent run:

1. Find the latest artifacts/rc-* directory 2. Count completed stages: ls -d artifacts/rc-*/stage-* 2>/dev/null | wc -l 3. Check for pipeline_summary.json — if it exists, the run is complete 4. If no summary exists, check which stage was last modified to estimate current progress 5. Report: Stage X/23 complete. Current stage: [stage name]. Status: [running/failed/complete]

Stage name mapping (for human-readable output):

---

/researchclaw:resume — Resume a Failed Run

Resume from the last successful stage:

1. Find the latest run directory: ls -td artifacts/rc-* | head -1 2. Find the last completed stage: check pipeline_summary.json or find the highest-numbered stage-* directory with output files 3. Determine the next stage name from the stage mapping above 4. Run:

   researchclaw run --config config.yaml --from-stage STAGE_NAME --output <run-dir> --auto-approve 2>&1 | tee researchclaw-resume.log

Known issue (upstream): The --from-stage flag may not work correctly in all versions. If resume fails, inform the user honestly and suggest:

• Starting a fresh run
• Manually copying successful stage outputs to a new run directory

---

/researchclaw:diagnose — Auto-Diagnose Failures

Read the most recent log and error output to identify the problem:

tail -100 researchclaw-run.log 2>/dev/null || tail -100 researchclaw-resume.log 2>/dev/null

Common failure patterns and fixes:

After diagnosis, suggest the specific fix. If the fix is automatable (e.g., installing a package), offer to do it with user approval.

---

/researchclaw:validate — Pre-Run Validation

Run all checks without starting the pipeline:

bash "${CLAUDE_SKILL_DIR}/scripts/check-prereqs.sh"

Then additionally:

1. Config syntax: python3 -c "import yaml; yaml.safe_load(open('config.yaml'))" 2. Config completeness: Check that llm.api_key or llm.api_key_env is set, research.topic is non-empty 3. API connectivity: Test the LLM endpoint with a minimal request 4. Docker health: docker info (if experiment mode is sandbox) 5. Disk space: df -h . — warn if less than 10 GB free 6. Write permissions: touch artifacts/.write-test && rm artifacts/.write-test

Report results as a checklist with pass/fail for each item.

---

Additional Resources

• For the full pipeline stage reference, see references/pipeline-stages.md
• For configuration field reference, see references/config-reference.md
• For troubleshooting recipes, see references/troubleshooting.md
• For Chinese documentation, see references/README-CN.md

---

Principles

1. Never lie. If something is broken, say so. If a feature does not exist upstream, do not pretend it does. 2. Always test. Run validation before every pipeline execution. Check results after every action. 3. Ask before acting. Never install packages, modify configs, or start long-running processes without explicit user approval. 4. Report honestly. Show actual error messages, not sanitized summaries. The user needs real information to debug. 5. Stay current. This skill targets AutoResearchClaw v0.3.x. If the upstream version changes significantly, some commands may need updating.

AutoResearchClaw Configuration Reference

This document covers all configuration fields in config.yaml. Fields marked required must be set for the pipeline to run.

LLM Configuration

*Either api_key or api_key_env must be set, not both.

Provider-Specific Notes

OpenAI:

• Default base_url: https://api.openai.com/v1
• Recommended models: gpt-4o, gpt-4o-mini
• Set OPENAI_API_KEY environment variable

Anthropic:

• Default base_url: https://api.anthropic.com
• Recommended models: claude-sonnet-4-20250514, claude-3-5-haiku-20241022
• Set ANTHROPIC_API_KEY environment variable

Azure OpenAI:

• Must set base_url to your Azure endpoint
• Must set api_key_env to your Azure API key variable
• Model name should match your Azure deployment name

DeepSeek:

• Default base_url: https://api.deepseek.com
• Recommended model: deepseek-chat
• Set DEEPSEEK_API_KEY environment variable

Research Configuration

Experiment Configuration

Pipeline Configuration

Paper Configuration

Literature Configuration

Quality Configuration

Important: The default min_score of 2.0 is very strict and blocks many first-time runs. Consider setting it to 3.0 or higher for better results, or 1.0 to always pass (useful for testing).

Iterative Pipeline Configuration

AutoResearchClaw Pipeline Stages Reference

The pipeline consists of 23 stages organized into 8 phases. Three stages (5, 9, 20) are human-approval gates that pause for review unless --auto-approve is set.

Phase 1: Topic and Problem Definition (Stages 1-2)

Phase 2: Literature Review (Stages 3-4)

Phase 3: Research Direction (Stage 5 — Gate)

Gate behavior: Pauses for human review. The user can approve, modify, or reject the direction. With --auto-approve, this is skipped.

Phase 4: Hypothesis and Experiment Design (Stages 6-9)

Phase 5: Experiment Execution (Stages 10-14)

Stage 10 is the most common failure point. The generated code may have syntax errors, missing imports, or incompatible library versions. If it fails, check artifacts/*/stage-10/experiment.py.

Phase 6: Paper Writing (Stages 15-17)

Phase 7: Review and Revision (Stages 18-20)

Phase 8: Finalization (Stages 21-23)

Typical Execution Times

Hardware Requirements

ResearchClaw 技能 — 自主研究管线

English | 中文

简介

本技能封装了 AutoResearchClaw，一个 23 阶段的自主研究管线。输入一个研究主题，即可自动完成从文献综述到论文生成的全流程，包括真实引文检索、沙箱实验执行、多智能体同行评审和引文验证。

命令列表

快速开始

第一步：安装前置依赖

/researchclaw:setup

技能会自动检测缺少的依赖，并在安装前征求你的同意。

第二步：生成配置文件

/researchclaw:config

按照交互式向导回答问题，技能会自动生成 config.yaml。

你需要准备：

• 研究主题：你想研究什么？
• LLM API 密钥：OpenAI、Anthropic、DeepSeek 等任一提供商的 API 密钥
• 实验模式：simulated（模拟，最快）、sandbox（本地执行）或 ssh_remote（远程 GPU）

第三步：运行管线

/researchclaw:run 你的研究主题

第四步：查看状态

/researchclaw:status

系统要求

常见问题

API 密钥错误 (HTTP 401)

检查 config.yaml 中的 llm.api_key_env 是否指向正确的环境变量。

echo $OPENAI_API_KEY  # 确认变量已设置

阶段 10 代码生成失败

这是最常见的失败点。建议： 1. 使用更强的模型（gpt-4o 或 claude-sonnet-4-20250514） 2. 切换到 simulated 模式跳过代码执行 3. 运行 /researchclaw:diagnose 获取详细错误信息

质量门控拒绝

默认阈值（2.0）非常严格。编辑 config.yaml：

quality:
  min_score: 3.0  # 降低阈值

Docker 未运行

# Linux
sudo systemctl start docker

# macOS
open -a Docker

中国大陆网络问题

如果无法访问 arXiv 或 Semantic Scholar：

1. 配置代理：

export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port

2. 考虑使用 DeepSeek 作为 LLM 提供商（国内访问更稳定）：

llm:
  provider: deepseek
  model: deepseek-chat
  api_key_env: DEEPSEEK_API_KEY

管线阶段概览

诚实声明

本技能不会虚构功能。每个命令都映射到真实的上游功能。如果某些功能失败，技能会报告实际错误并建议具体的修复方案——绝不假装问题不存在。

AutoResearchClaw Troubleshooting Guide

This document covers the most common failures and their solutions, based on real issues reported by the community.

Installation Failures

pip install fails with dependency conflicts

Symptom: ERROR: Cannot install researchclaw because these package versions have conflicting dependencies

Fix:

# Create a fresh virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install researchclaw[all]

Or use uv for faster, more reliable dependency resolution:

uv pip install researchclaw[all]

Windows: installation fails

Symptom: Various errors on Windows, especially with Docker and LaTeX paths.

Reality check: AutoResearchClaw has limited Windows support as of v0.3.x. The recommended approach is: 1. Use WSL2 (Windows Subsystem for Linux) 2. Install Docker Desktop with WSL2 backend 3. Run everything inside WSL2

---

Configuration Failures

YAML parse error

Symptom: yaml.scanner.ScannerError: mapping values are not allowed in this context

Diagnosis:

python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

Common causes:

• Missing quotes around strings with colons (e.g., topic: NLP: A Survey should be topic: "NLP: A Survey")
• Incorrect indentation (YAML requires consistent spaces, not tabs)
• Missing space after colon (key:value should be key: value)

API key not found

Symptom: HTTP 401 Unauthorized or AuthenticationError

Diagnosis:

# Check if the env var is set
echo $OPENAI_API_KEY
# or
echo $ANTHROPIC_API_KEY

Fixes: 1. Verify the key is valid (not expired, not revoked) 2. Check config.yaml — is api_key_env pointing to the correct variable name? 3. If using api_key directly, ensure it has no extra whitespace or quotes

Azure endpoint configuration

Symptom: Connection refused or 404 Not Found when using Azure OpenAI

Fix: Azure requires a specific URL format:

llm:
  provider: azure
  base_url: "https://YOUR-RESOURCE.openai.azure.com/openai/deployments/YOUR-DEPLOYMENT"
  api_key_env: AZURE_OPENAI_API_KEY
  model: "YOUR-DEPLOYMENT-NAME"  # Must match the Azure deployment name exactly

---

Pipeline Execution Failures

Stage 10 (Code Generation) failure

Symptom: Pipeline stops at stage 10 with code generation errors.

This is the most common failure. The LLM generates Python code that may have:

• Syntax errors
• Missing imports
• Incompatible library versions
• Hardcoded paths that don't exist

Diagnosis:

# Check the generated code
cat artifacts/rc-*/stage-10/experiment.py

# Try running it manually
python3 artifacts/rc-*/stage-10/experiment.py

Fixes: 1. Use a stronger model (gpt-4o or claude-sonnet-4-20250514 instead of smaller models) 2. Switch to simulated mode to skip actual code execution 3. Manually fix the generated code and resume from stage 11

Quality gate rejection

Symptom: Pipeline stops with quality_score below threshold

Fix: The default threshold (2.0) is very strict. Edit config.yaml:

quality:
  min_score: 1.0  # Lower to always pass (for testing)

For production runs, use 3.0-5.0 as a reasonable threshold.

Rate limiting (HTTP 429)

Symptom: RateLimitError or HTTP 429 Too Many Requests

Fixes: 1. Wait 60 seconds and resume: researchclaw run --from-stage LAST_STAGE --config config.yaml 2. Switch to a model with higher rate limits 3. Add retry logic in config (if supported by your version)

Memory exhaustion (OOM)

Symptom: Process killed, MemoryError, or system becomes unresponsive

Fixes: 1. Use simulated experiment mode (no code execution = less memory) 2. Close other applications 3. Reduce literature.max_papers to 10-15 4. Set pipeline.max_concurrent_stages: 1

---

Docker Failures

Docker daemon not running

Symptom: Cannot connect to the Docker daemon

Fix:

# Linux
sudo systemctl start docker

# macOS
open -a Docker  # Start Docker Desktop

# Verify
docker info

Docker permission denied

Symptom: Got permission denied while trying to connect to the Docker daemon socket

Fix:

sudo usermod -aG docker $USER
# Then log out and log back in

---

LaTeX Failures

pdflatex not found

Symptom: pdflatex: command not found at stage 23

Fix:

# Ubuntu/Debian
sudo apt-get install texlive-full  # WARNING: 2-4 GB download

# macOS
brew install --cask mactex

# Minimal install (smaller but may miss some packages)
sudo apt-get install texlive-latex-base texlive-latex-extra texlive-fonts-recommended

Missing LaTeX packages

Symptom: ! LaTeX Error: File 'neurips_2024.sty' not found

Fix: The NeurIPS/ICML/ICLR templates require specific style files. These should be included in the AutoResearchClaw package. If missing:

# Check if the template files exist
find . -name "*.sty" -o -name "*.cls" | head -20

# If missing, reinstall
pip install researchclaw[all] --force-reinstall

---

Resume Failures

--from-stage not working

Symptom: Resume starts from the beginning instead of the specified stage, or crashes.

Known issue: The --from-stage flag has bugs in some versions.

Workaround: 1. Note which stages completed successfully (check artifacts/rc-*/stage-*/) 2. Start a fresh run with the same config 3. If you need specific stage outputs, copy them from the old run directory

---

Network Failures

Cannot reach arXiv or Semantic Scholar

Symptom: ConnectionError during literature search (stages 3-4)

Diagnosis:

curl -s https://api.semanticscholar.org/graph/v1/paper/search?query=test | head -100
curl -s "http://export.arxiv.org/api/query?search_query=all:test&max_results=1" | head -100

Fixes: 1. Check internet connectivity 2. If behind a corporate proxy, set HTTP_PROXY and HTTPS_PROXY environment variables 3. If arXiv is rate-limiting you, wait 10 minutes and retry