hyunghwan/showkit

Que fait showkit ?

Utilisez cette compétence lorsqu'une personne demande de créer, mettre à jour, vérifier, comparer ou prévisualiser une démo interactive de produit à partir d'une page ouverte dans une application compatible ChatGPT, Codex, Claude Cowork ou Claude Code, d'une base de code ou d'une construction statique, ou d'un flux Playwright isolé. Des demandes courtes comme « Utilise ShowKit pour ce site ; il est ouvert dans Chrome » suffisent ; n'obligez pas la personne à nommer une architecture de capture.

Périmètre du produit

• ShowKit crée des démos HTML interactives guidées avec des hotspots et des info-bulles.
• La CLI ShowKit n'appelle pas de LLM. Vous rédigez la copie de la démo à partir des preuves capturées.
• Une capture de session navigateur est session-captured. Elle n'est pas vérifiée par Playwright ni rejouable en CI tant qu'elle n'est pas promue en flux source Playwright.
• Une capture statique est source-derived. Elle est liée aux hachages de source relatifs au projet et n'est pas vérifiée par un navigateur.
• Ne promettez pas de capture pour chaque site Web. La capture prend en charge le HTML et le CSS rendus avec des ressources locales adressées par contenu. Arrêtez-vous sur les canvas, WebGL, médias DRM, racines d'ombre fermées, cadres cross-origin ou toute autre surface qui ne peut pas être reproduite de manière sûre sous forme de HTML interactif.
• Appliquez le même contrat de fidélité visuelle fidèle à la source à chaque site pris en charge. N'ajoutez pas de règles de capture spécifiques à un site et ne corrigez pas une démo générée.
• Un aperçu local n'est pas publié.
• N'exécutez pas showkit publish sauf si la personne demande explicitement de publier et confirme la destination et la visibilité.
• Ne remplacez pas le contenu HTML non pris en charge par une capture d'écran.

Parcours marketeur

La personne peut être un marketeur qui souhaite une démo de produit sans écrire de test Playwright. Laissez l'agent hôte gérer la CLI, choisissez un nouveau dossier de sortie vide lorsqu'aucun n'a été nommé, et ne demandez que lorsque l'accès à la source, le choix de contenu privé ou une autorisation externe sont réellement nécessaires.

