breim/ax-kit

AX Kit

L'UX est l'expérience d'un humain. L'Agent Experience (AX) est l'expérience d'un agent d'IA qui utilise un produit pour une personne. Un agent n'a pas d'yeux, pas de patience pour un CAPTCHA, et aucun humain à qui demander. Il ne peut utiliser que ce que le produit expose à une machine.

Cette compétence améliore la couche orientée agent d'un site, d'une API, d'une application SaaS ou d'une boutique. Elle implémente les standards que les agents utilisent, et mesure le résultat avec un scanner. Le score est le retour sur le travail. Le score n'est pas le but.

Configuration

<skill-dir> est le répertoire qui contient ce SKILL.md. Gardez le répertoire de travail dans le projet de l'utilisateur.

Le scanner est <skill-dir>/scripts/ax.mjs. Il nécessite Node.js 18 ou ultérieur et n'a aucune dépendance.

node <skill-dir>/scripts/ax.mjs scan <url> --profile <content|api|webapp|commerce> --json

Si node est manquant ou plus ancien que la version 18, informez l'utilisateur. Continuez ensuite avec les playbooks et sans le scanner.

Commandes

Trouvez la commande dans la demande de l'utilisateur. Lisez ensuite le guide pour cette commande et suivez-le.

Commande	Utilisez-la lorsque l'utilisateur souhaite	Guide	Modifie le code
improve	Rendre le produit meilleur pour les agents, avec une boucle de scan, correction et vérification	references/improve.md	Oui
add <capability>	Implémenter une capacité, par exemple llms-txt ou mcp-server	references/add.md	Oui
audit <url>	Obtenir un diagnostic complet et un rapport, sans modifications	references/audit.md	Non
score <url>	Obtenir rapidement le score AX et les principaux écarts	references/score.md	Non
design	Examiner une API, un site ou une fonctionnalité planifié avant l'existence du code	references/design.md	Non
ci	Ajouter une porte pipeline sur le score, et un badge	references/ci.md	Oui

Si la demande ne nomme aucune commande et que vous ne pouvez pas en déduire une, affichez ce tableau et demandez quelle commande l'utilisateur souhaite. Ne commencez pas le travail à partir du menu.

Règles applicables à toutes les commandes

Ces règles sont plus fortes que les fichiers de référence.

1. Confirmez avant de modifier. Obtenez l'accord de l'utilisateur deux fois. D'abord, accordez-vous sur les écarts à combler. Ensuite, lisez les playbooks et montrez les fichiers exacts que vous allez modifier. Ne modifiez qu'après le deuxième accord.
2. Restez en lecture seule sur un site en direct. Envoyez uniquement des requêtes qui lisent des données. Ne créez pas de compte, ne soumettez pas de formulaire et n'achetez rien. Le propriétaire du site peut approuver une exception en termes clairs. Le scanner envoie un POST : une requête server/discover vers /mcp. Cette requête lit uniquement les données.
3. Demandez avant d'utiliser un scanner externe. Un scanner hébergé reçoit l'URL. Obtenez d'abord le consentement.
4. Protégez la sécurité. Ne désactivez pas la protection anti-bot, n'ouvrez pas CORS pour les données privées et n'exposez pas de contenu privé pour augmenter un score. Chaque playbook contient des notes de sécurité. Obéissez-y. Si une page humaine a un CAPTCHA, conservez-le. Ajoutez un chemin séparé pour les agents, par exemple des clés depuis une API, avec des contrôles d'abus.
5. Respectez la politique de bot du propriétaire. Un blocage des robots de formation IA est une décision valide. Ne le modifiez pas, sauf si l'utilisateur le demande.
6. Vérifiez la date d'un standard. Chaque playbook a une date Révisé. Si cette date a plus de 6 mois, lisez la source principale avant d'implémenter.
7. Rapportez la vérité. Affichez le score, la couverture et chaque vérification que le scanner n'a pas évaluée. Ne présentez pas une vérification non évaluée comme réussie.
8. Corrigez la cause. N'ajoutez pas un fichier uniquement pour satisfaire une vérification. Un llms.txt avec des liens erronés est pire que l'absence de fichier.

Les sept piliers

Les piliers suivent le parcours d'un agent. Un échec dans un pilier précoce bloque les piliers après lui.

