mcpField
D
deep-research

deep-research

github.com/davidondrejProductivity4.2k196 installsUpdated today
Repository

About deep-research

Deep Research is a skill that guides agents through DeepAPI's deep research endpoint, from composing a focused prompt to saving a cited report. It is for research tasks that need a structured answer with sources.

Key features

  1. 01Structures research prompts and sub-questions
  2. 02Calls the DeepAPI deep research endpoint
  3. 03Saves answers with source URLs
  4. 04Documents retry and failure handling

Use cases

  1. 01Investigate a question with a cited report
  2. 02Compare options using focused research prompts
  3. 03Compile separate sub-question findings into one report

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/davidondrej/skills --skill deep-research

After installing, type/deep-researchin Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

Deep Research

Use DeepAPI (POST /v1/research/deep) for all deep research.

API key

Read API_KEY from the environment.

KEY=$API_KEY
BASE=${DEEPAPI_API_BASE_URL:-https://deepapi.co}

If the key is missing, stop and ask the user. Never print or log it. Get a key at deepapi.co.

1. Build the prompt

Follow the research-prompt skill. Write one self-contained paragraph:

  • Lead with the main question and the decision it informs.
  • Include all context and 3-6 numbered sub-questions. Keep one mission per prompt.
  • State what to include or avoid. Prefer primary sources; separate fact from inference.

Field limits: query ≤ 4000 characters (the prompt), optional context ≤ 8000, optional instructions ≤ 2000. Do not send model or provider; the API rejects them.

2. Run it

One call returns a cited answer, targeting 700-1,120 words. The server allows up to ~5 minutes.

IDK=$(uuidgen)   # keep this; retries must reuse the SAME Idempotency-Key
jq -n --rawfile p /tmp/dr_prompt.txt '{query:$p, maxCostUsd:"0.70"}' > /tmp/dr_body.json
curl -s --max-time 320 "$BASE/v1/research/deep" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDK" \
  -d @/tmp/dr_body.json > /tmp/dr_result.json

Minimum maxCostUsd is "0.35". Default to "0.70"; ask the user before raising it.

3. Save the report

jq -r '.status'                    /tmp/dr_result.json   # succeeded | failed
jq -r '.output.answer'             /tmp/dr_result.json   # the report
jq -r '.output.sources[]?.url'     /tmp/dr_result.json   # source URLs

Save a Markdown report with citation URLs beneath it. Only report costs if the user asks. If the answer has [n] citations but output.sources is empty, deliver it and tell the user.

For longer reports, run each numbered sub-question separately with its own Idempotency-Key, then combine the answers and sources into one Markdown file.

Failures and retries

  • HTTP 402 insufficient_credits: stop for a top-up at deepapi.co/credits, then retry with the same Idempotency-Key.
  • HTTP 429 rate_limit_exceeded: wait Retry-After seconds, then retry once.
  • status: failed / HTTP 502: report requestId and error.message. Do not retry in a loop.
  • Reusing an Idempotency-Key returns HTTP 200 with replayed: true and no new charge.
  • See the deepapi skill for envelope/auth details and other endpoints.

Comments

Markdown supported