Gemini Deep Research (J-claw)

Gemini Deep Research via the gemini-cli deep-research MCP extension. Use when user wants to research a topic deeply, run market/industry analysis, or generat...

Security Scan

The skill largely does what it claims (wraps a gemini-deep-research MCP extension) but has small inconsistencies and relies on installing a third‑party GitHub extension and loading an extension .env file that could expose secrets — review the extension and key handling before installing.

Purpose & Capability

The skill's name/description align with the code: it runs a local gemini-deep-research MCP server to perform long-running research requests and save a report. The JavaScript client spawns the extension's dist/index.js and polls it via MCP commands, which is coherent with the stated purpose. Minor inconsistency: the setup guide says the extension stores the API key in the system keychain (and that GEMINI_API_KEY env var is stripped), yet the shipped client explicitly reads an extension .env file and merges it into the spawned process environment — this mismatch should be clarified.

Instruction Scope

SKILL.md instructs the agent to run the provided node script as a background sub-agent and to save reports to a user-chosen path (defaulting to an ObsidianVault path). The script reads ~/.gemini/extensions/gemini-deep-research/.env (if present), spawns the MCP server, polls status, and writes the report file. It does not attempt to enumerate unrelated system files or exfiltrate data to external endpoints in the skill itself. However, because it will read an extension .env and write into the user's filesystem by default, users should be aware of potential sensitive-data exposure or overwriting of local files.

Install Mechanism

The skill is instruction-only (no install spec). The setup guide requires installing @google/gemini-cli (official) and installing the deep-research extension from a GitHub URL with --auto-update. Installing a third‑party extension from GitHub (auto-update enabled) is a moderate-risk action—it pulls and runs external code (the extension's dist/index.js) on your system and can change over time via updates. The skill code itself does not embed remote downloads, but it depends on that external install.

Credentials

The skill does not request unrelated credentials, and its need for a paid Google AI API key matches the stated use. However, the client loads a .env file from the extension directory and merges those variables into the MCP server's environment when spawning it. If that .env contains secrets (API keys, tokens), they will be passed to the spawned process. This conflicts with the setup guide's claim that the CLI stores the key in the system keychain and strips KEY envvars from MCP processes — the mismatch is a potential secret‑handling risk and should be reconciled. Also note the default save path writes into a local Obsidian vault by default, which may be unexpected for some users.

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and only runs on explicit invocation (or when the agent chooses to invoke it). It spawns a background sub-agent for long-running work which is consistent with the stated workflow and is not itself an elevated privilege.

What to consider before installing

This skill appears to implement its stated purpose, but proceed with caution: - Verify the third‑party gemini-deep-research extension on the referenced GitHub repo before installing (check the author, recent commits, issues, and code). The setup step installs that repo and enables auto-update — a future update could change behavior. - Confirm how your Google AI API key is stored and used. The setup guide says the extension stores the key in the system keychain, yet the client reads ~/.gemini/extensions/gemini-deep-research/.env and passes those env values to the spawned MCP process; avoid placing secrets in plaintext .env files and prefer keychain-based config if available. - Be aware the tool will write files to whatever output path you choose (default: your Obsidian vault). Use a safe output directory if you do not want research results stored in your personal notes or to risk overwriting files. - If you have sensitive queries or secrets, review the extension's code (especially the MCP server dist/index.js) to ensure it does not transmit data to unexpected endpoints. Consider running the extension and this skill in a sandboxed environment or on a disposable account until you trust the extension. - If you want greater assurance, ask the publisher for the extension's provenance and a signed release, or run the MCP server locally and inspect network activity during a test run.

Gemini Deep Research

Executes a full Deep Research workflow using the official gemini-deep-research MCP extension.

Prerequisites

See references/setup-guide.md for full setup instructions. The skill assumes:

• gemini CLI installed (npm install -g @google/gemini-cli)
• gemini-deep-research extension installed and enabled
• Paid Google AI API key configured via gemini extensions config gemini-deep-research

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

Workflow

Step 1 — Confirm Intent & Parameters

Ask the user to confirm:

1. Research topic (exact wording goes to Gemini — make it clear and specific)
2. Report format — present as a choice:
   • Comprehensive Research Report (default, most thorough)
   • Executive Brief (concise, ~1-2 pages)
   • Technical Deep Dive (detailed, technical audience)
3. Save path — default: ~/ObsidianVault/Default/DeepResearch/<YYYYMMDD>-<slug>.md

If user does not specify format, use Comprehensive Research Report.

If user does not specify a save path, use the default and inform them.

Step 2 — Build the Command

node <skill>/scripts/dr-client.js \
  --input "<user's research topic>" \
  --output "<full save path>" \
  --format "<chosen format>" \
  --timeout 900000

• <skill> = the skill's scripts directory (resolved by the agent)
• Timeout defaults to 15 minutes (900,000 ms)

Step 3 — Spawn as Background Sub-agent

Use sessions_spawn with runtime: "subagent" to run the script in the background so the main session remains responsive.

Pass all parameters (input, output, format, timeout) via the task string.

Monitor completion via the sub-agent's completion event.

Step 4 — Handle Result

Parse the JSON output from the script:

• status: "completed" → Report the success to the user with the file path
• status: "error" → Report the error message to the user with a suggestion to check the API key or extension setup

Step 5 — Notify

Send a Discord message (via current session reply) confirming:

• Topic researched
• File path
• Format used
• Any errors if applicable

Report Format Reference

Format	Description
Comprehensive Research Report	Full multi-section report with analysis, data, and citations
Executive Brief	Condensed summary for decision-makers, ~1-2 pages
Technical Deep Dive	Detailed technical analysis, suited for specialists

The format is passed as-is to the Gemini API — it serves as a style hint, not a strict guarantee.

Error Handling

Error	Likely Cause	Resolution
API key not found	Key not configured	Guide user to references/setup-guide.md step 4
429 Too Many Requests	Free-tier key used or quota exceeded	Requires paid key — inform user
Research timed out	Took > 15 minutes	Retry or shorten query
MCP server spawn failed	Extension not installed or path wrong	Verify ~/.gemini/extensions/gemini-deep-research/ exists

File Naming

Default pattern: YYYYMMDD-<slug>.md

• YYYYMMDD = today's date
• <slug> = sanitized version of the research topic (lowercase, spaces to hyphens, strip special chars)
• Example: 20260325-iran-hormuz-strait-market-impact.md