Pilier	Question	Playbooks
Atteindre	Un agent peut-il obtenir une réponse, et la politique de bot est-elle explicite ?	bot-access
Découvrir	Un agent peut-il trouver ce qui existe ?	llms-txt, sitemap-and-links, api-catalog, agent-discovery
Lire	Un agent peut-il comprendre le contenu sans navigateur ?	markdown-for-agents, server-rendering, structured-data
Agir	Un agent peut-il appeler le produit ?	openapi-quality, mcp-server, webmcp, api-design
Autoriser	Un agent peut-il obtenir un accès sans humain présent ?	oauth-for-agents, self-serve-access
Récupérer	Un agent peut-il se corriger après une erreur ?	errors-and-limits
Transaction	Un agent peut-il payer ?	agentic-commerce

Chaque playbook est le fichier references/<nom>.md.

Profils

Un profil indique au scanner quelles vérifications s'appliquent. Donnez le profil avec --profile. Si vous l'omettez, le scanner le détecte.

Profil	Cible
content	Un site marketing, un site de documentation ou un blog
api	Une API HTTP
webapp	Une application SaaS avec comptes
commerce	Une boutique

Un produit peut avoir plus d'une surface. Scannez chaque surface avec son propre profil. Exemple : scannez example.com en tant que content et scannez api.example.com en tant que api.

Pour une API, donnez l'URL qui répond pour l'ensemble de l'API. Si la racine de l'hôte répond avec l'API, utilisez la racine de l'hôte. Si l'API est en dessous d'un chemin tel que /api/v1, et que la racine de l'hôte sert autre chose, utilisez ce chemin. Le scanner recherche la description de l'API aux emplacements connus de l'hôte et à côté de l'URL que vous donnez.

Comment lire la sortie du scanner

Le rapport JSON a trois compartiments de vérifications.

Compartiment	Contenu	Effet sur le score
score	Vérifications mesurées sur des standards stables	La totalité du score
review	Vérifications nécessitant un jugement, par exemple "un agent peut obtenir une clé API sans CAPTCHA"	Aucun. Vous les évaluez.
watch	Standards émergents, chemins hérités et observations	Aucun

• score est une borne inférieure vérifiée de 0 à 100. upperBound est le score si chaque vérification non évaluée réussit.
• coverage montre quelle partie du score le scanner a pu évaluer. Un délai d'attente le diminue.
• grade est null lorsque score et upperBound se trouvent dans des bandes de notes différentes.
• cap est défini lorsqu'une porte échoue. Une porte échoue lorsqu'une requête simple reçoit un défi de bot, ou lorsque la page n'a pas de contenu sans JavaScript. Le plafond est 59.
• opportunities liste les points que chaque correction peut ajouter, du plus grand au plus petit. Il contient tous les écarts. La sortie texte affiche uniquement les 8 premiers.
• Chaque vérification a un playbook. C'est le fichier de référence avec la correction.
• Une vérification avec blockedBy a échoué car une autre vérification a échoué en premier. Son statut est fail, pas not_assessed, donc elle ne diminue pas la couverture. Corrigez d'abord la vérification dans blockedBy.
• review liste les vérifications de révision qui s'appliquent au profil. Évaluez uniquement celles-ci.

Sans --json, le scanner imprime un rapport texte court avec la ligne de score et la ligne de pilier. Utilisez le rapport texte pour l'utilisateur et le JSON pour votre travail.

Codes de sortie : 0 ok, 1 porte échouée, 2 erreur d'utilisation, 3 porte non concluante, 4 pas de score, 5 erreur interne.

node <skill-dir>/scripts/ax.mjs catalog --json imprime le catalogue. Chaque entrée de son tableau checks a un bucket. Une vérification de révision a également une rubric avec les membres pass, partial, fail et evidence.

Conservez un rapport JSON dans la conversation, ou dans un répertoire temporaire en dehors du projet. Ne l'écrivez pas dans le projet sauf si l'utilisateur le demande.

Pour la formule, lisez references/scoring.md. Pour la liste des vérifications, lisez references/checks.md.

Fichiers de référence

Lisez un fichier uniquement lorsque la condition est vraie.

Fichier	Lisez-le lorsque
references/stacks.md	Vous devez trouver où va un fichier, un en-tête ou une route dans le framework du projet
references/standards.md	Vous devez savoir si un standard est stable, émergent ou hérité, ou si un chemin a changé de nom
references/checks.md	Vous avez besoin de la signification d'un ID de vérification, ou de la rubrique d'une vérification de révision
references/scoring.md	L'utilisateur demande comment fonctionne le score
references/<playbook>.md	Vous implémentez ou expliquez la capacité de ce playbook

Les modèles pour les fichiers courants se trouvent dans <skill-dir>/assets/. Chaque playbook nomme le modèle qu'il utilise.