Skip to main content
skill CX Codex

optimize-agent-prompt — Claude Code skill

optimize-agent-prompt — a skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode that refines Browserbase Agent API system prompts through iteration loops: run a task, collect logs, score the result, revise one heuristic.

MIT 289 installs ★ 3,758 updated 2026-09-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add browserbase/skills --skill optimize-agent-prompt -a claude-code
Open on GitHub

What optimize-agent-prompt does

Holds the agent task, result schema, variables and evaluation criteria fixed while changing only systemPrompt. The optimize_agent_prompt.mjs script creates a workspace (init), runs an iteration (run), writes message logs, status and session trace to runs/<label>/, displays the trajectory (inspect) and comparison table (report).

Requires Node.js 18 or later and a BROWSERBASE_API_KEY environment variable. The script relies solely on Node.js built-in modules. Success checks evaluate COMPLETED status, populated or explicitly nullable fields, known-fact regexes and fabrication-warning regexes. Iterations stop when a prompt passes two of the last three runs and one pass is an unchanged confirmation. No FFmpeg or Playwright: the entire loop goes through the Browserbase Agent API and Node.js.

Limitation: the skill does not guarantee a global optimum, only the best prompt for the tested task distribution. Session logs are needed to distinguish a redirect, 403 or console error from a logic error in a tool call.

What it helps with

  • bring a Browserbase Agent prompt to stable task completion in minimal steps
  • pinpoint which turn the agent failed and which heuristic fixes it
  • collect regression or improvement evidence from traces and browser logs
  • lock in winning changes and roll back ones that did not work

Example prompts for the agent

  • Create an experiment called cart-extraction where the task is to extract cart items via Browserbase Agent
  • Run an iteration with prompt prompts/iteration-001.md, label baseline, show trajectory and summary
  • Compare all iterations in agent-prompt-optimization/cart-extraction and build a score table

How to install optimize-agent-prompt

1Skills CLI (Vercel)

npx skills add browserbase/skills --skill optimize-agent-prompt -a claude-code

2Manually: put the files in place

~/.claude/skills/optimize-agent-prompt/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/optimize-agent-prompt/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about optimize-agent-prompt

How do I install optimize-agent-prompt in Claude Code?

Run npx skills add browserbase/skills --skill optimize-agent-prompt -a claude-code, then open ~/.claude/skills/optimize-agent-prompt/SKILL.md.

What does optimize-agent-prompt do?

Runs a Browserbase Agent with a fixed task and varying system prompt, collects message and session logs, computes a score, revises one heuristic and checks for convergence. Brings the prompt to stable completion without manual trial and error.

What dependencies does optimize-agent-prompt need?

Node.js 18 or later and a BROWSERBASE_API_KEY environment variable. The script uses only Node.js built-in modules; no external libraries required.

Source text

SKILL.md · MIT
---
name: optimize-agent-prompt
description: "Builds and improves Browserbase Agent API demos through an Autobrowse-style outer loop: run a fixed task, collect Agent messages and session logs, score the result, revise one system-prompt heuristic, and confirm convergence. Use when creating a Browserbase Agents demo or POC, optimizing an Agent system prompt, diagnosing flaky Agent runs, or applying auto-research/autobrowse to the Browserbase Agents API."
license: MIT
allowed-tools: Bash Read Write Edit Grep Glob
---

# Optimize Agent Prompt

Optimize a Browserbase Agent's `systemPrompt` while holding its task, result schema, variables, and evaluation criteria fixed. Treat the outer agent as the teacher and each Browserbase Agent run as an inner-agent rollout.

Use Node.js 18 or later and set `BROWSERBASE_API_KEY`. The harness uses only Node.js built-in modules.

## Set up the experiment

Choose a short experiment name and create an isolated workspace inside the demo or POC repository:

```bash
node <skill-dir>/scripts/optimize_agent_prompt.mjs init \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --name <experiment-name>
```

Edit the generated files:

- `task.json`: keep `task`, `resultSchema`, variables, browser settings, and evaluation oracle stable across iterations.
- `prompts/iteration-001.md`: write the minimal baseline system prompt. Include irreversible-action guardrails when applicable.

Use concrete success criteria. Prefer a strict JSON Schema with required fields and `null` for unavailable facts. Add known-field regexes and factuality-warning regexes under `evaluation` when a truth oracle exists. Read [references/evaluation.md](references/evaluation.md) when designing the task or score.

## Run the baseline

```bash
node <skill-dir>/scripts/optimize_agent_prompt.mjs run \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --prompt prompts/iteration-001.md \
  --label iteration-001
```

The harness creates one reusable Browserbase Agent, updates its `systemPrompt` on later iterations, starts the run, polls messages and status, and writes:

