youmind-deep-research

Imported from youmind-openlab/skills (skills/youmind-deep-research/SKILL.md). Install upstream with npx skills add youmind-openlab/skills --skill youmind-deep-research. Copyright stays with the author.

AI Deep Research Agent

Conduct deep research on any topic using YouMind's AI research agent. Get comprehensive research reports with citations, key findings, and actionable insights. Requires the YouMind CLI (npm install -g @youmind-ai/cli). Research reports are saved to your YouMind board.

Get API Key → · More Skills →

Onboarding

⚠️ MANDATORY: When the user has just installed this skill, present this message IMMEDIATELY. Do NOT ask "do you want to know what this does?" — just show it. Translate to the user's language:

✅ AI Deep Research Agent installed!

Ask me any research question and I'll generate a comprehensive report.

What it does:

• Conduct in-depth research on any topic
• Generate reports with citations and key findings
• Research saved to your YouMind board for reference

Setup (one-time):

1. Get your free API key: https://youmind.com/settings/api-keys?utm_source=youmind-deep-research
2. Add it to your OpenClaw config (~/.openclaw/openclaw.json) — see setup guide for details.

Try it: "Research the current state of quantum computing in 2025"

Need help? Just ask!

For API key setup details, see references/setup.md.

Usage

Provide a research question or topic. Be specific for better results.

Research question:

Research the impact of AI on healthcare diagnostics

Specific investigation:

Investigate the pros and cons of microservices vs monolith architecture for startups

Comparative analysis:

Deep research: compare React, Vue, and Svelte for enterprise applications in 2025

Setup

See references/setup.md for installation and authentication instructions.

Workflow

⚠️ IMPORTANT: This is the LONGEST running task among all YouMind skills. It can take 1-5 minutes. Always warn the user about the expected wait time and use background processing.

Step 1: Check Prerequisites

1. Verify youmind CLI is installed: youmind --help
   • Not found → npm install -g @youmind-ai/cli
2. Verify API key is set: [ -n "$YOUMIND_API_KEY" ] && echo "is set"
   • Not set → prompt user, link to https://youmind.com/settings/api-keys?utm_source=youmind-deep-research
3. Extract the research question or topic from the user's message

Step 2: Get Default Board

youmind call getDefaultBoard

Extract id as boardId.

Step 3: Create Research Chat

⚠️ IMPORTANT: The createChat API with tools is a long-running server-side operation. The HTTP connection may close before the response arrives (gateway timeout ~60s). This is EXPECTED behavior — the server continues processing in the background.

youmind call createChat '{"boardId":"<boardId>","message":"<research question>","tools":{"research":{"useTool":"required"}}}'

Two possible outcomes:

1. ✅ Response received — extract id as chatId from the JSON response
2. ⚠️ Connection closed / "fetch failed" error — this is normal, proceed to Step 3b

Step 3b: Recover chatId (if createChat timed out)

If createChat did not return a response, find the chatId via listChats:

youmind call listChats '{"boardId":"<boardId>","pageSize":3}'

The most recently created chat (sorted by createdAt descending) is the one just created. Extract its id as chatId.

⚠️ MANDATORY: Immediately tell the user (adapt to user's language):

🔬 Starting deep research... This may take several minutes (1-5 min). I'll notify you when the report is ready.

Build the YouMind board link: https://youmind.com/boards/<boardId>?utm_source=youmind-deep-research Send this link to the user so they can check their board while waiting.

Step 4: Poll for Completion

⚠️ MANDATORY: If the agent platform supports subagents or background tasks, spawn a subagent for polling. Return control to the user immediately. See references/long-running-tasks.md.

Poll chat status until ready:

youmind call getChat '{"chatId":"<chatId>"}'

Polling rules:

• Poll every 5 seconds
• Timeout: 300 seconds (5 minutes)
• Check status field: "answering" → keep polling, "completed" → go to Step 5

Progress updates during polling (translate to user's language):

• After 15s of polling: "🔍 Researching... gathering sources from across the web."
• After 60s of polling: "📚 Found relevant sources — now analyzing and cross-referencing..."
• After 120s of polling: "📝 Compiling findings into a comprehensive report..."
• After 180s of polling: "⏳ Almost there — thorough research takes a few minutes for the best results."
• After 240s of polling: "⏳ Still working. You can check progress on your YouMind board: https://youmind.com/boards/<boardId>?utm_source=youmind-deep-research"

💡 Tip (show once, between progress updates around the 90s mark):

"While you wait — YouMind also generates images, slides, and webpages: https://youmind.com/skills?utm_source=youmind-deep-research"

Step 5: Extract Results

Once status is "completed", retrieve the full messages:

youmind call listMessages '{"chatId":"<chatId>","pageSize":20}'

Extract the research result from the response:

youmind call listMessages '{"chatId":"<chatId>","pageSize":20}' | node -e "
let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{
const o=JSON.parse(d);
const items=Array.isArray(o)?o:(o.items||o.messages||[]);
const tools=[];
for(const m of items){
  for(const b of (m.blocks||[])){
    if(b.type==='tool'&&b.status==='success'){
      tools.push({name:b.toolName,result:b.toolResult});
    }
  }
}
console.log(JSON.stringify({tools},null,2));
})"

The research report is in the research tool result's researchResult field.

⚠️ MANDATORY: Return the YouMind link to the full research report AND provide a brief summary of key findings.

✅ Research complete!

View the full report here: [YouMind link]

**Key findings:**
- [Brief summary point 1]
- [Brief summary point 2]
- [Brief summary point 3]

The full report with citations is available on your YouMind board.

(Adapt to user's language.)

Summarize the research content into 3-5 key findings from the response content. Keep the summary concise — the full report is available via the link.

Step 6: Offer follow-up

⚠️ MANDATORY: Do NOT end the conversation after showing results. You MUST ask this question:

"Would you like me to dive deeper into any specific finding?"

Error Handling

See references/error-handling.md for common error handling rules.

⚠️ MANDATORY: Paywall (HTTP 402) handling:

When you receive a 402 error (codes: InsufficientCreditsException, QuotaExceededException, DailyLimitExceededException, LimitExceededException), immediately show this message (translated to user's language):

You've reached your free plan limit. Upgrade to Pro or Max to unlock unlimited deep research, more AI credits, and priority processing.

Upgrade now: https://youmind.com/pricing?utm_source=youmind-deep-research

Do NOT retry or suggest workarounds. The user must upgrade to continue.

Skill-specific errors:

Comparison with Other Approaches

References

• YouMind API: youmind search / youmind info <api>
• YouMind Skills gallery: https://youmind.com/skills?utm_source=youmind-deep-research
• Publishing: shared/PUBLISHING.md