Deep Research via Gemini CLI Extension

Execute Gemini Deep Research using the gemini-deep-research MCP extension for the Gemini CLI. Use when user wants deep, comprehensive research on a topic — m...

Security Scan

The skill mostly does what it says (drives the gemini-deep-research MCP extension and writes reports), but it launches persistent background processes, reads an extension .env, and depends on a third‑party Gemini extension (downloaded from GitHub) — behaviours that deserve careful review before granting trust.

Purpose & Capability

The name and description match the code and instructions: the scripts start a Gemini MCP research task, poll status, and save a report. However the registry metadata lists no prerequisites while SKILL.md requires the gemini CLI, the gemini-deep-research extension, and a paid Google AI API key; this mismatch is notable but explainable (the key is configured via the extension, not an env var).

Instruction Scope

The runtime instructions create a temp task dir, write task.json, produce a poll.sh that is launched with nohup, and run node scripts repeatedly in the background. The scripts spawn the extension's MCP server (dist/index.js) multiple times and write into /tmp and the user's home (~/ObsidianVault/...). They also read an extension .env file. Running background processes and repeatedly executing third‑party extension code expands the runtime scope beyond a single short LLM response and should be accepted consciously by the user.

Install Mechanism

The skill package itself has no install spec (instruction-only), which is low risk. But SKILL.md instructs installing the gemini CLI and installing a third‑party extension from a GitHub URL (https://github.com/allenhutchison/gemini-cli-deep-research). Installing and auto‑updating that extension pulls external code — expected for this purpose, but it is an external dependency you should vet.

Credentials

Registry metadata declares no required env vars (plausible because the extension stores the API key in the keychain), but the scripts read the extension directory and attempt to load an .env (EXT_PATH/.env) and merge it into spawned process.env in dr-client.js. Reading that .env could expose API keys if the extension stores them there. The skill also writes into the user's home and tmp directories. Requesting/using a Google AI API key is expected, but the way secrets are accessed (file-based .env + system keychain + repeated spawn of extension code) is worth verifying.

Persistence & Privilege

The skill is not marked always:true. However the instructions explicitly create and launch a background poll process (nohup bash poll.sh &), which will continue after the agent session ends. That persistent background behavior is core to the claimed functionality but increases blast radius (the background process repeatedly spawns MCP server code). The skill does not ask to modify other skills or global agent settings.

What to consider before installing

What to consider before installing/using: - Required external components: you must install the gemini CLI and the gemini-deep-research extension and provide a paid Google AI API key (configured via the extension). The skill metadata did not list these prerequisites — read SKILL.md and references/setup-guide.md carefully. - Third‑party extension risk: the workflow repeatedly spawns the extension's dist/index.js (code you download from GitHub). If that extension contains malicious or buggy code it can run with your user privileges. Audit the extension repo (https://github.com/allenhutchison/gemini-cli-deep-research) and its dist/index.js before installing, or run this skill in a sandbox/VM. - Secret handling: the scripts attempt to load EXT_PATH/.env and merge it into the spawned process environment; if API keys are stored in that .env they will be read. The setup guide says the extension stores keys in the system keychain (safer), but you should confirm how your extension actually stores credentials. - Background processes & filesystem writes: the workflow creates /tmp/gemini-deep-research/<task>/, writes task.json and logs there, and by default saves reports under ~/ObsidianVault/Default/DeepResearch/. Make sure you are happy with those write locations and with a background nohup process running for up to the timeout (40 minutes by default). - Practical precautions: verify the extension source and its code; run an initial test with a throwaway account or in an isolated environment; inspect the included scripts (start/poll/save) — they are straightforward but they execute the extension repeatedly; consider changing default output path; remove auto-update for the extension if you require stable code. Confidence: medium — the package is largely consistent with its stated purpose, but the combination of background execution, reading an extension .env, and pulling a third‑party extension from GitHub are non-trivial risks that require user review.

Gemini Deep Research

Executes a full Deep Research workflow via the gemini-deep-research MCP extension, with background polling and automatic report saving. The workflow is non-blocking — the agent sets up the task and exits immediately while a background script handles polling.

---

Prerequisites

See references/setup-guide.md. If any prerequisite is missing, inform the user and stop.

---

Scripts

Three scripts in <skill>/scripts/:

Script	Role
start-research.js	Calls research_start, outputs JSON with research ID
poll-research.js	Polls research_status every 5 min until done/timeout
save-report.js	Calls research_save_report once status is completed

All scripts read/write task.json in the task's temp directory.

---

Workflow

Step 1 — Pre-Flight Confirmation (one message, all parameters)

Write in the user's current session language.

请确认 Deep Research 参数：

① 研究主题：[用户描述]
   （将原样发给 Gemini，请确保表述清晰具体）

② 报告格式：
   - Comprehensive Research Report（推荐，最全面）
   - Executive Brief（精简版，1-2页）
   - Technical Deep Dive（技术深度分析）

③ 保存位置：~/ObsidianVault/Default/DeepResearch/
   （默认文件名：YYYYMMDD-<slug>.md，可自定义路径）

④ 轮询最大时长：40 分钟（5 分钟 × 8 次），超时后通知您手动处理

直接回复修改项，或"确认"以默认参数启动。

Step 2 — Create Task Temp Directory

mkdir -p /tmp/gemini-deep-research/<YYMMDD-HHmm>_<sanitized-topic>/

Write task.json:

{
  "input": "研究主题",
  "format": "Comprehensive Research Report",
  "outputPath": "/home/node/ObsidianVault/Default/DeepResearch/<YYYYMMDD>-<slug>.md",
  "pollIntervalSeconds": 300,
  "maxPolls": 8,
  "createdAt": "<ISO timestamp>"
}

Step 3 — Start Research

node <skill>/scripts/start-research.js /tmp/gemini-deep-research/<task-dir>/

Parse stdout JSON for { status: "started", researchId: "v1_..." }. If status: "error", inform the user and abort.

Step 4 — Write Background Poll Script

Write <task-dir>/poll.sh:

#!/bin/bash
set -euo pipefail
cd "$(dirname "$0")"

SKILL_DIR="<skill>/scripts"
TASK_DIR="$(pwd)"

log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> poll.log; }

