breim/ax-kit

AX Kit

UX é a experiência de um humano. Experiência do Agente (AX) é a experiência de um agente de IA que usa um produto para uma pessoa. Um agente não tem olhos, não tem paciência para um CAPTCHA e não tem um humano a quem perguntar. Ele só pode usar o que o produto expõe para uma máquina.

Esta skill melhora a camada voltada para agentes de um site, uma API, um aplicativo SaaS ou uma loja. Ela implementa os padrões que os agentes usam e mede o resultado com um scanner. A pontuação é o feedback para o trabalho. A pontuação não é o objetivo.

Configuração

<skill-dir> é o diretório que contém este SKILL.md. Mantenha o diretório de trabalho no projeto do usuário.

O scanner é <skill-dir>/scripts/ax.mjs. Ele precisa do Node.js 18 ou superior e não tem dependências.

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

Se node estiver ausente ou for mais antigo que a versão 18, avise o usuário. Em seguida, continue com os playbooks e sem o scanner.

Comandos

Encontre o comando na solicitação do usuário. Em seguida, leia o guia para aquele comando e siga-o.

Comando	Use quando o usuário quiser	Guia	Edita código
improve	Tornar o produto melhor para agentes, com um loop de escaneamento, correção e verificação	references/improve.md	Sim
add <capacidade>	Implementar uma capacidade, por exemplo llms-txt ou mcp-server	references/add.md	Sim
audit <url>	Obter um diagnóstico completo e um relatório, sem alterações	references/audit.md	Não
score <url>	Obter a Pontuação AX e as principais lacunas rapidamente	references/score.md	Não
design	Revisar uma API, site ou recurso planejado antes do código existir	references/design.md	Não
ci	Adicionar uma barreira de pipeline na pontuação e um selo	references/ci.md	Sim

Se a solicitação não nomear um comando e você não conseguir inferir um, mostre esta tabela e pergunte qual comando o usuário deseja. Não comece a trabalhar a partir do menu.

Regras que se aplicam a todos os comandos

Estas regras são mais fortes que os arquivos de referência.

1. Confirme antes de editar. Obtenha o acordo do usuário duas vezes. Primeiro, concorde com as lacunas a serem fechadas. Em seguida, leia os playbooks e mostre os arquivos exatos que você alterará. Edite somente após o segundo acordo.
2. Permaneça somente leitura em um site ativo. Envie apenas solicitações que leiam dados. Não crie uma conta, envie um formulário ou compre algo. O proprietário do site pode aprovar uma exceção em palavras claras. O scanner envia um POST: uma solicitação server/discover para /mcp. Essa solicitação lê apenas dados.
3. Pergunte antes de usar um scanner externo. Um scanner hospedado recebe a URL. Obtenha consentimento primeiro.
4. Proteja a segurança. Não desabilite a proteção contra bots, abra CORS para dados privados ou exponha conteúdo privado para aumentar uma pontuação. Cada playbook tem notas de segurança. Obedeça-as. Se uma página humana tiver um CAPTCHA, mantenha-o. Adicione um caminho separado para agentes, por exemplo, chaves de uma API, com controles de abuso.
5. Respeite a política de bots do proprietário. Um bloqueio em crawlers de treinamento de IA é uma decisão válida. Não o altere a menos que o usuário solicite.
6. Verifique a data de um padrão. Cada playbook tem uma data Reviewed. Se essa data for superior a 6 meses, leia a fonte primária antes de implementar.
7. Relate a verdade. Mostre a pontuação, a cobertura e cada verificação que o scanner não avaliou. Não mostre uma verificação não avaliada como aprovada.
8. Corrija a causa. Não adicione um arquivo apenas para satisfazer uma verificação. Um llms.txt com links errados é pior do que nenhum arquivo.

Os sete pilares

Os pilares seguem a jornada de um agente. Uma falha em um pilar inicial bloqueia os pilares seguintes.

