AX Kit
UX는 인간의 경험입니다. 에이전트 경험(AX)은 사용자를 위해 제품을 사용하는 AI 에이전트의 경험입니다. 에이전트는 눈도 없고, CAPTCHA를 기다릴 인내심도 없으며, 물어볼 사람도 없습니다. 오직 제품이 기계에 노출하는 것만 사용할 수 있습니다.
이 스킬은 사이트, API, SaaS 앱 또는 스토어의 에이전트 대면 레이어를 개선합니다. 에이전트가 사용하는 표준을 구현하고, 스캐너로 결과를 측정합니다. 점수는 작업에 대한 피드백입니다. 점수가 목표는 아닙니다.
설정
<skill-dir>은 이 SKILL.md 파일이 포함된 디렉토리입니다. 작업 디렉토리를 사용자의 프로젝트에 유지하십시오.
스캐너는 <skill-dir>/scripts/ax.mjs입니다. Node.js 18 이상이 필요하며 종속성이 없습니다.
node <skill-dir>/scripts/ax.mjs scan <url> --profile <content|api|webapp|commerce> --json
node가 없거나 버전 18보다 오래된 경우 사용자에게 알리십시오. 그런 다음 스캐너 없이 플레이북을 계속 진행하십시오.
명령어
사용자의 요청에서 명령어를 찾으십시오. 그런 다음 해당 명령어에 대한 가이드를 읽고 따르십시오.
| 명령어 | 사용자가 다음을 원할 때 사용 | 가이드 | 코드 수정 여부 |
|---|---|---|---|
improve | 제품을 에이전트에 더 적합하게 만들고, 스캔, 수정, 확인의 루프를 수행 | references/improve.md | 예 |
add <capability> | 하나의 기능(예: llms-txt 또는 mcp-server)을 구현 | references/add.md | 예 |
audit <url> | 변경 없이 전체 진단 및 보고서 획득 | references/audit.md | 아니요 |
score <url> | AX 점수와 주요 격차를 신속하게 확인 | references/score.md | 아니요 |
design | 코드가 존재하기 전에 계획된 API, 사이트 또는 기능 검토 | references/design.md | 아니요 |
ci | 점수에 파이프라인 게이트와 배지 추가 | references/ci.md | 예 |
요청에 명령어가 명시되지 않았고 추론할 수 없는 경우, 이 표를 보여주고 사용자가 원하는 명령어를 물어보십시오. 메뉴에서 작업을 시작하지 마십시오.
모든 명령어에 적용되는 규칙
이 규칙은 참조 파일보다 우선합니다.
- 수정 전에 확인하십시오. 사용자의 동의를 두 번 받으십시오. 먼저, 해결해야 할 격차에 동의합니다. 그런 다음 플레이북을 읽고 변경할 정확한 파일을 보여주십시오. 두 번째 동의 후에만 수정하십시오.
- 실시간 사이트에서는 읽기 전용을 유지하십시오. 데이터를 읽는 요청만 보내십시오. 계정을 생성하거나, 양식을 제출하거나, 무언가를 구매하지 마십시오. 사이트 소유자는 일반적인 표현으로 예외를 승인할 수 있습니다. 스캐너는 하나의
POST요청, 즉/mcp에 대한server/discover요청을 보냅니다. 이 요청은 데이터만 읽습니다. - 외부 스캐너를 사용하기 전에 물어보십시오. 호스팅된 스캐너는 URL을 수신합니다. 먼저 동의를 얻으십시오.
- 보안을 보호하십시오. 봇 보호를 비활성화하거나, 개인 데이터에 대한 CORS를 열거나, 점수를 높이기 위해 개인 콘텐츠를 노출하지 마십시오. 각 플레이북에는 보안 관련 참고 사항이 있습니다. 이를 준수하십시오. 인간 페이지에 CAPTCHA가 있으면 유지하십시오. 예를 들어 API의 키와 같이, 남용 방지 기능이 있는 에이전트 전용 경로를 추가하십시오.
- 소유자의 봇 정책을 존중하십시오. AI 학습 크롤러에 대한 차단은 유효한 결정입니다. 사용자가 요청하지 않는 한 변경하지 마십시오.
- 표준의 날짜를 확인하십시오. 각 플레이북에는
검토됨(Reviewed)날짜가 있습니다. 해당 날짜가 6개월 이상 지난 경우, 구현하기 전에 원본 출처를 읽으십시오. - 진실을 보고하십시오. 점수, 적용 범위 및 스캐너가 평가하지 않은 각 검사를 표시하십시오. 평가되지 않은 검사를 통과한 것으로 표시하지 마십시오.
- 원인을 수정하십시오. 검사를 통과하기 위해서만 파일을 추가하지 마십시오. 잘못된 링크가 있는
llms.txt는 파일이 없는 것보다 더 나쁩니다.
7가지 기둥
기둥은 에이전트의 여정을 따릅니다. 초기 기둥의 실패는 그 이후의 기둥을 차단합니다.
| 기둥 | 질문 | 플레이북 |
|---|---|---|
| 도달(Reach) | 에이전트가 응답을 받을 수 있으며, 봇 정책이 명시적인가? | bot-access |
| 발견(Discover) | 에이전트가 무엇이 존재하는지 찾을 수 있는가? | llms-txt, sitemap-and-links, api-catalog, agent-discovery |
| 읽기(Read) | 에이전트가 브라우저 없이 콘텐츠를 이해할 수 있는가? | markdown-for-agents, server-rendering, structured-data |
| 실행(Act) | 에이전트가 제품을 호출할 수 있는가? | openapi-quality, mcp-server, webmcp, api-design |
| 권한 부여(Authorize) | 에이전트가 사람 없이 접근 권한을 얻을 수 있는가? | oauth-for-agents, self-serve-access |
| 복구(Recover) | 에이전트가 오류 후 스스로 수정할 수 있는가? | errors-and-limits |
| 거래(Transact) | 에이전트가 지불할 수 있는가? | agentic-commerce |
각 플레이북은 references/<name>.md 파일입니다.
프로필
프로필은 스캐너에 어떤 검사가 적용되는지 알려줍니다. --profile과 함께 제공하십시오. 생략하면 스캐너가 감지합니다.
| 프로필 | 대상 |
|---|---|
content | 마케팅 사이트, 문서 사이트 또는 블로그 |
api | HTTP API |
webapp | 계정이 있는 SaaS 애플리케이션 |
commerce | 스토어 |
하나의 제품은 여러 표면을 가질 수 있습니다. 각 표면을 자체 프로필로 스캔하십시오.
예: example.com을 content로 스캔하고, api.example.com을 api로 스캔합니다.
API의 경우, 전체 API에 응답하는 URL을 제공하십시오. 호스트 루트가 API로 응답하면 호스트 루트를 사용하십시오. API가 /api/v1과 같은 경로 아래에 있고 호스트 루트가 다른 것을 제공하는 경우, 해당 경로를 사용하십시오.
스캐너는 API 설명을 호스트의 잘 알려진 위치와 사용자가 제공한 URL 옆에서 찾습니다.
스캐너 출력 읽는 방법
JSON 보고서에는 세 가지 검사 버킷이 있습니다.
| 버킷 | 내용 | 점수에 미치는 영향 |
|---|---|---|
score | 안정적인 표준에 대한 측정된 검사 | 점수의 전부 |
review | 판단이 필요한 검사 (예: "에이전트가 CAPTCHA 없이 API 키를 얻을 수 있음") | 없음. 사용자가 평가합니다. |
watch | 새로운 표준, 레거시 경로 및 관찰 사항 | 없음 |
score는 0에서 100까지 검증된 하한입니다.upperBound는 평가되지 않은 각 검사가 통과할 경우의 점수입니다.coverage는 스캐너가 평가할 수 있었던 점수의 양을 보여줍니다. 시간 초과는 이를 감소시킵니다.grade는score와upperBound가 다른 등급 대역에 있을 때null입니다.cap은 게이트가 실패할 때 설정됩니다. 게이트는 일반 요청이 봇 챌린지를 받거나, 페이지에 JavaScript 없이 콘텐츠가 없을 때 실패합니다. 한도는 59입니다.opportunities는 각 수정이 추가할 수 있는 포인트를 가장 큰 것부터 나열합니다. 모든 격차가 포함됩니다. 텍스트 출력은 처음 8개만 표시합니다.- 각 검사에는
playbook이 있습니다. 이는 수정 방법이 포함된 참조 파일입니다. blockedBy가 있는 검사는 다른 검사가 먼저 실패했기 때문에 실패했습니다. 상태는fail이며not_assessed가 아니므로 적용 범위를 감소시키지 않습니다. 먼저blockedBy의 검사를 수정하십시오.review는 프로필에 적용되는 검토 검사를 나열합니다. 이것들만 평가하십시오.
--json 없이 스캐너는 점수 라인과 기둥 라인이 포함된 짧은 텍스트 보고서를 출력합니다. 사용자에게는 텍스트 보고서를 사용하고, 작업에는 JSON을 사용하십시오.
종료 코드: 0 정상, 1 게이트 실패, 2 사용법 오류, 3 게이트 불확실, 4 점수 없음, 5 내부 오류.
node <skill-dir>/scripts/ax.mjs catalog --json은 카탈로그를 출력합니다. checks 배열의 각 항목에는 bucket이 있습니다. 검토 검사에는 pass, partial, fail 및 evidence 멤버가 있는 rubric도 있습니다.
JSON 보고서를 대화 내용이나 프로젝트 외부의 임시 디렉토리에 보관하십시오. 사용자가 요청하지 않는 한 프로젝트에 쓰지 마십시오.
공식에 대해서는 references/scoring.md를 읽으십시오. 검사 목록은 references/checks.md를 읽으십시오.
참조 파일
조건이 참일 때만 파일을 읽으십시오.
| 파일 | 다음 경우에 읽으십시오 |
|---|---|
| references/stacks.md | 프로젝트 프레임워크에서 파일, 헤더 또는 경로가 어디에 위치해야 하는지 찾아야 할 때 |
| references/standards.md | 표준이 안정적인지, 새로운 것인지, 레거시인지, 또는 경로 이름이 변경되었는지 알아야 할 때 |
| references/checks.md | 검사 ID의 의미나 검토 검사의 루브릭이 필요할 때 |
| references/scoring.md | 사용자가 점수 작동 방식을 물을 때 |
references/<playbook>.md | 해당 플레이북의 기능을 구현하거나 설명할 때 |
공통 파일의 템플릿은 <skill-dir>/assets/에 있습니다. 각 플레이북은 사용하는 템플릿을 지정합니다.