Compétence Walkthrough GIF

Que fait Compétence Walkthrough GIF ?

Génère un projet Node.js autonome qui enregistre un walkthrough navigateur et exporte en MP4 + GIF.

Quand utiliser cette compétence vs. l'outil gif_creator de claude-in-chrome

Pour une capture rapide et unique dans la session live du navigateur (son profil, ses onglets ouverts, déjà connecté), l'outil gif_creator de claude-in-chrome est bien plus simple — pas de projet à initialiser, pas de clés API. Utilisez cette compétence lorsque l'utilisateur a besoin de quelque chose que gif_creator ne peut pas fournir : un script réexécutable / versionnable (réenregistrer après chaque changement UI), une sortie MP4, un GIF gifski de haute qualité, un enregistrement avec un profil propre (pas de marque-pages personnels/extensions dans l'image), ou une répétabilité CI.

Architecture

Description en langage naturel
        ↓
Claude génère un script TypeScript
        ↓
Stagehand v3 (contrôle IA du navigateur) — Playwright attaché via CDP
        ↓
Contexte d'enregistrement Playwright capture la vidéo (.webm)
        ↓
ffmpeg convertit → .mp4
gifski convertit les images → .gif
        ↓
Sortie : walkthrough.mp4 + walkthrough.gif + walkthrough.md

Workflow

Étape 1 : Recueillir les exigences

Prérequis — Clé API LLM : Stagehand appelle un LLM pour chaque action IA. L'utilisateur a besoin de ANTHROPIC_API_KEY (ou de la clé du fournisseur correspondant au modèle configuré, par ex. OPENAI_API_KEY) disponible pour .env. Confirmez cela dès le départ — sans elle, le script généré ne peut pas s'exécuter.

Avant de générer du code, confirmez :

1. URL cible — Où commence le walkthrough ? (par ex., https://app.example.com/login)
2. Description du flux — Quelles étapes doivent être démontrées ? (le langage naturel convient)
3. Situation d'authentification — La page est-elle publique ou nécessite-t-elle une connexion ? Si connexion : l'utilisateur va-t-il coder en dur les identifiants dans .env, utiliser une session/cookie pré-authentifié, ou démarrer à partir d'un état connecté ?
4. Format de sortie — GIF uniquement, MP4 uniquement, ou les deux ? (par défaut : les deux)
5. Durée / rythme — Démo rapide ou délibérée étape par étape ? (~1-2 s de pause entre les étapes par défaut)
6. Viewport — Par défaut 1280×800. Plus étroit pour les démos mobiles.

Si l'utilisateur donne une description riche dès le départ, déduisez ce que vous pouvez et ne demandez que les lacunes.

Étape 2 : Générer le projet

Générez un projet complet et exécutable dans ./walkthrough-[nom]/ :

walkthrough-[nom]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   └── walkthrough.ts      ← script principal
└── scripts/
    └── convert.sh          ← conversion ffmpeg + gifski

Lisez references/stagehand-patterns.md pour l'API Stagehand et les modèles de traduction d'étapes. Lisez references/output-pipeline.md pour les commandes de conversion ffmpeg/gifski et le réglage des GIF.

Étape 3 : Traduire les étapes

Convertissez la description en langage naturel de l'utilisateur en appels stagehand.act() (v3 : act() vit sur l'instance stagehand et prend une chaîne simple, avec des options comme variables et page). Voir references/stagehand-patterns.md pour les motifs et les pièges.

Règles de traduction clés :

• Chaque action UI logique = un appel stagehand.act("...", { page }) avec une instruction claire en anglais
• Les entrées tapées passent par variables (placeholders %name%) — jamais de secrets en ligne dans la chaîne d'instruction
• Ajoutez page.waitForTimeout(1500) entre les étapes principales pour le rythme (visible pour le spectateur)
• Ajoutez page.waitForLoadState('networkidle') après les navigations
• Ne codez jamais en dur les sélecteurs — Stagehand les déduit des instructions en langage naturel
• Pour les flux nécessitant une authentification : utilisez .env pour les identifiants, jamais de valeurs en dur

Étape 4 : Stratégie d'enregistrement

Utilisez toujours l'enregistrement vidéo Playwright comme méthode de capture principale :

• Stagehand v3 n'a pas d'enregistrement intégré — connectez Playwright au navigateur de Stagehand via chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() }), créez un contexte avec l'option recordVideo, et pilotez la page de ce contexte (voir references/stagehand-patterns.md)
• Enregistrez la session complète en .webm via ce contexte d'enregistrement
• N'essayez PAS de concaténer des captures d'écran individuelles en GIF directement — vidéo → images → GIF est de meilleure qualité
• Après l'exécution du script, lancez convert.sh pour produire MP4 et GIF

