# Optimize Agent Prompt

Builds and improves Browserbase Agent API demos through an Autobrowse-style outer loop...

- Repository: https://github.com/browserbase/skills (3748 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-27
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add browserbase/skills --skill optimize-agent-prompt -g -a claude-code -y`
Codex: `npx skills add browserbase/skills --skill optimize-agent-prompt -g -a codex -y`
Cursor: `npx skills add browserbase/skills --skill optimize-agent-prompt -g -a cursor -y`
Gemini CLI: `npx skills add browserbase/skills --skill optimize-agent-prompt -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add browserbase/skills`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/browserbase/skills/blob/HEAD/skills/optimize-agent-prompt/SKILL.md