Connect Recommend

Recommandez la bonne forme d'intégration Stripe Connect. L'utilisateur ne devrait avoir besoin de fournir que l'URL d'une entreprise ou de décrire son activité — le skill déduit le reste.

Modèle d'interaction

AskUserQuestion est l'outil d'interaction principal (Grok Build : ask_user_question). Chaque point de décision dans ce skill DOIT utiliser AskUserQuestion avec des options numérotées claires et des descriptions courtes. Une seule question à la fois — ne surcharchez jamais l'utilisateur.

Auto-exécutez les actions peu coûteuses. Ne demandez jamais la permission pour :

Générer le plan de recommandation en markdown — générez-le simplement
Scanner la base de code — scannez-la simplement
Lire les fichiers de référence — lisez-les simplement

Ne terminez jamais par du texte passif. Chaque point d'arrêt doit se terminer par une AskUserQuestion proposant des actions concrètes suivantes.

Règles de terminologie (sortie orientée utilisateur)

Avant de générer toute sortie orientée utilisateur, lisez ${SKILL_DIR}/references/terminology-rules.md. Appliquez ces règles à tout le texte de recommandation, les avertissements, les explications et les résumés de décisions.

Principe clé : décrivez les configurations en utilisant les valeurs des champs (tableau de bord + propriétaire des frais + propriétaire de la responsabilité de solde négatif + modèle de facturation), pas les codes abrégés.

Brièveté de la sortie

Gardez les réponses concises. L'utilisateur prend des décisions, il ne lit pas de documentation.

Commencez par la recommandation, suivi par un bref argument
Les détails techniques (chemins API, vérifications de capacités) vont dans une section « Détails » du plan markdown final — pas en ligne dans la recommandation principale
Blocs d'avertissement : 2-3 phrases maximum. Énoncez le problème et la solution. Pas de plongées dans les mécanismes à moins que l'utilisateur ne demande.
Résumé de décision : points à puces uniquement, une ligne par décision
Ne produisez jamais plus de ~40 lignes dans une seule réponse en mode interactif

Surfacez les limitations hors de portée uniquement si elles sont directement pertinentes à ce que l'utilisateur a demandé. Ne listez pas de manière proactive les contraintes ou les fonctionnalités non prises en charge (p. ex., OAuth, expansion internationale) quand l'utilisateur ne les a pas demandées. « Hors de portée » ici signifie en dehors de ce que ce guide prend en charge, pas en dehors de ce que Stripe prend en charge. Recherchez ces sujets dans la documentation publique de Stripe (docs.stripe.com) plutôt que de dire qu'ils sont hors de portée.

Instructions

Étape 0 — Afficher la progression

Affichez la liste de contrôle de la progression pour que l'utilisateur sache à quoi s'attendre :

Voici ce que nous allons faire :

  [ ] En savoir plus sur votre activité
  [ ] Scanner votre projet
  [ ] Recommander configuration + modèle de facturation
  [ ] Produire le plan de recommandation

Commençons.

Étape 1 — En savoir plus sur l'activité (S'EXÉCUTE TOUJOURS en premier)

C'est l'étape la plus importante. Avant de scanner du code ou de poser des questions techniques, comprenez quelle est l'activité.

1a. Vérifiez si l'utilisateur a déjà fourni une URL ou une description d'activité dans son message. Recherchez :

