AutoBrowse — Compétences en automatisation de navigateur par auto-amélioration

Développez des compétences fiables en automatisation de navigateur grâce à une expérimentation itérative. Un agent interne navigue sur le site (evaluate.ts). Vous — l’agent externe — lisez ce qui s’est passé et améliorez les instructions (strategy.md). Répétez l’opération jusqu’à ce que le test soit réussi de manière constante.

Points d’entrée

L’invocation est flexible : les indicateurs explicites et le langage naturel libre fonctionnent tous les deux :

/autobrowse --task google-flights
/autobrowse --task google-flights --iterations 10 --env remote
/autobrowse --task google-flights --browser-trace
/autobrowse --tasks google-flights,amazon-add-to-cart
/autobrowse --all

# Également valable — analyse libre :
/autobrowse https://flights.google.com/
/autobrowse réserver un vol sur delta.com
/autobrowse corriger la compétence google-flights existante

--browser-trace (désactivé par défaut, à distance uniquement) : associe chaque itération à la compétence sœur browser-trace — encapsule l’agent interne dans une capture CDP pour obtenir des preuves par page concernant le réseau, la console et le cycle de vie de la page. Implique --env remote; génère une erreur si combiné avec --env local. Nécessite la présence de la compétence « browser-trace » jumelle dans ${CLAUDE_SKILL_DIR}/../browser-trace/, ainsi que la variable d’environnement BROWSERBASE_API_KEY.

Lorsque l’utilisateur saisit une URL ou une instruction libre au lieu de l’ e --task:

• Si une tâche existante dans ${WORKSPACE}/tasks/ correspond clairement au site/à l’intention, utilisez-la.
• Sinon, choisissez un nom court en « kebab case », créez le fichier ${WORKSPACE}/tasks//task.md à partir de ${CLAUDE_SKILL_DIR}/references/example-task.md, complétez l’URL et l’objectif en fonction de ce que l’utilisateur a dit, puis poursuivez. Indiquez à l’utilisateur le nom choisi en une seule ligne.

Comment procéder

Étape 1 — Analyser les arguments et s’orienter

Vérifiez ce qui a été transmis :

• --task → mode tâche unique
• --tasks a,b,c ou --all → mode multitâche (lance des sous-agents)
• --iterations N → nombre de cycles d'évaluation → amélioration (par défaut : 5)
• --env local|remote → environnement du navigateur (par défaut : local ; utiliser « remote » pour les sites protégés par des bots)
• --browser-trace → active l'intégration de la trace du navigateur (désactivée par défaut). Implique --env remote. Si --env local et --browser-trace sont tous deux passés explicitement, une erreur s'affiche : « browser-trace nécessite Browserbase » ; supprimez --env local ou --browser-trace.

Si l’utilisateur a fourni un texte libre à la place, mappez-le à l’une des options ci-dessus avant de continuer.

Étape 2 — Configurer l’espace de travail

Tous les artefacts d’entraînement (définitions de tâches, itérations de stratégie, traces, rapports) se trouvent dans un répertoire « workspace » situé dans le répertoire de travail actuel — et NON dans ~/.claude/skills/. Cela permet d’éviter que les écritures de fichiers de l’agent interne n’affectent le répertoire personnel de Claude et d’éviter tout conflit d’autorisations.

Espace de travail par défaut : ${CWD}/autobrowse/

mkdir -p ./autobrowse/tasks ./autobrowse/traces ./autobrowse/reports