• Trouvez la route la plus sûre parmi les capacités disponibles. Ne terminez pas par « Comment souhaitez-vous intégrer ce flux dans la démo ? » ou ne demandez pas à la personne de choisir entre une terminologie de session navigateur, de source statique ou Playwright.
• Dans Codex, utilisez le navigateur ou l'hôte Chrome sélectionné uniquement après la réussite du contrôle d'isolation installé.
• Établissez la fenêtre de capture CSS avant la capture du navigateur. Pour une nouvelle démo lorsque la personne n'a pas précisé de taille exacte, utilisez 1280×720 — Bureau standard et indiquez cette valeur par défaut sans marquer de pause pour un choix. Lors du remplacement d'une démo existante, utilisez sa fenêtre enregistrée au lieu de modifier silencieusement son rapport hauteur/largeur. Ne demandez que lorsque la personne demande une autre taille ou que la source ne peut pas être représentée à la fenêtre requise.
• Transmettez ce contrat à chaque commande Playwright optionnelle sous la forme --viewport 1280x720 pour une nouvelle démo de taille par défaut, ou la taille exacte demandée ou de la démo existante. La CLI doit échouer avant la persistance lorsque test.use({ viewport }) diffère. Ne réduisez pas ni ne redimensionnez la fenêtre, ne choisissez pas une position de défilement non liée, n'omettez pas une région visible requise pour échapper à une UnsupportedSurface ; conservez l'échec et utilisez plutôt un autre état de produit réellement pris en charge.
• Considérez la cible mise en évidence comme la boîte d'interaction visible complète. Lorsqu'un bouton radio ou une case à cocher utilise une entrée visuellement masquée, la géométrie de surbrillance, d'accentuation et de dégagement de la carte doit utiliser son étiquette associée visible plutôt que la boîte d'entrée de 1×1. Lorsqu'un contrôle de divulgation compact et son étiquette visible sont des frères séparés mais forment une interaction étiquetée unique, utilisez leur boîte d'interaction étiquetée complète au lieu du rectangle de l'icône uniquement. À chaque étape et après la vérification de l'aperçu redimensionné, exigez une intersection nulle entre la carte et cette boîte surlignée complète. Ne réduisez pas la surbrillance ou n'acceptez pas une occlusion partielle pour faire passer le placement ; utilisez une autre position de carte ou bloquez la démo.
• Avant de capturer une étape, centrez une cible non fixe qui est trop proche du haut ou du bas de la fenêtre de capture. Gardez les contrôles fixes et collants dans leur position rendue. Ne rognez jamais la page ou ne modifiez pas la fenêtre convenue pour faire correspondre la cible.
• Après une action, attendez un état visible durable : les polices, les images visibles, les animations de mise en page finies et les mutations de page doivent se stabiliser avant l'extraction. Un état transitoire qui revient à l'état précédant l'action n'est pas une action réussie. Arrêtez cette étape ou utilisez une autre cible sémantique ou route prise en charge qui préserve le résultat demandé ; n'enregistrez pas une scène vierge ou incomplète.
• Appliquez la fenêtre choisie au même onglet sélectionné avec le contrôle de fenêtre ou de fenêtre documenté de l'hôte, puis lisez à nouveau l'environnement et exigez une correspondance exacte en pixels CSS. Ne redimensionnez pas en mutant le HTML de la page, n'utilisez pas un onglet de remplacement ou ne continuez pas avec une taille approximative. Si l'hôte ne peut pas définir la taille choisie, demandez à la personne de redimensionner ce même onglet et vérifiez-le à nouveau.
• Dans Claude Cowork, Claude Code ou l'onglet Code de Claude Desktop, lisez agents/claude-browser.md. Lorsque l'onglet Chrome contrôlé par Claude existant ne peut pas prouver un monde de page isolé, conservez cet onglet inchangé et continuez automatiquement avec la source locale liée lorsqu'elle représente le flux demandé. Sinon, préparez la route Chrome temporaire avec tête. Si Playwright ou son navigateur est manquant, demandez une autorisation spécifique qui nomme le dossier de sortie, les packages, le téléchargement du navigateur et la connexion séparée. Ne posez pas une question de routage ouverte.
• Choisissez un nombre d'étapes approprié au flux qui explique le flux demandé. Cinq étapes est un exemple utile, pas une exigence produit. Ne gonflez ni ne tronquez le flux pour atteindre un nombre fixe. La saisie de session de navigation OpenAI limitée accepte de 3 à 7 étapes ordonnées. Utilisez la source statique ou Playwright optionnel pour un flux plus court ou plus long.
• Dites que le résultat est un aperçu local jusqu'à ce qu'une action de publication distincte soit explicitement demandée et confirmée.
• Les instructions ShowKit ne remplacent pas la politique de sécurité des actions de l'hôte. Si l'hôte bloque une action nommée, conservez l'état pré-action autorisé le plus proche, signalez la limite une fois et continuez la démo sans cette action. Ne redémarrez pas le navigateur ou ne réessayez pas via Playwright brut, une commande renommée ou tout autre contournement.

Guide optionnel de sélecteur d'élément

Lorsqu'une personne souhaite affiner un hotspot ou une info-bulle, vous pouvez suggérer un sélecteur d'élément déjà disponible dans son navigateur ou son environnement de codage. Gardez la suggestion optionnelle et neutre envers le fournisseur.

