Skip to content

Add deep-research skill#127

Open
derekmeegan wants to merge 4 commits into
mainfrom
codex/deep-research-skill
Open

Add deep-research skill#127
derekmeegan wants to merge 4 commits into
mainfrom
codex/deep-research-skill

Conversation

@derekmeegan

@derekmeegan derekmeegan commented Jun 4, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add a new deep-research skill based on the planner, researcher, and synthesizer loop from ../agents/apps/deep-research.
  • Document Browserbase-backed search, fetch, and remote browser fallback through bb, browse cloud, direct API fallbacks, and the repo's browser skill.
  • Add a bundled PDF renderer that turns final markdown research reports into full PDF reports via Browserbase + Playwright by default, with --local smoke-test mode.
  • Register the skill in the README catalog and Claude plugin marketplace.

Changes

  • New skills/deep-research/SKILL.md workflow with planning, finding ledger, synthesis, PDF output, and completion checklist.
  • New skills/deep-research/scripts/render-report.mjs plus package.json/package-lock.json for PDF rendering.
  • README and marketplace descriptions now advertise cited markdown/PDF report output.
  • Browser fallback instructions support both browse open --remote and older browse env remote flows.
  • Deep research now points agents to skills/browser/SKILL.md for browser-mode mechanics such as remote mode, snapshots, screenshots, interactions, protected-site handling, and session cleanup.
  • Fetch fallback rules now explicitly treat dynamic/client-rendered signals as incomplete until browser mode extracts rendered content.

Test plan

  • git diff --cached --check
  • git diff --check
  • Parsed .claude-plugin/marketplace.json, skills/deep-research/package.json, and skills/deep-research/package-lock.json with node.
  • node --check skills/deep-research/scripts/render-report.mjs
  • npm ls --depth=0 in skills/deep-research
  • Rendered three report modes to PDF with local Chrome: general, prospect, contradiction.
  • Verified generated PDFs with file and byte counts.
  • Tested browser fallback mechanics with browse env local, browse open, browse get markdown, browse snapshot, browse stop.
  • Verified Browserbase remote PDF rendering and bb search/fetch fail clearly when BROWSERBASE_API_KEY is missing.
  • Loaded BROWSERBASE_API_KEY from the parent Browserbase .env without printing it and gathered Browserbase Search/Fetch evidence for full reports on geese, Paul Klein, and Derek Meegan.
  • Rendered the three full reports to PDF through Browserbase remote Playwright; verified each PDF is a valid 5-page A4 document.
  • Re-ran git diff --check after clarifying dynamic Fetch browser fallback behavior.
  • Re-ran git diff --check after adding the browser-skill reference.

Notes

Full Browserbase-backed test report artifacts were generated under .deep-research/full-reports-2026-06-04/ and intentionally left untracked.


Note

Low Risk
Adds documentation, marketplace metadata, and an optional Node renderer; no changes to existing runtime skills or auth paths beyond requiring BROWSERBASE_API_KEY for remote PDF sessions.

Overview
Adds a deep-research skill that turns agents into a Browserbase-backed planner–researcher–synthesizer: plan sub-questions, search/fetch via bb / browse cloud / APIs, fall back to remote browser when fetch is dynamic or blocked, maintain a citation ledger, and write cited markdown (plus optional PDF).

skills/deep-research/SKILL.md documents depth budgets, untrusted-web discipline, dynamic-fetch → browser rules, prospect report shape, and a completion checklist. scripts/render-report.mjs (Playwright + Browserbase CDP by default, --local for smoke tests) converts final markdown to A4 PDF with escaped HTML and safe link handling; package.json / lockfile pin @browserbasehq/sdk and Playwright.

README and .claude-plugin/marketplace.json register the skill and add a usage example for cited competitive research.

Reviewed by Cursor Bugbot for commit 7895021. Bugbot is set up for automated code reviews on this repo. Configure here.

For each sub-question:

1. Run 2-3 search query variations. Use parallel tool calls when the host supports them.
2. Fetch the top 3-5 relevant unique URLs. Prefer primary sources, official docs, filings, company pages, reputable reporting, and recent material.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quick depth contradicts plan

Medium Severity

quick allows 20 steps for a single narrow question, but Phase 1 still requires 3–7 sub-questions and Phase 2 still mandates 2–3 searches plus 3–5 fetches per sub-question. Following all sections exceeds the budget or forces incomplete research.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 981008c. Configure here.

await opened.browser.close().catch(() => {});
}

console.log(JSON.stringify({ ok: true, mode: opened.mode, output: outputPath }, null, 2));

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PDF success after load failure

Medium Severity

The renderer catches every page.setContent error and still runs page.pdf, then prints ok: true. Real load failures (not just late timeouts) can produce blank or truncated PDFs while the skill treats PDF generation as successful.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit fb7387b. Configure here.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 814f748. Configure here.

const browser = await chromium.launch({ headless: true });
return { browser, mode: 'local-playwright' };
}
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Browserbase sessions not released

Medium Severity

Remote PDF mode creates a Browserbase session via the SDK but never retains its id or calls REQUEST_RELEASE. Cleanup only invokes browser.close() on the CDP connection, which in-repo Browserbase guidance says can leave cloud sessions running and billable, including when connectOverCDP fails after sessions.create succeeds.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 814f748. Configure here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant