AutoBrowse — Skill de Navigation Auto-Améliorant

Construisez des skills de navigation fiables par expérimentation itérative. Un agent interne browse le site (evaluate.ts). Vous — l'agent externe — lisez ce qui s'est passé et améliorez les instructions (strategy.md). Répétez jusqu'à ce que ça passe régulièrement.

Points d'entrée

L'invocation est flexible — les flags explicites et le langage naturel libre fonctionnent :

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

# Aussi possible — parsing libre :
/autobrowse https://flights.google.com/
/autobrowse book a flight on delta.com
/autobrowse fix the existing google-flights skill

Quand l'utilisateur passe une URL ou une instruction libre au lieu de --task <name> :

• Si une tâche existante dans ${WORKSPACE}/tasks/ correspond clairement au site/intent, utilisez-la.
• Sinon, choisissez un nom court en kebab-case, créez ${WORKSPACE}/tasks/<name>/task.md à partir de ${CLAUDE_SKILL_DIR}/references/example-task.md, remplissez l'URL/objectif selon ce que l'utilisateur a dit, et procédez. Dites à l'utilisateur le nom choisi en une ligne.

Comment l'exécuter

Étape 1 — Parser les arguments et s'orienter

Vérifiez ce qui a été passé :

• --task <name> → mode tâche unique
• --tasks a,b,c ou --all → mode multi-tâches (spawn des sous-agents)
• --iterations N → nombre de cycles évaluer → améliorer (défaut : 5)
• --env local|remote → environnement navigateur (défaut : local; utiliser remote pour les sites protégés par bot)

Si l'utilisateur a passé du texte libre, mappez-le à l'un des éléments 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) vivent dans un répertoire d'espace de travail dans le répertoire de travail courant — PAS à l'intérieur de ~/.claude/skills/. Cela tient les écritures de fichiers de l'agent interne en dehors du répertoire home de Claude et loin des frictions de permissions.

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

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

Si le répertoire de tâche (./autobrowse/tasks/<task>/task.md) n'existe pas encore, construisez-le :

mkdir -p ./autobrowse/tasks/<task>
cp ${CLAUDE_SKILL_DIR}/references/example-task.md ./autobrowse/tasks/<task>/task.md
# Puis éditez task.md pour décrire l'URL, les inputs, les étapes, et la sortie JSON attendue

La source du skill à ${CLAUDE_SKILL_DIR} reste en lecture seule — seul ./autobrowse/ dans CWD est écrit pendant l'entraînement. La graduation (étape finale) écrit un seul fichier vers ~/.claude/skills/<task>/SKILL.md.

Listez les tâches disponibles :

ls ./autobrowse/tasks/

Étape 3 — Multi-tâches : spawn des sous-agents en parallèle

Si vous exécutez plusieurs tâches, utilisez l'outil Agent pour spawn un sous-agent par tâche simultanément. Chaque sous-agent reçoit un prompt autonome pour exécuter la boucle autobrowse complète pour sa tâche :

"You are running the autobrowse skill for task <name>. Workspace: <absolute-path-to-workspace> (e.g. /path/to/project/autobrowse). Run <N> iterations of: evaluate → read trace → improve strategy.md → repeat. Use --env <env>. Pass --workspace <workspace> to every evaluate.mjs invocation. Follow the autobrowse loop instructions exactly.

When graduating, install the skill to ~/.claude/skills/<task-name>/SKILL.md with proper agentskills frontmatter (name + description). Do not just copy strategy.md — write a self-contained skill.

At the end, output a structured summary with: task name, pass/fail on final run, total cumulative cost, iterations completed, per-iteration table (iter number, turns, cost, status, hypothesis tested), and 2-3 bullet key learnings."

Spawner tous les sous-agents en parallèle, attendez que tous se terminent, puis collectez leurs résumés et écrivez le rapport de session.

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

La Boucle (exécutez ceci pour chaque tâche)

Démarrage d'itération

Vérifiez que ./autobrowse/tasks/<task>/task.md existe (construisez-le à partir du template si nécessaire — voir Étape 2). strategy.md est auto-créé vide par le harness à la première exécution.

Exigences

• ANTHROPIC_API_KEY doit être dans l'environnement (ou dans un fichier .env dans CWD — evaluate.mjs le charge automatiquement). S'il manque, le harness affiche une erreur claire et quitte; ne cherchez pas les clés dans d'autres chemins.

Exécutez l'agent interne

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

Ceci exécute la session navigateur et écrit une trace complète vers ./autobrowse/traces/<task>/latest/.

Lisez la trace

cat ./autobrowse/traces/<task-name>/latest/summary.md

Le résumé a la durée, le coût, les tours, le journal de décision, et la sortie JSON finale.

Si l'agent a échoué ou s'est coincé, regardez plus profondément :

• Lisez ./autobrowse/traces/<task-name>/latest/trace.json — cherchez le tour d'échec
• Lisez les screenshots autour du point d'échec avec l'outil Read

Formez une hypothèse

Trouvez le tour exact où les choses ont mal tourné. Quelle heuristique unique l'aurait évité ?

Exemples :

• "Après avoir cliqué sur le dropdown, attendez 1s — les options s'animent avant d'être cliquables"
• "Naviguez directement vers /pay-invoice/ — ignorez la page de destination"
• "Utilisez browse fill #field_3 value pas browse type — ce champ se vide au focus"
• "La page affiche un spinner au tour 8 — ajoutez browse wait timeout 2000 avant snapshot"

Mettez à jour strategy.md

Éditez ./autobrowse/tasks/<task-name>/strategy.md. Gardez tout ce qui a fonctionné. Corrigez l'échec spécifique. Ajoutez une heuristique concrète.