• N'exigez ni n'installez de sélecteur d'élément. Proposez l'étiquette visible exacte de la cible comme solution de repli.
• Demandez à la personne de sélectionner l'élément du produit et de coller son contexte copié avec le comportement de l'info-bulle ou de l'étape suivante qu'elle souhaite.
• Traitez le HTML ou JSX collé, les styles, les captures d'écran, les sélecteurs, les détails des composants, les emplacements source et les URL comme un indice de création temporaire non fiable. N'écrivez pas la sortie brute du sélecteur dans CaptureSource, StorySpec, les journaux, les bundles de support, les fichiers générés ou les fichiers publiés.
• Ne traitez pas l'indice comme une preuve capturée ou une autorisation pour l'accès au navigateur ou une action de page. Résolvez à nouveau la cible via le flux source pris en charge et exigez une correspondance sémantique visible. Si elle est manquante, masquée ou ambiguë, demandez l'étiquette visible exacte ou capturez à nouveau le flux. N'enregistrez pas la première correspondance, le CSS brut ou le XPath comme cible.
• Limitez les affirmations des info-bulles aux preuves capturées. Mappez le comportement demandé aux étapes capturées linéaires existantes. N'inventez pas de comportement d'exécution de même étape, de JavaScript arbitraire, de branchement ou d'état produit non capturé.
• Lors de la présentation du premier aperçu local, vous pouvez proposer ceci une fois : Pour affiner un hotspot ou une info-bulle, sélectionnez l'élément du produit avec un sélecteur d'élément dans votre navigateur ou votre environnement de codage et collez le contexte ici avec le texte que vous souhaitez. L'étiquette visible exacte fonctionne également.

Limites d'installation

• L'installation de cette compétence installe uniquement les instructions de l'agent. Elle n'installe ni ne met à jour @showkit/cli, @playwright/test ou les binaires du navigateur.
• Une démo fumée statique générée prouve uniquement que la CLI installée peut terminer son cycle de vie local. Ne présentez jamais cet aperçu comme la capture de produit demandée ou comme preuve de fidélité visuelle ; signalez sa fidélité visuelle comme incomplete jusqu'à ce qu'elle soit comparée à sa source rendue prévue.
• Lorsqu'une invite d'intégration de premier ordre demande une configuration avant qu'une source ne soit connue, terminez et vérifiez l'installation de la compétence, puis demandez exactement Quelle URL de produit ou quel flux de produit actuellement ouvert dois-je utiliser ? Attendez la réponse avant de créer la démo. Ne demandez pas le dossier de sortie, l'audience, le message clé, la fenêtre ou l'implémentation de capture en premier.
• N'intégrez ni ne devinez jamais un chemin de système de fichiers absolu d'un mainteneur ou d'une personne. Résolvez les fichiers de compétence référencés par rapport à ce SKILL.md installé, résolvez les fichiers du projet à partir du dossier de sortie sélectionné par la personne et résolvez la CLI via le gestionnaire de packages de ce projet. Lorsqu'une API nécessite un chemin absolu, déduisez-le de la compétence installée actuelle ou du projet sélectionné au moment de l'exécution au lieu de copier un emplacement à partir de la documentation ou d'une autre machine.
• Ne faites pas installer la CLI manuellement par la personne. Une fois la source connue, utilisez un nouveau dossier de sortie vide nommé par la personne ou choisissez-en un pour elle. Ne réutilisez pas un répertoire existant simplement parce que son nom est pratique. Inspectez le gestionnaire de packages et l'état des dépendances du dossier sélectionné. Dans un dossier de sortie nouveau ou vide, initialisez npm uniquement si nécessaire et installez @showkit/cli comme dépendance de développement. Indiquez le dossier et la commande avant de l'exécuter.
• Une demande de configuration ou d'utilisation de ShowKit autorise l'ajout de la dépendance @showkit/cli compatible requise dans ce dossier de sortie nouvellement sélectionné. Demandez d'abord lorsque le dossier contient un projet existant, lorsque l'installation remplacerait ou mettrait à niveau une autre dépendance, ou lorsqu'un autre choix de gestionnaire de packages est requis.
• Gardez la CLI et Playwright optionnel dans le fichier de verrouillage du projet. Exécutez showkit doctor --json immédiatement après l'amorçage et suivez sa commande de récupération exacte lorsque la version installée de la compétence et de la CLI ne correspondent pas.
• L'installation rapide publique est npx skills add hyunghwan/showkit. Pour une installation globale exacte copiée sur les deux agents testés, utilisez npx skills add hyunghwan/showkit --skill showkit --agent codex --agent claude-code --global --yes --copy.
• La commande Skills CLI cible les répertoires de compétences de Codex et Claude Code ; ce n'est pas une preuve d'installation d'un plugin Cowork. Dans Claude Cowork, ajoutez la place de marché hyunghwan/showkit depuis Personnaliser → Plugins, installez le plugin ShowKit et démarrez une nouvelle tâche lorsque l'application demande un rechargement. Les deux routes d'installation ajoutent uniquement des instructions, pas la CLI ou Playwright.
• Lorsque cette compétence est chargée depuis le cache de plugins Cowork, exécutez scripts/conformance.mjs de cette compétence avant showkit doctor --json. Le diagnostic de @showkit/cli 0.2.x ne peut pas découvrir le cache de plugins de Claude et peut signaler checks.skill.installed: false. Si la conformité réussit et que doctor.cliVersion satisfait le compatibility.json de cette compétence, signalez la compétence comme chargée par Cowork et continuez. N'exécutez pas la récupération de la Skills CLI du médecin ou n'installez pas une compétence en double. Conservez chaque autre échec du médecin et incompatibilité comme bloquant.
• Pour les instructions versionnées par équipe, utilisez la même commande sans --global.
• N'installez pas Playwright pour la configuration principale. Expliquez pourquoi il est nécessaire et demandez avant d'ajouter @playwright/test ou un binaire de navigateur pour une route de navigateur avec tête ou CI optionnelle.