log "Starting poll-research..."
node "$SKILL_DIR/poll-research.js" "$TASK_DIR" >> poll-out.log 2>&1
RESULT=$(cat <<< "$(node "$SKILL_DIR/poll-research.js" "$TASK_DIR")")

STATUS=$(echo "$RESULT" | node -pe "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).status")
log "Poll result: $STATUS"

if [[ "$STATUS" == "completed" ]]; then
  log "Research completed. Saving report..."
  node "$SKILL_DIR/save-report.js" "$TASK_DIR" >> save-out.log 2>&1
  SAVE_STATUS=$(node -pe "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).status" <<< "$(node "$SKILL_DIR/save-report.js" "$TASK_DIR")")
  log "Save result: $SAVE_STATUS"
  echo "$SAVE_STATUS"
elif [[ "$STATUS" == "timeout" ]]; then
  echo "timeout"
else
  echo "failed"
fi

Step 5 — Launch Background Process

cd /tmp/gemini-deep-research/<task-dir>/
nohup bash poll.sh > /dev/null 2>&1 &
echo "Background PID: $!"

Step 6 — Notify User

"🔬 Deep Research 已启动\n\n主题：[topic]\n格式：[format]\n预计完成：2–15 分钟（视主题复杂度而定）\n\n轮询后台运行，完成后我会通知您。如超时（40 分钟）未完成，我会告知并提供手动检查方法。"

Step 7 — Completion

When the user asks "is it done?" or when notified by a new session:

# Check done.flag or task.json status
cat /tmp/gemini-deep-research/<task-dir>/task.json

On success:

"✅ Deep Research 完成！\n\n主题：[topic]\n报告：[outputPath]\n轮询次数：N\n\n已保存到 ObsidianVault，可在 DeepResearch/ 目录找到。"

On timeout:

"⏰ Deep Research 超时\n\n主题：[topic]\nResearch ID：v1_...\n\n该 ID 在 Google 侧仍可能已完成。可手动保存：\n```bash\nnode <skill>/scripts/save-report.js /tmp/gemini-deep-research/<task-dir>/\n```\n\n或前往 https://notebooklm.google.com/ 查看。"

On failure:

"❌ Deep Research 失败\n\n原因：[error message]\n\n请检查 API Key 配置（gemini extensions config gemini-deep-research）或查询 references/setup-guide.md。"

---

Report Formats

Format	Description
Comprehensive Research Report	Full multi-section report with analysis and citations (default)
Executive Brief	Condensed summary for decision-makers
Technical Deep Dive	Detailed technical analysis

---

File Naming

Default pattern: YYYYMMDD-<slug>.md

• YYYYMMDD = today's date
• <slug> = lowercase, spaces→hyphens, strip special chars
• Example: 20260325-iran-hormuz-strait-market-impact.md

---

Error Handling

Error	Cause	Resolution
API key not found	Key not configured	Guide to references/setup-guide.md step 4
429 Too Many Requests	Free-tier key / quota exceeded	Requires paid key
Research timed out	Took > 40 min	Check task.json, manually save if completed server-side
MCP server spawn failed	Extension path wrong	Verify ~/.gemini/extensions/gemini-deep-research/ exists

---

Temp Directory Structure

/tmp/gemini-deep-research/
  <YYMMDD-HHmm>_<topic>/
    task.json       ← task parameters + research ID
    progress.json    ← poll count, last poll time (updated by poll-research.js)
    poll.log        ← each poll attempt log
    poll-out.log    ← stdout from poll-research.js
    save-out.log    ← stdout from save-report.js
    error.log       ← errors
    done.flag       ← created on success
    <report>.md     ← saved report