Ce simple fichier apprend à Claude, Codex et Copilot comment ajouter correctement des paiements dans un jeu

Un fournisseur de paiement vient de commencer à écrire ses instructions pour les agents avant de les écrire pour les développeurs. Avec Xsolla AI Toolkit, Claude Code, Codex, Cursor ou GitHub Copilot ne reçoivent plus seulement un lien vers une documentation API. Ils trouvent des fichiers SKILL.md qui leur indiquent dans quel ordre configurer le marchand, le catalogue, la connexion des joueurs, le paiement et les webhooks.

La promesse est séduisante : demander à l’agent « ajoute une boutique de skins à mon jeu » et le voir suivre le parcours recommandé par l’entreprise qui a conçu les API. Mais le dépôt public révèle aussi une limite essentielle. Plusieurs modules sont encore marqués comme brouillons et certaines consignes ne correspondent déjà plus exactement à la documentation en ligne. Le SKILL.md ne remplace donc pas la documentation. Il devient une couche procédurale entre elle et l’IA.

Xsolla AI Toolkit est disponible, mais tout n’est pas « terminé »

Le site officiel de Xsolla AI Toolkit annonce une intégration avec Claude Code, Codex et Gemini CLI en moins de deux minutes. Il présente également le kit comme compatible avec les principaux outils de développement assisté par IA et affirme pouvoir conduire d’un premier prompt à une boutique web fonctionnelle au cours d’une seule session assistée.

Cette dernière formule doit être lue comme une ambition commerciale, pas comme un résultat garanti. Le dépôt GitHub officiel de Xsolla contient bien les parcours nécessaires, mais son état est plus nuancé que la page de présentation. Il réunit actuellement huit dossiers de skills :

• shop-setup, qui orchestre le parcours complet ;
• merchant-setup, pour le compte, le projet et les clés API ;
• catalog-design, pour les skins, monnaies virtuelles, packs et prix ;
• login-setup et login-styling, pour l’identité et l’interface de connexion ;
• headless-checkout-integration, pour une interface de paiement personnalisée ;
• webhooks-impl, pour confirmer, attribuer ou retirer un achat ;
• production, pour passer du sandbox aux transactions réelles.

Le catalogue du dépôt affiche certains domaines comme terminés et d’autres comme brouillons. En ouvrant les fichiers eux-mêmes, catalog-design, login-setup, headless-checkout-integration et webhooks-impl portent encore un statut draft dans leurs métadonnées ou leur contenu. Le kit est donc utilisable pour expérimenter et encadrer une intégration, mais il serait imprudent d’interpréter sa présence comme une certification automatique de chaque ligne générée.

Un fichier SKILL.md, c’est quoi exactement ?

Un skill est un dossier dont le point d’entrée est un fichier nommé SKILL.md. Son en-tête indique son nom, sa description et les situations dans lesquelles l’agent doit l’activer. Le reste contient une méthode : étapes, commandes, critères de réussite, erreurs fréquentes et références à charger uniquement lorsque la tâche l’exige.

Cette organisation suit le principe de divulgation progressive décrit par la spécification Agent Skills. L’agent voit d’abord une courte description. Il ne charge le corps du skill que si la demande correspond, puis ouvre les références ou exécute les scripts nécessaires. Une énorme documentation n’occupe ainsi pas toute sa fenêtre de contexte dès le départ.

Ce mécanisme ne doit pas être confondu avec un fichier AGENTS.md qui fixe les règles communes d’un dépôt pour Codex, Claude, Cursor ou Gemini. AGENTS.md dit par exemple où se trouve le code métier, quelles commandes de test lancer et ce qu’il est interdit de modifier. Un SKILL.md explique comment réussir une tâche précise, comme vérifier la signature d’un webhook de paiement.

Ce que le kit apprend réellement à Claude, Codex et Copilot

La valeur du toolkit apparaît dans les détails que les modèles oublient souvent. Le skill marchand distingue la clé liée à un projet de la clé liée au marchand, impose de conserver les secrets dans un fichier d’environnement et rappelle que le compte doit être créé manuellement. Il explique aussi que le sandbox peut fonctionner avant la signature du contrat, alors que les paiements réels exigent les formalités de mise en production.

Le skill de catalogue demande de séparer les appels d’administration, réservés à la configuration, des appels Catalog utilisés par la boutique. Il précise que certaines mises à jour remplacent l’objet complet au lieu de fusionner quelques champs et qu’une liste de devises incohérente peut produire des prix absents. Ce sont exactement les erreurs qu’un agent peut commettre en assemblant des extraits de documentation sans comprendre le flux global.