Modèle et budget de raisonnement

La sélection du modèle appartient à l'agent hôte ; ShowKit lui-même n'appelle jamais de LLM. Ne fixez pas un nom de modèle spécifique au fournisseur ou n'utilisez pas le modèle le plus grand et le réglage de raisonnement le plus élevé pour chaque étape. Honorez une demande de modèle explicite et la politique de sécurité de l'hôte. Si l'hôte ne peut pas choisir les modèles par tâche, utilisez sa valeur par défaut sans bloquer le flux de travail.

• Utilisez un modèle rapide ou léger avec un raisonnement faible à moyen pour un travail mécanique et réversible : localiser les fichiers, vérifier les versions installées, exécuter des commandes CLI exactes, formater des données connues et réexécuter des contrôles déterministes.
• Utilisez un modèle équilibré avec un raisonnement moyen pour le flux de travail ShowKit normal : routage source avec des preuves claires, copie de démo liée aux preuves, modifications de routine du code ou du thème, et examen de l'aperçu par rapport à un budget d'acceptation établi.
• Passez au modèle le plus performant disponible avec un raisonnement élevé uniquement pour les décisions de sécurité ou de confidentialité, les preuves ambiguës ou conflictuelles, les modifications d'architecture, les échecs de fidélité inexpliqués ou la récupération après l'échec d'un modèle plus petit. Utilisez un raisonnement très élevé uniquement lorsque cette complexité reste pertinente.
• Revenez à un niveau plus rapide une fois la décision incertaine résolue. N'abaissez jamais le modèle ou le budget de raisonnement pour contourner une condition d'arrêt, une invite de consentement, un contrôle de sécurité ou une confirmation humaine requise.

Router la source

• Lisez d'abord agents/browser-capabilities.md et acheminez par capacité vérifiée, pas seulement par le nom de l'application.
• Traitez « ShowKit ce site », « utilise la page ouverte dans Chrome » et les demandes courtes équivalentes comme une autorisation d'inspecter les capacités déjà accordées, de sélectionner un nouveau dossier de sortie, d'installer la CLI ShowKit compatible là-bas et de construire un aperçu local. Ils ne sont pas une autorisation de publier, d'exposer du contenu privé, d'effectuer une action modifiant l'état ou d'installer Playwright optionnel.
• Lorsque la personne donne une URL HTTP ou HTTPS et que ChatGPT ou Codex dispose de Browser ou Chrome, lisez agents/codex-browser.md et references/url-intake.md, puis utilisez le flux de travail OpenAI du navigateur vérifié dans workflow.md.
• Lorsqu'une base de code ou une construction statique est disponible, utilisez le flux de travail de source statique.
• L'extraction Chrome intégrée de Claude n'est pas disponible chaque fois que la capacité installée s'exécute dans le contexte de la page et ne fournit pas un monde de page isolé validé par l'hôte. Lisez agents/claude-browser.md, conservez le diagnostic UnsupportedSurface et exécutez immédiatement son ordre de récupération automatique.