Pilar	Pergunta	Playbooks
Alcançar	Um agente pode obter uma resposta, e a política de bots é explícita?	bot-access
Descobrir	Um agente pode encontrar o que existe?	llms-txt, sitemap-and-links, api-catalog, agent-discovery
Ler	Um agente pode entender o conteúdo sem navegador?	markdown-for-agents, server-rendering, structured-data
Agir	Um agente pode chamar o produto?	openapi-quality, mcp-server, webmcp, api-design
Autorizar	Um agente pode obter acesso sem presença humana?	oauth-for-agents, self-serve-access
Recuperar	Um agente pode se corrigir após um erro?	errors-and-limits
Transacionar	Um agente pode pagar?	agentic-commerce

Cada playbook é o arquivo references/<nome>.md.

Perfis

Um perfil informa ao scanner quais verificações se aplicam. Forneça o perfil com --profile. Se você omiti-lo, o scanner o detecta.

Perfil	Alvo
content	Um site de marketing, um site de documentação ou um blog
api	Uma API HTTP
webapp	Um aplicativo SaaS com contas
commerce	Uma loja

Um produto pode ter mais de uma superfície. Escaneie cada superfície com seu próprio perfil. Exemplo: escaneie example.com como content e escaneie api.example.com como api.

Para uma API, forneça a URL que responde por toda a API. Se a raiz do host responder com a API, use a raiz do host. Se a API estiver abaixo de um caminho como /api/v1 e a raiz do host servir outra coisa, use esse caminho. O scanner procura a descrição da API nos locais conhecidos do host e ao lado da URL que você fornece.

Como ler a saída do scanner

O relatório JSON tem três grupos de verificações.

Grupo	Conteúdo	Efeito na pontuação
score	Verificações medidas em padrões estáveis	Toda a pontuação
review	Verificações que precisam de julgamento, por exemplo, "um agente pode obter uma chave de API sem CAPTCHA"	Nenhum. Você as avalia.
watch	Padrões emergentes, caminhos legados e observações	Nenhum

• score é um limite inferior verificado de 0 a 100. upperBound é a pontuação se cada verificação não avaliada for aprovada.
• coverage mostra quanto da pontuação o scanner conseguiu avaliar. Um tempo limite o diminui.
• grade é null quando score e upperBound estão em faixas de nota diferentes.
• cap é definido quando uma barreira falha. Uma barreira falha quando uma solicitação simples recebe um desafio de bot, ou quando a página não tem conteúdo sem JavaScript. O cap é 59.
• opportunities lista os pontos que cada correção pode adicionar, do maior para o menor. Tem todas as lacunas. A saída de texto mostra apenas as primeiras 8.
• Cada verificação tem um playbook. Esse é o arquivo de referência com a correção.
• Uma verificação com blockedBy falhou porque outra verificação falhou primeiro. Seu status é fail, não not_assessed, portanto não diminui a cobertura. Corrija primeiro a verificação em blockedBy.
• review lista as verificações de Revisão que se aplicam ao perfil. Avalie apenas estas.

Sem --json, o scanner imprime um relatório de texto curto com a linha de pontuação e a linha do pilar. Use o relatório de texto para o usuário e o JSON para o seu trabalho.

Códigos de saída: 0 ok, 1 barreira falhou, 2 erro de uso, 3 barreira inconclusiva, 4 sem pontuação, 5 erro interno.

node <skill-dir>/scripts/ax.mjs catalog --json imprime o catálogo. Cada entrada de sua matriz checks tem um bucket. Uma verificação de Revisão também tem uma rubric com os membros pass, partial, fail e evidence.

Mantenha um relatório JSON na conversa ou em um diretório temporário fora do projeto. Não o escreva dentro do projeto, a menos que o usuário solicite.

Para a fórmula, leia references/scoring.md. Para a lista de verificações, leia references/checks.md.

Arquivos de referência

Leia um arquivo somente quando a condição for verdadeira.

Arquivo	Leia quando
references/stacks.md	Você precisa encontrar onde um arquivo, cabeçalho ou rota se encaixa no framework do projeto
references/standards.md	Você precisa saber se um padrão é estável, emergente ou legado, ou se um caminho mudou de nome
references/checks.md	Você precisa do significado de um ID de verificação ou da rubrica de uma verificação de revisão
references/scoring.md	O usuário pergunta como a pontuação funciona
references/<playbook>.md	Você implementa ou explica a capacidade desse playbook

Modelos para arquivos comuns estão em <skill-dir>/assets/. Cada playbook nomeia o modelo que usa.