Pour le paiement, le kit construit Headless Checkout par phases : carte bancaire, choix du moyen de paiement, redirections, portefeuilles, méthodes enregistrées, puis pays du paiement. Il interdit d’envoyer la clé API dans le navigateur et limite le client à un jeton de paiement de courte durée. Le parcours de webhook impose ensuite la vérification de signature, l’idempotence et la déduplication des transactions afin qu’une notification répétée ne donne pas deux fois le même skin.

Le kit combine même ses instructions avec le MCP de documentation Xsolla. C’est la même séparation que l’on retrouve lorsque Claude Code ou Cursor utilise Unity MCP pour lire et modifier une scène de jeu : le skill fournit la méthode, tandis que le MCP apporte une information ou une action disponible au moment de l’exécution.

Le détail qui prouve que les skills ne remplacent pas encore les docs

Le dépôt Xsolla demande à plusieurs endroits de vérifier le schéma courant avec un outil nommé search_xsolla_sources. La documentation Xsolla consacrée aux assistants IA expose actuellement un outil nommé search_xsolla_knowledge_sources. Le principe est identique, mais le nom ne l’est pas.

Ce petit décalage est plus instructif qu’une démonstration parfaite. Même un skill maintenu par l’éditeur peut vieillir, contredire son index ou pointer vers une commande renommée. En matière de paiement, l’agent doit donc vérifier les schémas et les noms d’outils en direct, signaler ce qu’il n’a pas pu confirmer et arrêter l’intégration lorsqu’un prérequis manque.

Il existe aussi un risque de chaîne d’approvisionnement. Un SKILL.md peut demander à l’agent de lire des fichiers, d’exécuter un script ou d’appeler un service externe. Les recommandations de sécurité d’Anthropic assimilent l’installation d’un skill à celle d’un logiciel : il faut lire son contenu, contrôler ses scripts et examiner ses accès réseau avant de lui confier un dépôt ou des secrets. Le fait qu’un fichier soit en Markdown ne le rend pas inoffensif.

Le test honnête : ajouter la même boutique de skins deux fois

Pour mesurer l’effet d’un skill, il faut éviter le scénario publicitaire où l’on montre uniquement le second essai réussi. Le protocole le plus propre part de deux copies identiques d’un mini-jeu. Les deux agents utilisent le même modèle, la même limite de temps, les mêmes autorisations et le même accès à la documentation Xsolla. Le second reçoit en plus le dépôt AI Toolkit.

Ajoute une boutique de trois skins à ce mini-jeu. Un joueur doit pouvoir se connecter, consulter le catalogue, acheter un skin en sandbox, recevoir le skin uniquement après confirmation serveur et le perdre après un remboursement. N’expose aucun secret dans le navigateur ou les journaux. Ajoute les tests nécessaires, documente les étapes manuelles et ne passe jamais en production.

Parcours A : documentation seule

L’agent peut consulter les pages Markdown, le fichier llms.txt et le serveur MCP de documentation. Il n’a accès ni au dossier skills, ni au fichier AGENTS.md de Xsolla. Le testeur note chaque mauvais endpoint, confusion d’authentification, secret placé au mauvais endroit et correction humaine.

Parcours B : documentation et skill officiel

La seconde copie reçoit le toolkit. L’agent doit détecter shop-setup, charger uniquement les domaines nécessaires et continuer à vérifier les schémas via les mêmes sources que le parcours A. Le skill ne doit pas lui donner davantage de permissions ; il change seulement la procédure et l’ordre des contrôles.

Les neuf mesures à relever

1. Temps jusqu’au premier paiement sandbox terminé, pas jusqu’à l’affichage du formulaire.
2. Nombre d’interventions humaines, y compris les questions auxquelles l’agent pouvait répondre seul.
3. Erreurs API : endpoint, méthode, corps, version ou champ incorrect.
4. Erreurs d’authentification : mauvaise clé, mauvais identifiant ou secret exposé au client.
5. Qualité du webhook : signature vérifiée sur le corps brut, réponse rapide et erreur explicite.
6. Idempotence : un webhook rejoué ne doit pas attribuer deux fois le skin.
7. Remboursement : l’objet doit être retiré une seule fois après l’événement correspondant.
8. Tests et traces : commandes reproductibles, absence de secret dans les journaux et statut réellement observé.
9. Coût total : tokens de l’agent, temps humain et éventuels abonnements, pas seulement le prix du toolkit.

Les cases doivent rester vides tant que l’essai n’a pas été exécuté. Xsolla publie des tests de référence dans certains skills, mais ils ne remplacent pas un benchmark indépendant sur le même jeu et avec les mêmes contraintes.

Installer Xsolla AI Toolkit dans Claude Code, Codex ou Cursor

Le dépôt fournit plusieurs parcours d’installation. Avant toute commande, il faut lire le dépôt, épingler si possible une révision connue et travailler sur une branche dédiée. Une mise à jour automatique peut modifier les instructions au milieu d’un projet.