Ne faites jamais du GIF l'artefact principal. Le MP4 est toujours produit en premier. Le GIF en est dérivé. Les GIF sont volumineux et de faible qualité pour tout ce qui dépasse 15 secondes — prévenez l'utilisateur et suggérez de limiter les walkthroughs à moins de 60 s.

Étape 5 : Surcouches de clic/curseur (optionnel mais recommandé)

Injectez une surcouche de mise en évidence des clics via page.addInitScript() avant le début du walkthrough. Voir references/stagehand-patterns.md → section "Click Overlay" pour l'extrait.

Cela ajoute une animation subtile d'ondulation à chaque point de clic — rend les walkthroughs considérablement plus lisibles sans post-traitement.

Étape 6 : Sortie

Après génération, produisez :

1. Le répertoire du projet (tous les fichiers)
2. Une brève liste de vérification dans la conversation :

## Configuration
npm install
npx playwright install chromium
cp .env.example .env  # remplir ANTHROPIC_API_KEY + tout identifiant

## Exécution
npx tsx src/walkthrough.ts

## Conversion en GIF + MP4
bash scripts/convert.sh

Dites aussi à l'utilisateur à quoi s'attendre : durée approximative, taille du viewport, noms des fichiers de sortie.

Proposez de l'exécuter : Claude Code peut exécuter tout le pipeline lui-même — npm install, npx playwright install chromium, exécuter le script walkthrough, puis bash scripts/convert.sh — si l'utilisateur est d'accord (il doit toujours fournir les valeurs .env). En l'exécutant vous-même, vérifiez la sortie avant de déclarer le succès : utilisez ffprobe sur le MP4 pour une durée raisonnable et vérifiez que les tailles des fichiers GIF/MP4 ne sont pas triviales (convert.sh affiche ces vérifications dans sa queue de vérification).

---

Avertissements / Conditions d'abandon

Informez l'utilisateur dès le départ si l'une de ces conditions s'applique :

Condition	Conseils
La page nécessite une connexion avec MFA/SSO	Le script ne peut pas gérer cela automatiquement — l'utilisateur doit exporter les cookies d'une session navigateur connectée
CAPTCHA sur la page cible	Playwright va bloquer — utilisez un environnement de démonstration/sandbox à la place
Animations lourdes / défilements infinis	L'enregistrement les capturera, mais la conversion en GIF sera volumineuse — suggérez de rogner
Flux > 90 secondes	Recommandez le MP4 uniquement ; le GIF sera trop volumineux pour être utilisable
Contenu de page aléatoire/dynamique	Stagehand gère le ciblage visuel, mais prévenez que les réexécutions peuvent sembler différentes

---

Convention de nommage des sorties

walkthrough-[slug]/
  output/
    walkthrough.webm     ← enregistrement Playwright brut
    walkthrough.mp4      ← converti (H.264, adapté au web)
    walkthrough.gif      ← sortie gifski, max 800 px de large
    walkthrough.md       ← annotation étape par étape (générée automatiquement)

Le fichier .md liste chaque appel act() comme une étape numérotée avec des horodatages — utile pour l'intégrer comme légende accompagnant le GIF.

---

Fichiers de référence

• references/stagehand-patterns.md — API Stagehand, traduction d'étapes, extrait de surcouche de clic, modèles d'authentification
• references/output-pipeline.md — commandes ffmpeg, drapeaux gifski, optimisation GIF, dépannage