```text
runs/<label>/
├── system-prompt.md
├── created-run.json
├── run.json
├── messages.json
├── session-logs.json
└── summary.json
```

It stops a run after the configured message budget instead of paying for an unproductive spiral. Use `--max-messages`, `--timeout-ms`, `--proxies`, or `--verified` only when the task needs different values from `task.json`.

## Diagnose from observable evidence

Start with the compact trajectory:

```bash
node <skill-dir>/scripts/optimize_agent_prompt.mjs inspect \
  --workspace ./agent-prompt-optimization/<experiment-name> \
  --label iteration-001
```

Then read `summary.json` and drill into `messages.json` at the first wrong or wasted turn. Agent messages expose ordered tool calls, tool results, errors, and final output. A `reasoning` part may contain no readable text; never require hidden chain-of-thought for the teacher loop.

Read `session-logs.json` only when browser-level evidence can distinguish the cause—for example, a redirect, 403, failed request, console error, or hidden endpoint. Empty session logs can mean the Agent completed with search/fetch tools and never drove its browser.

See [references/api.md](references/api.md) for endpoint shapes, pagination, result normalization, and trace caveats.

## Improve one heuristic

Find the earliest consequential failure and state one counterfactual:

> If the system prompt had instructed X, the Agent would have avoided Y, as shown by tool result Z.

Copy the current prompt to `prompts/iteration-NNN.md` and make one attributable change. Typical improvements are:

- cap retries after a repeated block or identical error;
- distinguish public identifiers from private/internal IDs;
- prefer search/fetch before launching a browser when interaction is unnecessary;
- separate current snapshots from dated historical events;
- define when a qualified fallback counts as completed;
- require `null` instead of guessed values;
- add a tool-call or evidence budget.

Keep wins. If the new run regresses, restore the previous prompt and test a different hypothesis rather than stacking more rules.

## Judge and converge

Generate the comparison table after each run:

```bash
node <skill-dir>/scripts/optimize_agent_prompt.mjs report \
  --workspace ./agent-prompt-optimization/<experiment-name>
```

Judge more than field completeness. Require:

- terminal status `COMPLETED`;
- required fields populated or explicitly nullable;
- known-fact checks passing when available;
- no factuality-warning match;
- provenance and safety constraints preserved;
- fewer messages or lower duration without quality loss.

Once a prompt wins, run it again unchanged with a new label. Converge only after it passes at least two of the last three runs and one pass is an unchanged confirmation. Do not call a prompt globally optimal from one task; describe it as the best prompt for the tested task distribution.

## Graduate into the demo

Use the confirmed prompt as the Agent's production `systemPrompt`. Keep the strict result schema and per-run variables. Preserve the experiment workspace or its report so reviewers can audit why each instruction exists.

In the final handoff, report:

- baseline versus winning score, duration, and message count;
- the first wrong turn each prompt change fixed;
- whether session logs added evidence;
- the winning prompt path;
- confirmation-run results;
- limitations and the next holdout matrix.

© browserbase · MIT · browserbase/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set18

The whole set →
event-prospecting event-prospecting takes a conference speakers page URL, extracts people, filters companies by ICP, and outputs an HTML report with person cards explaining why the AE should reach out. CX Codex +1 2,200installs browser-to-api browser-to-api reads a browser-trace capture and turns it into an OpenAPI 3.1 spec, a fetch client and a coverage report. Useful when the site you are integrating with has no published API docs. CX Codex +1 2,000installs safe-browser The skill builds a local browser agent whose only tool is safe_browser. Requests to hosts outside the allowlist fail at the CDP layer. CX Codex +1 1,800installs agent-experience agent-experience — a skill for Claude Code, Codex, Cursor, and other platforms that fires multiple subagents at your SDK, docs site, or SKILL.md and produces an HTML report with an A–F grade. CX Codex +1 936installs competitor-analysis competitor-analysis is a skill that researches competitors, finds new candidates, and builds an HTML feature and pricing report for market comparison. CX Codex +1 741installs webmcp-gen webmcp-gen — a Claude Code skill that builds site-specific WebMCP tools from a target URL and a description of the needed function. It writes the manifest, compiles an init script, and checks registration through Stagehand. CX Codex +1 633installs browser-use-to-stagehand browser-use-to-stagehand — a skill for Claude Code, Codex, Cursor and other platforms: converts Python browser-use scripts into TypeScript Stagehand v3 on Browserbase. Triggers on browser-use, Agent(task=...) or explicit migration requests. CX Codex +1 561installs add-webmcp add-webmcp is a Claude Code skill that adds WebMCP tools to an existing web app. It runs when a codebase needs to expose its features to AI agents. CX Codex +1 259installs

Project sponsors

Companies that keep this analytics open