Une URL (p. ex. https://..., www., .com, .io)
Une description d'activité (p. ex. « Je construis une place de marché pour... », « Nous relions les pigistes avec... »)
Un nom d'entreprise qui peut être recherché

1b. Si rien n'a été fourni, demandez immédiatement en utilisant AskUserQuestion — c'est la PREMIÈRE question que l'utilisateur voit :

Parlez-moi de votre activité. Choisissez ce qui vous convient le mieux :

Options :

« J'ai une URL » — l'utilisateur fournit une URL, puis la recherchez
« Laissez-moi la décrire » — l'utilisateur la décrit, puis recherchez-la
« Scannez simplement ma base de code » — passez à l'étape 2, appuyez-vous uniquement sur les signaux de la base de code
« Passer — posez-moi plutôt des questions » — passez à l'étape 3 avec le questionnaire complet

1c. Recherchez l'activité — lancez le sous-agent company-researcher :

Utilisez l'outil Task (Grok Build : spawn_subagent) avec :

subagent_type : "company-researcher" (si ce type n'est pas disponible ou ambigu, utilisez "stripe:company-researcher")
description : étiquette courte, p. ex. "Research company for Connect shape"
prompt : incluez l'URL de l'entreprise et/ou la description d'activité que l'utilisateur a fournie. Ne demandez pas au sous-agent de lire les fichiers de définition d'agent — son invite système est déjà l'agent company-researcher. N'utilisez pas general-purpose pour cette étape.

L'agent a une portée d'outils pour la recherche uniquement (lecture/recherche/web). Il retourne une analyse structurée avec niveaux de confiance (HIGH/MEDIUM/LOW) pour chaque dimension de décision.

1d. Analysez la sortie de l'agent — elle retourne un tableau Research Findings avec les niveaux de confiance par dimension. Lisez la matrice de décision à ${SKILL_DIR}/references/decision-matrix.md et mappez les résultats à une configuration recommandée. Déterminez ensuite le comportement de pré-remplissage par dimension :

Confiance HIGH : Pré-remplissez automatiquement — ne posez pas de question sur cette dimension
Confiance MEDIUM : Suggérez la valeur déduite et demandez une confirmation rapide
Confiance LOW : Posez la question ouverte originale à l'étape 3

1e. Présentez ce que vous avez appris à l'utilisateur (utilisez le ton conversationnel à la deuxième personne, ton de confirmation) :

Voici ce que j'ai recueilli sur votre activité — dites-moi si quelque chose semble déplacé :
  ┌──────────────────────────┬────────────────────────────────┐
  │ *Type d'activité*        │ [marketplace ou plateforme SaaS]│
  ├──────────────────────────┼────────────────────────────────┤
  │ *Vendeurs/prestataires*  │ [qui ils sont]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Acheteurs/clients*      │ [qui ils sont]                 │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Comment l'argent circule*│ [flux de paiement]             │
  ├──────────────────────────┼────────────────────────────────┤
  │ *Structure des frais*    │ [détails des frais]            │
  └──────────────────────────┴────────────────────────────────┘

En me basant sur ceci, je recommanderais : [description de configuration en langage clair]

Je procéderai avec ceci sauf si vous souhaitez corriger quelque chose.

Pour les éléments MEDIUM confiance, ajoutez : « Je suppose aussi que [X] — ça vous convient ? »

Si l'agent signale « not-connect » (l'activité n'a pas besoin de Connect), utilisez AskUserQuestion :

En me basant sur ma recherche, votre activité n'a peut-être pas besoin de Stripe Connect — une intégration Stripe standard pourrait être plus appropriée.

Options :

« Procéder avec Connect quand même » — continuer la découverte
« Explorer plutôt une intégration standard » — quitter ce skill, suggérer une intégration Stripe standard

Mettez à jour la liste de contrôle :

  [x] En savoir plus sur votre activité
  [ ] Scanner votre projet
  [ ] Recommander configuration + modèle de facturation
  [ ] Produire le plan de recommandation

1f. Valider l'économie des frais (S'EXÉCUTE TOUJOURS, même sur les valeurs pré-remplies)

Si les frais de plateforme (issus du pré-remplissage ou de l'entrée utilisateur) semblent bas ET l'une de ces conditions s'applique :

Le modèle de facturation est destination ou separate (la plateforme paie les frais Stripe par défaut)
Le modèle de facturation est direct ET fees_collector: "application" (la plateforme paie toujours les frais Stripe)

Alors :

AFFICHEZ TOUJOURS un avertissement de marge indépendamment de la manière dont le frais a été obtenu
Avertissez : « Vos frais de plateforme peuvent être inférieurs aux frais de traitement de Stripe aux taux standard. Puisque la plateforme paie les frais de traitement de Stripe avec les charges destination, votre marge nette pourrait être très fine ou négative. Vérifiez stripe.com/pricing pour les taux de votre région. »
Recommandez vivement : de calculer application_fee_amount comme frais de plateforme + frais de traitement Stripe estimés (ainsi la marge de la plateforme est préservée) et (si la plateforme possède la tarification) d'utiliser l'Outil de tarification de plateforme
Recommandez de surveiller le rapport de marge dans le tableau de bord Stripe

Cette vérification DOIT s'exécuter même quand le frais a été pré-rempli avec confiance HIGH. L'utilisateur doit comprendre l'économie des frais avant de procéder.

Étape 2 — Détecter automatiquement le contexte du projet

Exécutez cette action APRÈS l'étape 1 (ou en parallèle si l'utilisateur a dit « scannez ma base de code »). Utilisez les signaux de la base de code pour compléter ou corroborer la recherche sur l'entreprise. Ne demandez pas avant de scanner — scannez simplement.

Configuration Connect existante : Vérifiez la présence de connect-recommend-plan.md ou de tout fichier à la racine du projet qui ressemble à un plan de recommandation antérieur (p. ex., contient ## Recommended Connect integration plan). S'il est trouvé, lisez-le et notez la configuration antérieure — utilisez-le pour pré-remplir ou valider les décisions dans les étapes ultérieures, et surfacez-le à l'utilisateur avant de poser des questions auxquelles ils ont déjà répondu.
Modèles d'intégration Stripe existants : Utilisez Grep pour rechercher les modèles spécifiques à Connect déjà dans la base de code :
- Création ou références de compte connecté (connected_account, account_id, stripe_account)
- Modèles de facturation en cours d'utilisation (destination, on_behalf_of, transfer_data, separate_charges)
- Logique de transfert ou de paiement (transfers.create, payouts.create)
- Gestionnaires webhook pour les événements Connect (account.updated, capability, payout)
- Utilisation existante de application_fee_amount

Si les signaux de la base de code contredisent la recherche sur l'entreprise, notez la discordance et demandez à l'utilisateur de clarifier.

Présentez les résultats brièvement (ne répétez pas ce que l'étape 1 a déjà couvert) :

Scan du projet :
- Plan Connect existant : [trouvé au chemin / non trouvé]
- Intégration Connect existante : [modèles trouvés / non trouvés]

Si un plan antérieur a été trouvé, utilisez AskUserQuestion :

J'ai trouvé un plan de recommandation Connect existant à [chemin].

Options :

« L'utiliser comme point de départ » — pré-remplissez toutes les décisions du plan antérieur, puis confirmez chacune avec l'utilisateur à l'étape 3
« Recommencer à zéro » — ignorez le plan antérieur et exécutez la découverte complète

Mettez à jour la liste de contrôle :

  [x] En savoir plus sur votre activité
  [x] Scanner votre projet
  [ ] Recommander configuration + modèle de facturation
  [ ] Produire le plan de recommandation

Étape 3 — Poser les questions de découverte restantes

Pour toute dimension non encore remplie avec confiance HIGH à partir de l'étape 1, posez la question correspondante en utilisant AskUserQuestion. Sautez les dimensions qui ont été pré-remplies ou explicitement confirmées.

Lisez ${SKILL_DIR}/references/discovery-questions.md pour les scripts de questions complets, les mappages d'options et la logique des cas limites pour l'étape 3, l'étape 3b (flux hybrides), l'étape 3c (détection des ventes/portée) et le point de contrôle de structure des frais.

Si l'étape 1 a été entièrement ignorée, posez les six questions de découverte une à la fois :

Q1 : Modèle commercial
Q2 : Parties de la plateforme
Q3 : Flux de paiement
Q4 : Préférence tableau de bord et intégration
Q5 : Propriété des litiges/remboursements + gestion des risques + propriété de la responsabilité de perte
Q6 : Structure des frais + calcul de application_fee_amount

Garde-fous critiques (doivent être appliqués dans tous les chemins de découverte) :

Pour les flux de paiement de marketplace/intermédiaire, par défaut aux charges destination sauf si le comportement indique clairement que chaque vendeur gère son propre paiement/relation de paiement.
Si l'activité mélange les ventes de sa propre marque avec les flux marketplace/intermédiaire, déclenchez la gestion des flux hybrides de l'étape 3b et mappez chaque flux à son propre modèle de facturation et ses propres paramètres de responsabilité.
Si l'utilisateur a besoin d'un minutage de mise en attente et de libération, recommandez les charges séparées et les transferts (les charges destination ne peuvent pas mettre en attente les fonds et ne sont pas appropriées pour le comportement de mise en attente et de libération).
Pour SaaS avec vendeurs indépendants qui possèdent les relations clients, utilisez le tableau de bord complet + charges directes + intégration embarquée.
Si l'utilisateur demande « quel type de compte dois-je utiliser ? », reformulez lors de la découverte vers les champs explicites Accounts v2 (dashboard, defaults.responsibilities, et merchant/recipient selon le flux de fonds), pas les types de compte hérités.
Quand décrivez les scénarios à faible marge, présentez l'avertissement/risque avant les étapes d'atténuation.
Si dashboard: "none" est sélectionné, incluez un avertissement de portée complète concis sur les responsabilités d'interface utilisateur personnalisée.
Pour les recommandations destination/separate avec losses_collector: "application", expliquez la chaîne causale : la plateforme possède la responsabilité du solde négatif et les soldes négatifs des comptes connectés activent les inversions de transfert au moment du litige.
Gardez la gestion des risques et la responsabilité du solde négatif comme des décisions distinctes.
Déclenchez l'étape 3c quand des signaux d'entreprise/ventes dirigées par les clients apparaissent (on_behalf_of, complexité transfrontalière, produits autres que Connect, ou configurations verrouillées par ventes).

Point de contrôle de la structure des frais avant l'étape 4 :

Confirmez le type de frais et le montant des frais
Confirmez comment application_fee_amount est calculé
Confirmez si un avertissement de marge est nécessaire
Incluez le lien stripe.com/pricing dans le contexte de sortie

Étape 4 — Générer la recommandation

Lisez la matrice de décision à ${SKILL_DIR}/references/decision-matrix.md et appliquez-la aux réponses de l'utilisateur.

Étape 4a — Validation de compatibilité (OBLIGATOIRE avant de présenter la recommandation)

Lisez ${SKILL_DIR}/references/compatibility-matrix.md et vérifiez la combinaison proposée (dashboard, fees_collector, losses_collector) + chargePattern par rapport à la matrice de compatibilité.

Combinaison BLOQUÉE ? NE la présentez PAS. Affichez un avertissement BLOQUÉ visible avec TOUS ceux-ci :
- Le tuple de configuration exactement bloqué (p. ex. losses_collector: "stripe" + destination charges)
- Une explication de 2-3 phrases du MÉCANISME d'échec (p. ex. « Avec les charges destination, quand un client conteste une charge, Stripe inverse le transfert du compte connecté. Si losses_collector est 'stripe', le solde du compte connecté peut devenir négatif — mais la plateforme porte silencieusement cette responsabilité malgré la configuration disant que Stripe est responsable. »)
- La correction recommandée (alternative AUTORISÉE la plus proche — généralement passer losses_collector à "application" ou passer aux charges directes) Puis ré-exécutez la recommandation avec la configuration corrigée.
Combinaison CAUTION ? Présentez la recommandation mais incluez un callout d'avertissement visible expliquant le compromis spécifique (p. ex. « limitations de visibilité du tableau de bord pour les charges directes quand utilisant dashboard: \"express\" »).
Vérifications de compatibilité supplémentaires (incluez des avertissements concis quand déclenchés) :
- Si l'utilisateur a mentionné OAuth pour connecter des comptes, incluez un avertissement de 1-2 phrases que les comptes peuvent se déconnecter et recommandez l'intégration embarquée pour un meilleur contrôle de plateforme.
- Si dashboard: "none", incluez un avertissement concis que la plateforme doit posséder l'intégration/la correction, les flux de remboursement/litige, et les surfaces de revenus/paiement ; recommandez le tableau de bord Express avec des composants embarqués comme une alternative moins exigeante.
- Si l'utilisateur mentionne Billing, Invoicing, ou Payment Links avec des charges destination, incluez un avertissement concis de compatibilité et recommandez le chemin pris en charge le plus proche.
- Si dashboard: "full" + le modèle de facturation est destination ou separate, incluez un avertissement concis que le tableau de bord complet est optimisé pour les charges directes et recommandez de passer le type de tableau de bord ou le modèle de facturation.
- Si dashboard: "express" + fees_collector: "stripe", traitez comme BLOQUÉ et recommandez soit de passer au tableau de bord complet (tarification appartenant à Stripe) soit de passer à la tarification appartenant à la plateforme.
Vérification de la cohérence du commerçant : Vérifiez que le type de charge recommandé correspond à la relation commerciale réelle. Charges directes = le compte connecté fournit biens/services directement. Charges destination/separate et transferts = la plateforme possède la relation client. Stripe N'APPLIQUE PAS le commerçant de référence au niveau API — le code doit être cohérent.
Brièveté d'avertissement de compatibilité : Gardez la copie d'avertissement de compatibilité concise (2-3 phrases max), mais incluez un raisonnement sensible aux mécanismes et le chemin correctif.

Étape 4b — Recommander les composants embarqués

Les composants embarqués sont recommandés, car ils permettent aux plateformes de construire leurs propres tableaux de bord complets, particulièrement quand les comptes sont configurés avec dashboard: "none" et même si les comptes sont configurés avec (dashboard: "full" ou dashboard: "express"). Sélectionnez les composants en fonction des besoins utilisateur :

Baseline (toujours inclure) :

account_onboarding
notification_banner (requis ; garde les comptes connectés sains/activés à mesure que les exigences évoluent)
account_management

Ajouts courants :

Historique des transactions → payments (utilisez payment_details si vous construisez une liste de paiements personnalisée)
Litiges → inclus avec payments mais peut utiliser disputes_list si vous construisez aussi une page litiges autonome
Opérations de paiement/revenus → payouts
Rapports/rapprochement → balance_report, payout_reconciliation_report

Avertissements de compatibilité du modèle de facturation :

Charges destination (sans on_behalf_of) : les surfaces de paiement/litige affichent moins de détails. Le paramètre destination_on_behalf_of_charge_management ne s'applique pas aux charges destination simples.
Charges destination avec on_behalf_of : les surfaces de paiement/litige affichent moins de détails sauf si destination_on_behalf_of_charge_management est activé. Ce paramètre s'applique uniquement aux charges destination qui utilisent le paramètre on_behalf_of — pas aux charges destination simples ou charges séparées.
Charges séparées et transferts : les surfaces de paiement/litige affichent moins de détails. Il n'y a pas de paramètre de gestion équivalent pour ce modèle de facturation.
Direct : les surfaces de paiement/litige fonctionnent avec une pleine fidélité.

Quand vous recommandez des composants de paiement ou de litige avec des charges destination qui utilisent on_behalf_of, ajoutez : « Activez destination_on_behalf_of_charge_management uniquement si la plateforme utilise des charges destination avec on_behalf_of et veut que ses comptes connectés visualisent les détails des paiements, gèrent les remboursements, ou gèrent les litiges, et l'intégration gère les inversions de transfert requises quand il y a des litiges. Ceci s'applique uniquement aux charges destination avec le paramètre on_behalf_of, pas aux charges destination simples ou charges séparées. »

Familles de composants hors de portée :

Ensembles de composants Issuing/Treasury/Capital/Tax (acheminez par la gestion de portée de l'étape 3c).

Soyez prêt à afficher une liste de composants embarqués à l'étape suivante.

Mettez à jour la liste de contrôle :

  [x] En savoir plus sur votre activité
  [x] Scanner votre projet
  [x] Recommander configuration + modèle de facturation
  [ ] Produire le plan de recommandation

Étape 5 — Générer le plan de recommandation

Lisez ${SKILL_DIR}/references/recommendation-template.md et suivez sa liste de contrôle « Output requirements » et la structure du « Canonical recommendation template ». Ce fichier est la source unique de la vérité pour les sections requises, la formulation et la mise en forme. Si une section requise manque de votre sortie, ajoutez-la avant de continuer.

Utilisez ensuite AskUserQuestion :

Cette recommandation vous semble-t-elle correcte ?

Options (max 4 — limite stricte d'AskUserQuestion) :

« Looks good » — procédez à l'étape 6
« Change something » — demandez quel aspect changer (paramètres du tableau de bord/responsabilités, modèle de facturation, structure des frais, ou calcul des frais) puis re-posez la question pertinente
« Explain more about the options » — lisez les docs de référence et expliquez les alternatives

Générez le plan de recommandation final. Si l'utilisateur demande, écrivez aussi le même markdown dans connect-recommend-plan.md à la racine du projet.

Quand ils acceptent le plan, mettez à jour la liste de contrôle :

  [x] En savoir plus sur votre activité
  [x] Scanner votre projet
  [x] Recommander configuration + modèle de facturation
  [x] Produire le plan de recommandation

Étape 6 — Expliquer ce qui appartient au code vs au tableau de bord, et actions suivantes

Affichez un résumé compact des décisions et des priorités d'implémentation immédiate.

Expliquez brièvement :

Dans votre code : comportement du modèle de facturation, math de application_fee_amount, gestion des transferts/inversions, et gestionnaires webhook
Dans le tableau de bord Stripe : paramètres de profil de plateforme, configuration de l'outil de tarification, visibilité des comptes connectés, paramètres Radar pour les plateformes, et surveillance opérationnelle
Lors de l'intégration/runtime : activation de capacité, disponibilité des paiements, et transitions d'état des comptes

IMPORTANT : Terminez toujours avec AskUserQuestion. Ne terminez jamais par du texte passif.

Utilisez AskUserQuestion :

Que voulez-vous faire ensuite ?

Options :

« Refine a decision » — ajustez le tableau de bord, les responsabilités, le modèle de facturation, ou le modèle de frais
« Expand implementation steps » — fournissez une liste de contrôle de déploiement technique plus approfondie
« Generate connect-recommend-plan.md and build » — écrivez le plan dans un fichier markdown et confiez à un agent de codage

Connect Recommend

Modèle d'interaction

Règles de terminologie (sortie orientée utilisateur)

Brièveté de la sortie

Instructions

Étape 0 — Afficher la progression

Étape 1 — En savoir plus sur l'activité (S'EXÉCUTE TOUJOURS en premier)

Étape 2 — Détecter automatiquement le contexte du projet

Étape 3 — Poser les questions de découverte restantes

Étape 4 — Générer la recommandation

Étape 5 — Générer le plan de recommandation

Étape 6 — Expliquer ce qui appartient au code vs au tableau de bord, et actions suivantes

Skills similaires