breim/ax-kit

AX Kit

UX ist die Erfahrung eines Menschen. Agent Experience (AX) ist die Erfahrung eines KI-Agenten, der ein Produkt für eine Person nutzt. Ein Agent hat keine Augen, keine Geduld für ein CAPTCHA und keinen Menschen, den er fragen kann. Er kann nur das nutzen, was das Produkt einer Maschine preisgibt.

Dieses Skill verbessert die agentenorientierte Schicht einer Website, einer API, einer SaaS-App oder eines Shops. Es implementiert die Standards, die Agenten verwenden, und misst das Ergebnis mit einem Scanner. Der Score ist das Feedback für die Arbeit. Der Score ist nicht das Ziel.

Einrichtung

<skill-dir> ist das Verzeichnis, das diese SKILL.md enthält. Behalten Sie das Arbeitsverzeichnis im Projekt des Benutzers.

Der Scanner ist <skill-dir>/scripts/ax.mjs. Er benötigt Node.js 18 oder höher und hat keine Abhängigkeiten.

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

Wenn node fehlt oder älter als Version 18 ist, informieren Sie den Benutzer. Fahren Sie dann mit den Playbooks und ohne den Scanner fort.

Befehle

Finden Sie den Befehl in der Anfrage des Benutzers. Lesen Sie dann die Anleitung für diesen Befehl und befolgen Sie sie.

Befehl	Verwenden Sie ihn, wenn der Benutzer ...	Anleitung	Bearbeitet Code
improve	das Produkt mit einer Schleife aus Scannen, Reparieren und Verifizieren für Agenten verbessern möchte	references/improve.md	Ja
add <capability>	eine Fähigkeit implementieren möchte, z.B. llms-txt oder mcp-server	references/add.md	Ja
audit <url>	eine vollständige Diagnose und einen Bericht ohne Änderungen erhalten möchte	references/audit.md	Nein
score <url>	schnell den AX-Score und die größten Lücken erhalten möchte	references/score.md	Nein
design	eine geplante API, Website oder Funktion überprüfen möchte, bevor der Code existiert	references/design.md	Nein
ci	ein Pipeline-Gate für den Score und ein Badge hinzufügen möchte	references/ci.md	Ja

Wenn die Anfrage keinen Befehl nennt und Sie keinen ableiten können, zeigen Sie diese Tabelle und fragen Sie, welchen Befehl der Benutzer möchte. Beginnen Sie nicht mit der Arbeit aus dem Menü.

Regeln, die für alle Befehle gelten

Diese Regeln sind stärker als die Referenzdateien.

1. Bestätigung vor Änderungen. Holen Sie die Zustimmung des Benutzers zwei Mal ein. Stimmen Sie zuerst die zu schließenden Lücken ab. Lesen Sie dann die Playbooks und zeigen Sie die genauen Dateien, die Sie ändern werden. Bearbeiten Sie erst nach der zweiten Zustimmung.
2. Nur-Lese-Modus auf einer Live-Seite. Senden Sie nur Anfragen, die Daten lesen. Erstellen Sie kein Konto, senden Sie kein Formular ab und kaufen Sie nichts. Der Eigentümer der Seite kann in klaren Worten eine Ausnahme genehmigen. Der Scanner sendet ein POST: eine server/discover-Anfrage an /mcp. Diese Anfrage liest nur Daten.
3. Fragen Sie, bevor Sie einen externen Scanner verwenden. Ein gehosteter Scanner empfängt die URL. Holen Sie zuerst die Zustimmung ein.
4. Schützen Sie die Sicherheit. Deaktivieren Sie keinen Bot-Schutz, öffnen Sie CORS nicht für private Daten und legen Sie keine privaten Inhalte offen, um einen Score zu erhöhen. Jedes Playbook enthält Sicherheitshinweise. Befolgen Sie diese. Wenn eine menschliche Seite ein CAPTCHA hat, behalten Sie es. Fügen Sie einen separaten Pfad für Agenten hinzu, z. B. Schlüssel von einer API, mit Missbrauchskontrollen.
5. Respektieren Sie die Bot-Richtlinie des Eigentümers. Eine Sperre für KI-Training-Crawler ist eine gültige Entscheidung. Ändern Sie sie nicht, es sei denn, der Benutzer fragt danach.
6. Überprüfen Sie das Datum eines Standards. Jedes Playbook hat ein Überprüft-Datum. Wenn dieses Datum mehr als 6 Monate alt ist, lesen Sie die Primärquelle, bevor Sie implementieren.
7. Berichten Sie die Wahrheit. Zeigen Sie den Score, die Abdeckung und jede Prüfung, die der Scanner nicht bewertet hat. Zeigen Sie eine nicht bewertete Prüfung nicht als bestanden an.
8. Beheben Sie die Ursache. Fügen Sie keine Datei nur hinzu, um eine Prüfung zu bestehen. Eine llms.txt mit falschen Links ist schlimmer als keine Datei.

Die sieben Säulen

Die Säulen folgen der Reise eines Agenten. Ein Fehler in einer frühen Säule blockiert die darauf folgenden Säulen.

