Research Skill

---

name: research

description: Conduct open-ended research on a topic, building a living markdown document. Supports interactive and deep research modes.

---

# Research Skill

Description

Conduct open-ended research on a topic, building a living markdown document. The conversation is ephemeral; the document is what matters.

Trigger

Activate when the user wants to:

Research Directory

Each research topic gets its own folder:

~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # Original research question/prompt
├── research.md        # Main findings (Parallel output or interactive notes)
├── research.pdf       # PDF export (when generated)
└── ...                # Any other related files (data, images, etc.)

---

Two Research Modes

1. Interactive Research (default)

For topics you explore together in conversation. You search, synthesize, and update the doc in real-time.

2. Deep Research (async)

For complex topics that need comprehensive investigation. Uses the Parallel AI API via `parallel-research` CLI. Takes minutes to hours, returns detailed markdown reports.

**When to use deep research:**

---

Interactive Research Workflow

1. Initialize Research

1. **Create the research folder** at `~/.openclaw/workspace/research/<topic-slug>/`

2. **Create prompt.md** with the original question:

```markdown

# <Topic Title>

> <The core question or curiosity>

**Started:** <date>

```

3. **Create research.md** with the working structure:

```markdown

# <Topic Title>

**Status:** Active Research

**Started:** <date>

**Last Updated:** <date>

---

## Open Questions

- <initial questions to explore>

## Findings

<!-- Populated as we research -->

## Options / Approaches

<!-- If comparing solutions -->

## Resources

<!-- Links, references, sources -->

## Next Steps

<!-- What to explore next, or "graduate to project" -->

```

4. **Confirm with user** - Show the folder was created and ask what to explore first.

2. Research Loop

For each exchange:

1. **Do the research** - Web search, fetch docs, explore code

2. **Update the document** - Add findings, move answered questions, add sources

3. **Show progress** - Note what was added (don't repeat everything)

4. **Prompt next direction** - End with a question or suggestion

**Key behaviors:**

3. Synthesis Checkpoints

Every 5-10 exchanges, offer to:

4. Completion

When research is complete, update the status in `research.md`:

**If the research is specifically for building a project:**

Most research is just research — it doesn't need to become a spec. Only graduate if you're actually building something from it.

---

Deep Research Workflow

1. Start Deep Research

parallel-research create "Your research question" --processor ultra --wait

**Processor options:**

**Options:**

2. Schedule Auto-Check (optional)

Deep research tasks take minutes to hours. You'll want to poll for results automatically rather than checking manually.

**Options:**

3. Manual Check (if needed)

parallel-research status <run_id>
parallel-research result <run_id>

4. Save to Research Folder

Create the research folder and save results:

~/.openclaw/workspace/research/<topic-slug>/
├── prompt.md          # Original question + run metadata
├── research.md        # Full Parallel output

**prompt.md** should include:

# <Topic Title>

> <Original research question>

**Run ID:** <run_id>
**Processor:** <processor>
**Started:** <date>
**Completed:** <date>

**research.md** contains the full Parallel output, plus any follow-up notes.

---

PDF Export

**All PDFs go in the research folder** — never save to `tmp/`. Whether using `export-pdf`, the browser `pdf` action, or any other method, the output path must be `research/<topic-slug>/`.

Use the `export-pdf` script to convert research docs to PDF:

export-pdf ~/.openclaw/workspace/research/<topic-slug>/research.md
# Creates: ~/.openclaw/workspace/research/<topic-slug>/research.pdf

For browser-generated PDFs (e.g. saving a webpage as PDF):

browser pdf → save to research/<topic-slug>/<descriptive-name>.pdf

**Note:** Tables render as stacked rows (PyMuPDF limitation). Acceptable for research docs.

---

Commands

---

Document Principles

---

Setup

See `SETUP.md` for first-time installation of: