Imported from naveedharri/benai-skills (shared-skills/research/SKILL.md). Install upstream with npx skills add naveedharri/benai-skills --skill research. Copyright stays with the author.

Deep Research

Turns a research request into a comprehensive, sourced report using the OpenAI Deep Research API. The orchestration script assesses the prompt, enhances it through clarifying questions when needed, saves the exact prompt for reproducibility, runs the research, and saves a markdown report with numbered sources.

Steps

1. Accept the user's research request (brief or detailed).

2. Decide whether to enhance. If the prompt is brief or generic, ask the 2-3 clarifying questions in references/prompt-enhancement.md (present numbered options plus a free-text option) and build the enhanced prompt. Skip when the prompt is already specific.

3. Confirm the final prompt with the user before executing. A run costs API spend and takes 10-20 minutes, so get a yes on the enhanced prompt first.

4. Run the orchestration script:

   python3 scripts/run_deep_research.py "<prompt>"

   It re-runs the enhancement check, saves research_prompt_*.txt, and executes synchronously. Options and output files are in references/cli.md. Wait silently for completion; do not poll for status.

5. Present results: the markdown report (research_report_*.md), the numbered source URLs, and the saved file paths. Offer follow-up research directions.

Routing

• references/prompt-enhancement.md: when to enhance, the question templates (technical vs general), how to build the enhanced prompt, worked examples.
• references/cli.md: script options, output files, execution behavior.
• references/troubleshooting.md: requirements and error fixes (missing API key, script not found, timeout).

Self-improvement

This skill is never finished. Improve it as you use it.

• When the user corrects how a step was done, update the relevant reference file (or this SKILL.md) so the correction sticks. Do not just fix it for this run.
• When a correction is a hard rule ("always X", "never Y"), add it as a permanent rule here.
• When the user says a research report was genuinely good, save it to references/examples/ so it becomes a model for future runs.
• Keep the skill small: when you add something, run the deletion test and cut anything that no longer changes behavior.