Säule	Frage	Playbooks
Erreichen	Kann ein Agent eine Antwort erhalten und ist die Bot-Richtlinie explizit?	bot-access
Entdecken	Kann ein Agent finden, was existiert?	llms-txt, sitemap-and-links, api-catalog, agent-discovery
Lesen	Kann ein Agent den Inhalt ohne Browser verstehen?	markdown-for-agents, server-rendering, structured-data
Handeln	Kann ein Agent das Produkt aufrufen?	openapi-quality, mcp-server, webmcp, api-design
Autorisieren	Kann ein Agent ohne menschliches Eingreifen Zugriff erhalten?	oauth-for-agents, self-serve-access
Erholen	Kann ein Agent sich nach einem Fehler korrigieren?	errors-and-limits
Transagieren	Kann ein Agent bezahlen?	agentic-commerce

Jedes Playbook ist die Datei references/<name>.md.

Profile

Ein Profil teilt dem Scanner mit, welche Prüfungen gelten. Geben Sie das Profil mit --profile an. Wenn Sie es weglassen, erkennt der Scanner es.

Profil	Ziel
content	Eine Marketing-Site, eine Dokumentations-Site oder ein Blog
api	Eine HTTP-API
webapp	Eine SaaS-Anwendung mit Konten
commerce	Ein Shop

Ein Produkt kann mehr als eine Oberfläche haben. Scannen Sie jede Oberfläche mit ihrem eigenen Profil. Beispiel: Scannen Sie example.com als content und api.example.com als api.

Für eine API geben Sie die URL an, die für die gesamte API antwortet. Wenn der Host-Root mit der API antwortet, verwenden Sie den Host-Root. Wenn die API sich unterhalb eines Pfads wie /api/v1 befindet und der Host-Root etwas anderes ausliefert, verwenden Sie diesen Pfad. Der Scanner sucht nach der API-Beschreibung an den bekannten Orten des Hosts und neben der von Ihnen angegebenen URL.

So lesen Sie die Scanner-Ausgabe

Der JSON-Bericht hat drei Buckets von Prüfungen.

Bucket	Inhalt	Auswirkung auf den Score
score	Gemessene Prüfungen anhand stabiler Standards	Der gesamte Score
review	Prüfungen, die ein Urteil erfordern, z.B. „ein Agent kann einen API-Schlüssel ohne CAPTCHA erhalten“	Keine. Sie bewerten sie.
watch	Neue Standards, Legacy-Pfade und Beobachtungen	Keine

• score ist eine verifizierte Untergrenze von 0 bis 100. upperBound ist der Score, wenn jede nicht bewertete Prüfung besteht.
• coverage zeigt, wie viel des Scores der Scanner bewerten konnte. Ein Timeout verringert ihn.
• grade ist null, wenn score und upperBound in verschiedenen Noten-Bändern liegen.
• cap wird gesetzt, wenn ein Gate fehlschlägt. Ein Gate schlägt fehl, wenn eine einfache Anfrage eine Bot-Herausforderung erhält oder wenn die Seite ohne JavaScript keinen Inhalt hat. Die Obergrenze ist 59.
• opportunities listet die Punkte auf, die jede Korrektur hinzufügen kann, die größten zuerst. Es enthält alle Lücken. Die Textausgabe zeigt nur die ersten 8.
• Jede Prüfung hat ein playbook. Dies ist die Referenzdatei mit der Korrektur.
• Eine Prüfung mit blockedBy ist fehlgeschlagen, weil eine andere Prüfung zuerst fehlgeschlagen ist. Ihr Status ist fail, nicht not_assessed, sodass sie die Abdeckung nicht verringert. Korrigieren Sie zuerst die Prüfung in blockedBy.
• review listet die Review-Prüfungen auf, die für das Profil gelten. Bewerten Sie nur diese.

Ohne --json gibt der Scanner einen kurzen Textbericht mit der Score-Zeile und der Säulen-Zeile aus. Verwenden Sie den Textbericht für den Benutzer und das JSON für Ihre Arbeit.

Exit-Codes: 0 OK, 1 Gate fehlgeschlagen, 2 Nutzungsfehler, 3 Gate nicht eindeutig, 4 kein Score, 5 interner Fehler.

node <skill-dir>/scripts/ax.mjs catalog --json gibt den Katalog aus. Jeder Eintrag seines checks-Arrays hat ein bucket. Ein Review-Check hat auch ein rubric mit den Mitgliedern pass, partial, fail und evidence.

Behalten Sie einen JSON-Bericht im Gespräch oder in einem temporären Verzeichnis außerhalb des Projekts. Schreiben Sie ihn nicht in das Projekt, es sei denn, der Benutzer fragt danach.

Für die Formel lesen Sie references/scoring.md. Für die Liste der Prüfungen lesen Sie references/checks.md.

Referenzdateien

Lesen Sie eine Datei nur, wenn die Bedingung zutrifft.

Datei	Lesen Sie sie, wenn
references/stacks.md	Sie herausfinden müssen, wo eine Datei, ein Header oder eine Route im Framework des Projekts platziert wird
references/standards.md	Sie wissen müssen, ob ein Standard stabil, neu oder Legacy ist oder ob ein Pfad seinen Namen geändert hat
references/checks.md	Sie die Bedeutung einer Prüfungs-ID oder das Rubrik eines Review-Checks benötigen
references/scoring.md	Der Benutzer fragt, wie der Score funktioniert
references/<playbook>.md	Sie die Fähigkeit dieses Playbooks implementieren oder erklären

Vorlagen für gängige Dateien befinden sich in <skill-dir>/assets/. Jedes Playbook nennt die Vorlage, die es verwendet.