Si le répertoire de tâches (./autobrowse/tasks//task.md) n'existe pas encore, créez-le :

mkdir -p ./autobrowse/tasks/
cp ${CLAUDE_SKILL_DIR}/references/example-task.md ./autobrowse/tasks//task.md
# Modifiez ensuite le fichier task.md pour décrire l’URL, les entrées, les étapes et la sortie JSON attendue

La source de la compétence située dans ${CLAUDE_SKILL_DIR} reste en lecture seule — seul le ré pertoire ./autobrowse/ dans le répertoire de travail (CWD) est modifié pendant l’entraînement. La « graduation » (étape finale) écrit un seul fichier dans ~/.claude/skills//SKILL.md.

Liste des tâches disponibles :

ls ./autobrowse/tasks/

Étape 3 — Multitâche : lancer des sous-agents en parallèle

Si vous exécutez plusieurs tâches, utilisez l’outil Agent pour lancer simultanément un sous-agent par tâche. Chaque sous-agent reçoit une invite autonome lui permettant d’exécuter la boucle complète autobrowse pour sa tâche :

« Vous exécutez la compétence autobrowse pour la tâche . Espace de travail : (par ex. /chemin/vers/projet/autobrowse). Effectuez les itérations suivantes : evaluate → read trace → improve strategy.md → repeat. Utilisez --env . Passez --workspace à chaque invocation de evaluate.mjs. Si l'invocation parente a utilisé --browser-trace, vous DEVEZ utiliser le bloc traced-path de la boucle SKILL.md pour chaque itération (pré-créer une session, attacher bb-capture, passer --connect-url à evaluate.mjs, arrêt + bisection, publication) — ne revenez pas au chemin par défaut à commande unique. Suivez à la lettre les instructions de la boucle autobrowse.

À la fin du projet, installez la compétence dans ~/.claude/skills//SKILL.md avec une section d’en-tête agentskills correcte (nom + description). Ne vous contentez pas de copier strategy.md — rédigez une compétence autonome.

À la fin, générez un résumé structuré comprenant : le nom de la tâche, la réussite ou l’échec de l’exécution finale, le coût cumulé total, le nombre d’itérations effectuées, un tableau par itération (numéro d’itération, tours, coût, statut, hypothèse testée) et 2 à 3 points clés sous forme de puces. »

Lancez tous les sous-agents en parallèle, attendez qu’ils aient tous terminé, puis collectez leurs résumés et rédigez le rapport de session.

Pour une tâche unique, ignorez cette étape et exécutez la boucle ci-dessous.

La boucle (à exécuter pour chaque tâche)

Début de l’itération

Vérifiez que le fichier ./autobrowse/tasks//task.md existe (créez-le à partir du modèle s’il n’existe pas — voir l’étape 2). Le fichier strategy.md est créé automatiquement et vide par le harnais lors de la première exécution.

Prérequis

• ANTHROPIC_API_KEY doit être présent dans l’environnement (ou dans un fichier .env du répertoire de travail — evaluate.mjs le charge automatiquement). S’il manque, le harnais affiche une erreur claire et se termine ; ne cherchez pas de clés dans d’autres chemins.

Exécuter l’agent interne

Chemin par défaut (sans --browser-trace) — commande unique, sans orchestration :

node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task  --workspace ./autobrowse
# ou pour les sites protégés par un bot :
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task  --workspace ./autobrowse --env remote

Cela lance la session de navigateur et enregistre une trace complète dans ./autobrowse/traces//latest/.

Chemin de trace (--browser-trace, à distance uniquement) — le harnais externe pré-crée une session Browserbase, associe bb-capture en tant qu’observateur passif et transmet l’URL de connexion de la session ( connectUrl) à evaluate.mjs afin que chaque appel de navigation interne utilise --cdp $connectUrl --session autobrowse-main (le modèle canonique de browser-trace qui fournit aux observateurs l’intégralité des événements Network/Console). Exécutez ce bloc une fois par itération en définissant $N sur le numéro d’itération indexé à partir de 1 :

# Vérification préalable — échouer rapidement si browser-trace n’est pas installé aux côtés de autobrowse.
BT_DIR="${CLAUDE_SKILL_DIR}/../browser-trace"
if [ ! -f "$BT_DIR/scripts/bb-capture.mjs" ]; then
  echo "ERREUR : --browser-trace nécessite la compétence browser-trace à l'emplacement $BT_DIR." >&2
  echo "Installez-la en clonant github.com/browserbase/skills et en copiant le répertoire skills/browser-trace/" >&2
  echo "dans le même répertoire parent que autobrowse (par exemple ~/.claude/skills/browser-trace/)." >&2
  exit 1
fi

# a. CONFIGURATION DE LA SESSION — pré-créer la session keep-alive et en dériver l’URL de connexion
sid=$(browse cloud sessions create --keep-alive --verified --proxies \
  | node -e "let s='';process.stdin.on('data',c=>s+=c).on('end',()=>process.stdout.write(JSON.parse(s).id))")
connect_url=$(browse cloud sessions get "$sid" \
  | node -e "let s='';process.stdin.on('data',c=>s+=c).on('end',()=>process.stdout.write(JSON.parse(s).connectUrl))")

RUN_ID="run-$(printf '%03d' "$N")"
TRACE_ROOT="./autobrowse/traces//$RUN_ID"
mkdir -p "$TRACE_ROOT"
export O11Y_ROOT="$TRACE_ROOT/.o11y"   # stocke la sortie de browser-trace dans le répertoire d'exécution de autobrowse export O11Y_RUN_ID="$RUN_ID"           # indique à l'interface CLI de browse dans quel répertoire d'exécution écrire le fichier descriptors.ndjson

# b. LANCER BROWSER-TRACE — observateur passif ; s'exécute en arrière-plan
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bb-capture.mjs "$sid" "$RUN_ID" &
sleep 2

# c. EXÉCUTION d’ AUTOBROWSE — le drapeau connectUrl indique à evaluate.mjs d’injecter --cdp/--session
#    dans chaque appel interne à browse. L’agent interne ne voit jamais --remote.
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs \
  --task  --workspace ./autobrowse --env remote \
  --connect-url "$connect_url" --run-number "$N"

# d. STOP + BISECT + UNIFY — l’ordre est important ; bisect nécessite que la session
#    existe encore, et unify-trace fusionne la sortie de bisect avec le fichier trace.json de autobrowse#    en un seul NDJSON classé par ordre chronologique que l’agent externe lit en premier à chaque itération.
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/stop-capture.mjs "$RUN_ID"
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bisect-cdp.mjs "$RUN_ID"
node ${CLAUDE_SKILL_DIR}/scripts/unify-trace.mjs \
  --trace-dir "$TRACE_ROOT" \
  --o11y-dir "$O11Y_ROOT/$RUN_ID"

# e. RELEASE
browse cloud sessions update "$sid" --status REQUEST_RELEASE

Cela écrit la trace interne à l’agent dans ./autobrowse/traces//latest/ et la bisection CDP dans ./autobrowse/traces//latest/.o11y//. L’interface CLI de navigation tracée génère également, pour chaque commande, des descripteurs de nœuds riches vers .o11y//cdp/descriptors.ndjson (un objet JSON par appel générateur de page : balise cible/id/rôle/nom accessible/attributs/xpath/rectangle de délimitation). Le fichier de descripteurs alimente le générateur de code en aval ; il n’ est pas indispensable à la formulation d’hypothèses — ignorez-le lors de la lecture de la trace.

Lire la trace

cat ./autobrowse/traces//latest/summary.md

Le résumé contient la durée, le coût, les tours, le journal des décisions et la sortie JSON finale.

Si l’agent a échoué ou s’est bloqué, examinez la trace plus en détail :

• Lisez le fichier ./autobrowse/traces//latest/trace.json — recherchez le tour où l'échec s'est produit
• Consultez les captures d’écran autour du point d’échec à l’aide de l’outil Read

Lorsque l'option --browser-trace a été utilisée — commencez par unified-events.jsonl. Le harnais fusionne le journal des tours de l'agent et le flux CDP du navigateur en un seul flux NDJSON ordonné chronologiquement à la racine de l'exécution. Un seul fichier, balisé parsource (source : « agent » | « navigateur »), entrecoupé d’horodatages en temps réel. Parcourez-le de haut en bas ; la cause de l’échec se trouve généralement sur une ou deux lignes adjacentes (l’agent a émis la commande X, le navigateur a répondu par Y).

cat ./autobrowse/traces//latest/unified-events.jsonl

Les fichiers structurés (trace.json, .o11y//cdp/*) peuvent également être exploités par l'agent sous forme d'analyses approfondies lorsque le flux unifié met en évidence un élément sur lequel vous souhaitez obtenir davantage d'informations :

Le flux unifié est le paramètre par défaut ; n'explorez les fichiers structurés que lorsque vous avez besoin d'une requête groupée, d'une charge utile en texte intégral ou d'un filtrage que le flux ne peut pas vous fournir.

Formulez une hypothèse

Identifiez le moment précis où les choses ont mal tourné. Quelle heuristique unique aurait pu l’empêcher ?

Avec l'option --browser-trace, l'hypothèse doit citer un événement spécifique issu du fichier unified-events.jsonl (numéro de ligne ou horodatage) — ou indiquer le nom du fichier d'analyse détaillée si vous avez dû y accéder. Cela permet de s'appuyer sur des preuves concrètes plutôt que sur des impressions subjectives lors des mises à jour. Une hypothèse fondée uniquement sur les commandes de l’agent pourrait indiquer « le clic n’a pas fonctionné » ; s’appuyant sur le flux unifié, elle peut indiquer : « ligne 47 de unified-events.jsonl : la commande browse open a été suivie d’ un Network.responseReceived statut 403 sur /api/checkout — basculer vers --verified --proxies. »

Exemples :

• « Après avoir cliqué sur le menu déroulant, attendre 1 s — les options s’affichent en animation avant de devenir cliquables »
• « Accédez directement à /pay-invoice/ — ignorez complètement la page d’accueil »
• « Utilisez la valeur de remplissage #field_3 de la navigation et non le type de navigation — ce champ s’efface lorsqu’on le met en surbrillance »
• « La page affiche un indicateur de chargement au tour 8 — ajoutez un délai d’attente de navigation de 2000 avant la capture d’écran »
• (avec --browser-trace) « À la ligne 47 du fichier unified-events.jsonl, 3 événements Network.responseReceived consécutifs sur /api/availability ont renvoyé un code 403 juste après l’ouverture du navigateur — le site effectue une identification par empreinte digitale ; l’itération suivante nécessite les options --verified et --proxies. »

Mettez à jour strategy.md

Modifiez ./autobrowse/tasks//strategy.md. Conservez tout ce qui fonctionnait. Corrigez l’échec spécifique. Ajoutez une heuristique concrète.

Les bonnes stratégies comportent :

• Un chemin rapide: URL directe ou raccourcis pour éviter l’exploration
• Un workflow étape par étape: séquence exacte avec indications de timing
• Connaissances spécifiques au site: identifiants des sélecteurs, noms des champs de formulaire, indicateurs de réussite
• Récupération en cas d’échec: que faire lorsque X ne fonctionne pas

Évaluez le résultat

Lisez le nouveau résumé. A-t-il été validé ? Des progrès significatifs ont-ils été réalisés ?

• Réussite ou progrès → conserver,passer à l’itération suivante
• Pas de progrès ou régression → revenir à la version précédente de strategy.md et tester une autre hypothèse

Générer un script exécutable (facultatif)

Une fois que la tâche a convergé, vous pouvez produire un script déterministe et exécutable dans un ou plusieurs frameworks via scripts/codegen.mjs. Il s’agit d’un appel unique au LLM par framework, mis en cache par hachage de contenu, avec en option une vérification par rapport à une nouvelle session et une réécriture en cas d’échec.

node ${CLAUDE_SKILL_DIR}/scripts/codegen.mjs \
  --task  \
  --workspace ./autobrowse \
  --frameworks playwright,stagehand \
  --verify

Chaque framework dispose de son propre sous-répertoire sous tasks/// contenant le script généré et une structure de base autonome (package.json, tsconfig.json). Le répertoire est exécutable de manière autonome avec cd tasks//playwright && npm install && npx tsx .ts — la seule condition d’exécution requise est BROWSERBASE_API_KEY (ainsi que ANTHROPIC_API_KEY pour la cible Stagehand).

Frameworks intégrés : playwright, stagehand. Ajoutez un framework personnalisé avec --prompt-template --frameworks custom (et fournissez votre propre runner ou passez --no-verify).

Options courantes :

La sortie est constituée d’une ligne JSON par framework sur stdout. Code de sortie non nul si l’ état final d’un framework sélectionné est false.

Voir references/playwright-cdp-bridge.md pour les modèles canoniques connectOverCDP suivis par les scripts générés.

Après toutes les itérations — publier si prêt

Si la tâche a réussi au moins 2 des 3 dernières itérations ou a atteint la limite maximale d’itérations, installez-la en tant que compétence Claude Code. Ne vous contentez pas de copier strategy.md — la compétence doit être autonome et utile à quelqu’un qui n’a jamais vu cette base de code. Si la tâche atteint la limite d’itérations sans avoir réussi une fois, notez le point d’échec connu mais documentez tout ce que vous avez appris.

Installez-la en créant le fichier ~/.claude/skills//SKILL.md:

mkdir -p ~/.claude/skills/

Utilisez cette structure pour le fichier SKILL.md :

---
name: 
description: <1-2 sentences describing what this skill does and when to use it. Include trigger keywords.>
---

#  — Compétence de navigation

## Objectif
<1-2 sentences: what this automates and why it exists.>

## Quand l’utiliser


## Consultation de la référence CLI
L’agent interne utilise la CLI `browse`. Commandes clés pour cette tâche :
- `browse stop` — met fin à la session en cours (à toujours exécuter avant de basculer en mode distant)
- `browse open  --remote` — lance une nouvelle session Browserbase dans le cloud et permet de naviguer
- `browse open  --local` — lance un navigateur local vierge et permet de naviguer
- `browse tab new ` — ouvre l’URL dans un nouvel onglet
- `browse wait load` — attend que le chargement de la page soit terminé
- `browse wait timeout ` — attend un délai défini pour les indicateurs de chargement ou les animations
- `browse wait selector ""` — attendre qu’un élément devienne visible
- `browse get title` — vérifier que vous êtes sur la bonne page
- `browse get text body` — extraire tout le texte visible (méthode privilégiée pour l’extraction de contenu)
- `browse snapshot` — récupère l’arborescence d’accessibilité ; chaque nœud possède une référence au format `[X-Y]` (par ex. `[0-5]`, `[2-147]`)
- `browse click [X-Y]` — clique sur un élément par sa référence à partir du dernier instantané (inclure les crochets)

**N’utilisez jamais les indicateurs `--session ` dans SKILL.md.** Les sessions nommées constituent une solution de contournement permettant l’exécution en parallèle — elles contaminent les compétences avec des problèmes d’infrastructure. Les compétences doivent fonctionner de manière isolée avec la session par défaut.

## Déroulement

### Étape 1 — Démarrer la session


### Étape 2 — Navigation


### Étape 3 — Extraction


### Étape 4 — Sortie


## Pièges spécifiques au site


## Récupération après échec


## Sortie attendue
```json

Après avoir rédigé le fichier SKILL.md, vérifiez qu’il est bien installé :
```bash
ls ~/.claude/skills//SKILL.md

La compétence est désormais disponible sous la forme / dans Claude Code.

Rapport final (mode multitâche)

Une fois que tous les sous-agents ont terminé, affichez un tableau au format Markdown :

Ensuite, enregistrez un rapport de session persistant dans ./autobrowse/reports/ afin de conserver une trace durable de l'exécution au sein de l'espace de travail :

mkdir -p ./autobrowse/reports

Créez le fichier ./autobrowse/reports/AAAA-MM-JJ-HH-MM-.md avec le contenu suivant :

# Rapport de session d’ AutoBrowse **Date :** 
**Tâches :** 
**Environnement :** distant|local
**Coût total :** $X.XX

## Résultats

| Tâche | Itérations | Taux de réussite | Statut final | Réussite | Coût |
|------|-----------|-----------|--------------|-----------|------|
| ... | ... | X/5 | ✅/❌ | oui/non | $X,XX |

## Enseignements par tâche

### 
- **Enseignement clé n° 1 :** 
- **Enseignement clé n° 2 :** 
- **Mode de défaillance corrigé :** 

## Journal des itérations

### 
| Itér | Tours | Coût | Statut | Hypothèse testée |
|------|-------|------|--------|-------------------|
| 1 | 79 | 18,75 $ | ❌ échec | référence |
| 2 | 9 | 0,26 $ | ✅ réussite | correction de la contamination de session |
| ... | ... | ... | ... | ... |

Règles

• Modifiez uniquement le fichier strategy.md — ne touchez jamais au fichier task.md (sauf si vous le créez à partir du modèle) ni au fichier evaluate.mjs
• Restez dans l’espace de travail — toutes les écritures liées à l’entraînement vont dans ./autobrowse/, jamais dans ~/.claude/skills/autobrowse/. Le code source de la compétence est en lecture seule.
• Une hypothèse par itération — testez une modification à la fois
• S’appuyer sur les réussites — conserver ce qui a fonctionné et y ajouter des éléments
• Faites confiance à la trace — l’agent interne montre exactement ce qu’il a vu et fait
• Passez à ~/.claude/skills/ — le seul fichier que vous y enregistrez est le fichier SKILL.md final validé
• Ne publiez pas avant la bisection — avec l’option --browser-trace, l’ordre à la fin de chaque itération est impératif : stop-capture → bisect-cdp → parcourir les sessions cloud → mettre à jour REQUEST_RELEASE. La bisection nécessite que la session existe encore lorsque la trace s’arrête.