Les bonnes stratégies ont :

• Chemin rapide : URL directe ou raccourcis pour ignorer l'exploration
• Workflow étape par étape : séquence exacte avec notes de timing
• Connaissance spécifique du site : sélecteurs ID, noms de champs de formulaire, indicateurs de succès
• Récupération d'échecs : quoi faire quand X échoue

Jugez le résultat

Lisez le nouveau résumé. Est-ce que ça a passé? Progression claire?

• Succès ou progrès → gardez, prochaine itération
• Pas de progrès ou régression → revertez strategy.md à la version précédente et essayez une hypothèse différente

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

Si la tâche a passé sur 2+ des 3 dernières itérations ou a atteint la limite d'itération max, installez-la comme un skill Claude Code. Ne copiez pas simplement strategy.md — le skill doit être autonome et utile à quelqu'un qui n'a jamais vu ce codebase. Si vous graduez aux itérations max sans succès net, notez le point d'échec connu mais documentez quand même tout ce qui a été appris.

Installez en écrivant vers ~/.claude/skills/<task-name>/SKILL.md :

mkdir -p ~/.claude/skills/<task-name>

Utilisez cette structure pour SKILL.md :

---
name: <task-name>
description: <1-2 phrases décrivant ce que ce skill fait et quand l'utiliser. Incluez les mots-clés de déclenchement.>
---

# <Titre de la Tâche> — Browser Skill

## Purpose
<1-2 phrases : ce que cela automatise et pourquoi ça existe.>

## When to Use
<Quand quelqu'un devrait utiliser ce skill.>

## Browse CLI Reference
L'agent interne utilise le CLI `browse`. Commandes clés pour cette tâche :
- `browse stop` — tuer la session existante (toujours exécuter avant de basculer en remote)
- `browse env remote` — démarrer une nouvelle session cloud Browserbase
- `browse newpage <url>` — ouvrir URL dans un nouvel onglet (requis en mode remote — `browse open` échoue avec "no page available")
- `browse open <url>` — naviguer l'onglet existant (mode local uniquement)
- `browse wait load` — attendre que la page finisse de charger
- `browse wait timeout <ms>` — attendre un temps fixe pour les spinners ou animations
- `browse wait selector "<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 (préféré pour l'extraction de contenu)
- `browse snapshot` — obtenir l'arbre d'accessibilité; chaque nœud a une ref au format `[X-Y]` (ex. `[0-5]`, `[2-147]`)
- `browse click [X-Y]` — cliquer l'élément par ref du dernier snapshot (inclure les crochets)

**Ne jamais utiliser les flags `--session <name>` dans SKILL.md.** Les sessions nommées sont une contournement pour les exécutions parallèles — elles contaminent les skills avec des préoccupations d'infrastructure. Les skills doivent fonctionner en isolation avec la session par défaut.

## Workflow

### Step 1 — Start session
<commandes browse exactes dans l'ordre>

### Step 2 — Navigate
<URL exacte et étapes de vérification>

### Step 3 — Extract
<commandes d'extraction exactes>

### Step 4 — Output
<quel JSON émettre, référençant le schéma ci-dessous>

## Site-Specific Gotchas
<Liste à puces de chaque heuristique acquis dur à partir des itérations. C'est la valeur centrale du skill.>

## Failure Recovery
<Quoi faire quand la navigation échoue, la session est contaminée, ou l'extraction retourne des ordures>

## Expected Output
```json
<collez le schéma de sortie exact attendu depuis task.md>

Après avoir écrit SKILL.md, confirmez qu'il est installé :
```bash
ls ~/.claude/skills/<task-name>/SKILL.md

Le skill est maintenant disponible en tant que /<task-name> dans Claude Code.

Rapport final (mode multi-tâches)

Après que tous les sous-agents se terminent, imprimez un tableau markdown :

Puis écrivez un rapport de session persistant vers ./autobrowse/reports/ afin qu'il y ait un registre durable de la session à l'intérieur de l'espace de travail :

mkdir -p ./autobrowse/reports

Écrivez le fichier ./autobrowse/reports/YYYY-MM-DD-HH-MM-<tasks>.md avec :

# AutoBrowse Session Report
**Date:** <ISO date>
**Tasks:** <comma-separated list>
**Environment:** remote|local
**Total cost:** $X.XX

## Results

| Task | Iterations | Pass Rate | Final Status | Graduated | Cost |
|------|-----------|-----------|--------------|-----------|------|
| ... | ... | X/5 | ✅/❌ | yes/no | $X.XX |

## Per-Task Learnings

### <task-name>
- **Key insight 1:** <what the agent learned>
- **Key insight 2:** <another heuristic>
- **Failure mode fixed:** <what was failing and how it was resolved>

## Iteration Log

### <task-name>
| Iter | Turns | Cost | Status | Hypothesis tested |
|------|-------|------|--------|-------------------|
| 1 | 79 | $18.75 | ❌ fail | baseline |
| 2 | 9 | $0.26 | ✅ pass | session contamination fix |
| ... | ... | ... | ... | ... |

Règles

• Éditez uniquement strategy.md — ne touchez jamais task.md (sauf si le créant à partir du template) ou evaluate.mjs
• Restez dans l'espace de travail — tous les écritures d'entraînement vont vers ./autobrowse/, jamais vers ~/.claude/skills/autobrowse/. La source du skill est en lecture seule.
• Une hypothèse par itération — testez un changement à la fois
• Construisez sur les victoires — gardez ce qui a fonctionné, ajoutez-y
• Faites confiance à la trace — l'agent interne montre exactement ce qu'il a vu et fait
• Graduez vers ~/.claude/skills/ — le seul fichier que vous écrivez là est le SKILL.md final gradué