Claude Code

claude plugin marketplace add xsolla/xsolla-ai-kit
claude plugin install xsolla-ai-kit@xsolla-ai-kit

Codex

codex plugin marketplace add xsolla/xsolla-ai-kit

Cursor

Xsolla recommande d’ajouter le dépôt comme dossier de l’espace de travail, puis de décrire la tâche en langage naturel. Cursor découvre les skills placés sous .cursor/skills/. Pour une boutique complète, la demande doit commencer par shop-setup.

Copilot et les autres agents

Lorsqu’un outil ne dispose pas du système de plugins utilisé par le dépôt, Xsolla propose de copier AGENTS.md et le dossier skills/ dans le projet. Il faut alors vérifier le chemin de skills réellement reconnu par la version de l’agent utilisée : la compatibilité générale du format ne garantit pas une installation identique partout.

Les identifiants attendus peuvent ensuite être déclarés côté serveur avec des noms explicites, sans jamais écrire leurs valeurs dans le dépôt :

XSOLLA_MERCHANT_ID=
XSOLLA_PROJECT_ID=
XSOLLA_PROJECT_API_KEY=

Le fichier qui contient les valeurs réelles doit être ignoré par Git. Le navigateur et le build du jeu ne doivent recevoir ni la clé API du projet, ni le secret OAuth, ni le secret de webhook.

Le parcours sûr pour une première boutique Xsolla assistée par IA

1. Auditer le kit avant installation. Lire les fichiers activés, leurs références et les scripts éventuels. Noter la révision Git testée.
2. Créer le compte manuellement. L’agent peut expliquer le parcours, mais l’adresse électronique, la double authentification, le contrat et les informations fiscales restent sous contrôle humain.
3. Rester dans le sandbox. Utiliser uniquement les moyens de paiement de test jusqu’à ce que tout le parcours soit vérifié.
4. Commencer par trois produits simples. Trois skins à prix fixe suffisent pour tester catalogue, commande, paiement et attribution.
5. Générer les jetons côté serveur. La clé API ne doit jamais être incluse dans le JavaScript, l’application mobile ou le jeu distribué.
6. Vérifier le webhook avant toute attribution. Contrôler la signature sur le corps brut, puis enregistrer l’identifiant de transaction avec une contrainte unique.
7. Tester le rejeu et le remboursement. Envoyer deux fois la même notification, puis réaliser un remboursement sandbox. L’état du joueur doit rester cohérent.
8. Faire une revue humaine avant la production. Contrôler le contrat, les prix, les taxes, les remboursements, la confidentialité et les procédures de support.

Un agent peut automatiser une grande partie du code, mais il ne devient pas pour autant le responsable légal du paiement. Il ne doit jamais accepter seul un contrat, choisir une politique de remboursement ou décider qu’un système est conforme parce qu’un test sandbox est passé.

Est-ce la fin des documentations API ?

Non. Une documentation décrit un produit dans sa largeur : endpoints, paramètres, erreurs, versions, SDK et cas particuliers. Un skill choisit un chemin parmi ces possibilités et transforme cette connaissance en procédure. Il est plus proche d’un playbook d’intégration maintenu par l’éditeur que d’une référence exhaustive.

Cette distinction explique pourquoi Xsolla conserve simultanément des pages Markdown pour les modèles, un index llms.txt, un serveur MCP de recherche et les nouveaux fichiers SKILL.md. Ces couches ne se remplacent pas ; elles réduisent chacune une friction différente.

Le signal de fond dépasse cependant Xsolla. Si les agents écrivent une part croissante des intégrations, Stripe, OVHcloud, Brevo, Shopify ou d’autres fournisseurs auront intérêt à publier leurs chemins recommandés sous une forme que Claude, Codex et Copilot savent activer. Ils devront surtout les versionner, les tester et annoncer clairement leur niveau de maturité.

Pour le développement de jeux, cette évolution complète celle des outils qui transforment déjà une description en prototype, comme Roblox Build et sa première version jouable générée depuis un téléphone. Une IA peut bientôt créer une scène, modifier le moteur, puis intégrer une boutique. La question n’est plus seulement de savoir si elle peut produire du code, mais si elle suit une procédure vérifiable lorsqu’elle touche à l’argent réel.

Le fichier SKILL.md devient donc un nouvel objet stratégique : lisible par l’humain, activable par plusieurs agents et maintenable par le fournisseur. Le test décisif ne sera pas la beauté de sa démonstration. Ce sera sa capacité à réduire les erreurs mesurées sans masquer ses brouillons, ses dépendances et les validations qui restent humaines.

Article vérifié à partir du dépôt et des documentations officielles disponibles le 8 août 2026. Le toolkit évolue rapidement ; contrôlez le statut des skills et les commandes d’installation avant de les utiliser.