Communitygithub.com

geo-audit

클라이언트 웹사이트가 ChatGPT, Perplexity, Google AI Overviews, Gemini, Claude, Copilot, Doubao, DeepSeek, Kimi, Yuanbao, Naver AI Briefing, Le Chat 등 AI 검색에서 노출, 인용, 추천되도록 하기 위해, URL만으로 GEO/생성형 엔진 최적화/AI 검색 최적화/AI SEO/AEO 감사를 수행하거나 이전 GEO 보고서 이후 사이트를 재확인할 때 사용합니다.

geo-audit란 무엇인가요?

이 스킬은 제공된 URL만을 기반으로 AI 검색 엔진(예: ChatGPT, Perplexity, Google AI Overviews 등)에서 사이트의 가시성을 외부에서 감사합니다. 단순한 키워드 최적화를 넘어, AI 에이전트가 웹사이트의 콘텐츠를 성공적으로 크롤링(crawl), 인덱싱(retrieve), 흡수(absorb)하고 외부에서 언급(citation)되는지에 우선순위를 둡니다. 결과는 증거 기반의 우선순위(P0/P1/P2)와 참조 증거 ID가 포함된 맞춤형 보고서로 제공되며, Claude Code, Codex, Cursor, Codeium 등 다양한 AI 코딩 도구에서 설치 및 실행할 수 있습니다. 감사 프로세스는 여러 국가 또는 언어 시장을 동시에 처리하며, 이전 감사와의 비교를 위한 재감사 모드를 지원합니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ClydeKuo/geo-skill/tree/HEAD/geo-audit

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

GEO 웹사이트 감사(Audit)

개요

URL만 주어지면, 하나 이상의 국가/언어 시장에서 AI 검색 가시성을 외부에서 진단하고 고객이 그대로 따라 수정할 수 있는 보고서를 출력합니다.

핵심 원칙: 증거 강도에 따라 노력을 배분합니다. 가장 큰 레버리지는 순서대로 크롤링 가능 → 검색 가능 → 흡수 가능 → 사이트 외부에서 언급이며, 단순한 문구 편집이 아닙니다. 모든 권장 사항은 references/evidence.md의 증거 번호와 강도를 인용해야 합니다.

이 스킬은 개방형 Agent Skills 형식을 따르며, Claude Code, Codex, Cursor 등에서 사용할 수 있습니다. bash <skill>/install.sh 명령어로 각 도구의 스킬 디렉토리에 설치합니다. 아래 모든 경로는 이 SKILL.md가 있는 디렉토리(<skill>로 표기)를 기준으로 합니다.

사용하지 않아야 할 경우

  • 전통적인 SEO 전체 감사(백링크, 키워드 순위): GEO와 관련된 경우에만 언급합니다.
  • AI 인터페이스 호출을 통한 실제 가시성 측정: 수행하지 않으며, 보고서에는 수동 방법만 제시합니다.
  • 클라이언트 웹사이트 직접 수정: 보고서만 제공하며, 최대 1–2개 단락의 샘플 수정 예시를 첨부할 수 있습니다.

필요한 환경 기능

기능용도없을 경우 대처
shell + Python 3<skill>/scripts/ 디렉토리의 감사 스크립트 실행 (표준 라이브러리만 사용)감사 불가, 사용자에게 알림
네트워크 액세스스크립트가 클라이언트 웹사이트 가져오기1단계 시도 중 발견, 중단 후 네트워크 연결 활성화 안내
웹 검색 도구 (Claude Code의 경우 WebSearch)사이트 외부 언급 확인'사이트 외부' 섹션에 '현재 환경에서 웹 검색 불가'라고 작성, 해당 섹션 생략 금지
웹 페이지 가져오기 도구 (Claude Code의 경우 WebFetch)외부 페이지 읽기curl로 대체
파일 쓰기 도구보고서 작성shell heredoc 사용
Chrome / Chromium (선택 사항)렌더링 비교스크립트가 자동으로 '미검사' 표시

파일

파일용도
scripts/crawl_check.pyAI 크롤러에 대한 robots.txt 허용(RFC 9309), UA 차단 확인, sitemap, canonical, noindex, HTTPS, llms.txt, ICP, hreflang(HTML/HTTP Link 헤더/sitemap 세 가지 출처 및 양방향 확인)
scripts/render_diff.pyJavaScript 미실행 시와 렌더링 후 본문 비율
scripts/page_audit.py제목 계층, 증거 단위, 구조화된 데이터, 작성자 및 업데이트 시간, canonical, hreflang; --save-html로 원본 HTML 저장
references/checklist.md일반 점검 목록 및 P0/P1/P2 규칙
references/markets/<코드>.md시장 프로필: cn us jp kr de fr es; 등록되지 않은 시장은 _generic.md 사용
references/evidence.md증거 라이브러리 E1–E16
references/ai-crawlers.md크롤러 용도, 공개 UA가 없는 엔진, 위장 UA의 한계
references/report-template.md보고서 구조 및 작성 규칙 (필수 사용)

모든 스크립트의 공통 매개변수: python3 <skill>/scripts/<스크립트>.py <url> [추가 url…] [--proxy URL] [--timeout 초] [--lang 언어태그] [--out 파일.json], 결과는 표준 출력에 JSON으로 출력되며, 어떤 경우든 종료 코드는 0입니다. crawl_check.py는 URL 하나만 받으며 --markets cn,us,jp 매개변수를 추가로 가집니다.

감사 절차

먼저 출력 디렉토리 geo-report-<호스트명>-<YYYYMMDD>/를 생성합니다 (현재 작업 디렉토리에 생성; <호스트명>은 최종 홈페이지 주소의 호스트명을 그대로 사용, 예: www.example.com). 모든 원시 데이터는 이곳에 저장됩니다. 보고서 파일 geo-report-<호스트명>-<YYYYMMDD>.md는 동일한 레벨에 위치합니다.

  1. 컨텍스트 수집

    • URL은 필수입니다. 브랜드, 주요 사업 내용을 묻고 사용자가 답하지 않으면 홈페이지에서 추론하여 보고서의 '감사 범위 및 가정'에 기록합니다.
    • 보고서 언어 = 사용자가 감사를 시작할 때 사용한 언어; 사용자가 별도로 지정한 경우 그 언어를 따릅니다.
    • 대상 시장 (시장 코드 목록): 사용자가 지정한 것을 우선합니다. 명시되지 않은 경우, 2단계를 먼저 실행한 후 crawl.json의 hreflang과 언어 전환기에서 추론하여 사용자에게 확인을 요청합니다. 한 번 감사는 기본적으로 최대 3개 시장; 아무도 응답하지 않을 경우 '웹사이트 기본 언어에 해당하는 시장 + hreflang에 등록된 시장 중 최대 2개 (cn, us, jp, kr, de, fr, es 순서)'를 선택하고 나머지는 '이번 감사에서 제외된 시장'으로 표시합니다. 사용자가 명시적으로 더 많은 시장을 요청하면 따르되, 페이지 수와 시간 예산은 변경되지 않습니다.
    • 시장은 국가 또는 지역 단위로 구분합니다. zh-TW / zh-HK, en-GB 등 비미국 영어, de-AT / de-CH, fr-BE / fr-CA 등은 모두 _generic을 사용하며, 참조 관계는 markets/_generic.md 1절을 참조하세요.
    • 감사 머신의 네트워크 출구 국가를 확인합니다 (예: curl -s https://ipinfo.io/country).
  2. 크롤링 가능 확인 (동시에 네트워크 연결 시험)

    python3 <skill>/scripts/crawl_check.py <url> --markets <코드목록> --lang <첫번째 대상 시장의 언어태그> --out <출력디렉토리>/crawl.json
    
    • homepage와 robots가 모두 네트워크 오류인 경우, 현재 환경에서 네트워크 연결이 불가능한 것입니다: 중단하고, 사용자에게 네트워크 연결 활성화가 필요함을 알립니다 (Codex의 활성화 방법은 README 참조). 빈 보고서를 생성하지 마십시오.
    • ai_crawlers (relevant가 true인 항목을 중점적으로 확인), ua_blocking, homepage, robots.value.source, meta_robots, x_robots_tag, canonical, https, sitemap, icp, hreflang, other_domains를 읽습니다. 판단 규칙은 references/checklist.md를, 로컬 크롤러는 각 시장 프로필 4절을 참조합니다.
    • sitemap.value.truncated가 true인 경우, count는 전체 사이트 페이지 수가 아니라 읽은 수에 불과합니다.
    • 다른 호스트의 언어 버전: hreflang.declared에서 다른 도메인/서브도메인에 있고 선택한 대상 시장에 속하는 버전은 이번 감사에 포함하며, 해당 홈페이지에 대해 crawl_check.py를 다시 실행하여 crawl-<호스트명>.json으로 출력합니다. hreflang에 선언되지 않은 다른 도메인(other_domains)은 보고서에서만 알리고 별도 감사를 권장합니다.
  3. 중점 페이지 선정: 각 대상 시장별로 최소 2페이지 (해당 시장의 언어 버전), 총 20페이지를 초과하지 않습니다. 우선 순위: 홈페이지, 핵심 제품/서비스 페이지, 비교 페이지, 가격 페이지, 회사 소개 페이지, 콘텐츠 페이지. 출처는 우선 sitemap과 내비게이션을 사용합니다.

  4. 렌더링 비교: 한 번에 1–5개 URL을 전송하며, 타임아웃 30초, 해당 시장의 언어를 사용합니다:

    python3 <skill>/scripts/render_diff.py <url1> <url2> --timeout 30 --lang ja-JP --out <출력디렉토리>/render-1.json
    
  5. 단일 페이지 감사 및 본문 읽기:

    python3 <skill>/scripts/page_audit.py <url1> <url2> … --lang ja-JP --save-html <출력디렉토리>/html --out <출력디렉토리>/pages-jp.json
    
    • 스크립트는 개수만 세며, <nav>와 페이지 수준의 <header>, <footer> 내의 링크와 제목은 제외합니다.
    • 본문을 읽을 때는 --save-html로 저장된 파일을 읽습니다. 별도의 가져오기 스크립트를 작성하지 말고, 중간 파일을 출력 디렉토리 외부에 두지 마십시오.
    • 판단해야 할 내용: 정의문, 비교, 단계, 검증 가능한 데이터가 있는지; 한 단락이 하나의 주장만을 전달하는지; 숨겨진 본문 (접힌 FAQ가 JS 데이터에만 있는 경우, 숫자 애니메이션이 HTML에서 0으로 표시되는 경우); 현지 언어 버전이 수동 로컬라이제이션되었는지, 기계 번역 흔적이 있는지; 시장 프로필 7절의 로컬라이제이션 핵심 사항.
  6. 검색 가능 여부 판단: 각 대상 시장에 대해 현지 언어로 10–20개의 질문을 추론하며, 문장 형식은 시장 프로필 6절을 참조하고 인지/비교/결정/사후 단계를 모두 포함합니다. 각 질문에 대해 해당 시장 언어 버전에 직접 답변하는 페이지가 있는지 판단하여 보고서의 '질문 적용 표'에 채웁니다 (현지 언어 원문 + 보고서 언어 번역).

  7. 사이트 외부 언급: 웹 검색 도구를 사용하여 시장 프로필 5절의 플랫폼별로 하나씩 검색하며, 있음/없음/미검사 및 대표 링크를 기록합니다. 로그인이 필요한 플랫폼은 검색하지 않습니다.

  8. 감사 선택 사항 저장: <출력디렉토리>/audit.json에 다음과 같이 작성합니다:

    {"target": "", "markets": ["jp", "us"], "report_language": "ja", "brand": "", "business": "",
     "pages": {"jp": ["…"], "us": ["…"]}, "questions": {"jp": ["…"], "us": ["…"]},
     "offsite_queries": {"jp": ["…"], "us": ["…"]}, "extra_hosts": ["…"],
     "proxy_country": {"jp": "JP"}, "date": "YYYY-MM-DD"}
    

    proxy_country는 사용한 출구 국가만 기록하고 (사용하지 않은 경우 {}), 프록시 주소는 기록하지 않습니다.

  9. 보고서 작성: references/report-template.md의 구조를 따르며, 보고서 언어로 작성합니다. 장 번호는 고정이며, 해당하지 않는 경우 '해당 없음'이라고 작성합니다.

재감사 모드

사용자가 이전 geo-report-<호스트명>-<날짜>/ 디렉토리를 제공하는 경우: 그 안의 audit.json을 읽고 동일한 시장, 중점 페이지, 추론 질문, 외부 검색어를 그대로 사용하여 2–7단계를 다시 실행하고 보고서의 '수정 전후 비교' 장을 작성합니다.

이전 버전의 audit.json에서 "market": "cn" | "global" | "both"를 사용하는 경우, 다음 규칙에 따라 변환합니다: "cn" → cn; "global" → us; "both" → cn,us. 이전 버전의 questions 키 global은 us에 해당합니다.

속도 제한 및 시간 예산

  • 스크립트는 이미 백오프(back-off)가 내장되어 있습니다: 429 또는 Retry-After가 포함된 503을 만나면 대기 후 한 번 재시도하고 이후 요청 속도를 자동으로 늦춥니다. 결과에 rate_limited: true가 표시되거나 여러 페이지에서 연속으로 429가 반환되는 경우:
    • 남은 중점 페이지를 각 시장당 2페이지로 줄입니다;
    • 보고서 '감사 범위 및 가정'에 '사이트 속도 제한으로 인해 표본 페이지 수가 감소했습니다.'라고 명시합니다.
  • 속도 제한이 걸리면 단일 스크립트가 수 분간 실행될 수 있습니다 (Retry-After 대기). 스크립트를 실행할 때 셸 타임아웃을 10분으로 설정하거나 백그라운드에서 실행하고, 타임아웃으로 인해 JSON 출력이 손실되지 않도록 하십시오.
  • 전체 감사는 45분 이내에 완료하는 것이 좋습니다. 초과 시 추가 가져오기를 중단하고 기존 데이터로 보고서를 작성하며, 완료되지 않은 검사를 명시합니다.
  • 금지 사항: 속도 제한을 우회하기 위해 프록시나 출구 IP를 교체하거나, UA를 변경하거나, 재시도를 가속화하는 행위.
  • --proxy로 특정 국가의 출구를 지정하는 경우는 다음 두 가지 경우로 제한됩니다: 해당 대상 국가의 접근성 테스트; 사이트가 접속 지역에 따라 다른 콘텐츠를 반환하는 경우. 어떤 국가의 출구를 사용했는지 보고서에 기록해야 하며, 국가만 기록하고 프록시 주소는 기록하지 않습니다 (프록시 주소는 감사 기관의 내부 정보이며, 보고서와 audit.json 모두 고객에게 전달되어야 함).

판단 핵심

스크립트 결과의미보고서 작성 방법
ai_crawlers에서 검색 또는 사용자 트리거 유형이 failrobots.txt에서 명시적으로 차단P0
ai_crawlers에서 unknownrobots.txt를 읽을 수 없음'미검사' 및 이유 작성
ai_crawlers에서 학습 유형이 warn학습 크롤러를 차단했음장단점만 설명
ua_blocking이 suspect브라우저 UA는 정상, 위장된 AI UA가 차단됨P1, '의심됨', 고객에게 CDN/WAF 또는 서버 로그 확인 요청
ua_blocking이 warn / unknown모두 차단됨 / 속도 제한 또는 요청 실패감사가 제한되었음을 설명
homepage가 unknown감사 머신이 WAF 챌린지에 걸림'사이트 사용 불가'가 아님, 다른 네트워크에서 확인 필요
render_diff의 ratio < 0.5AI 크롤러가 기본적으로 본문을 볼 수 없음P0, js_only_headings 나열
hreflang.alternates에서 fail / warn언어 버전을 열 수 없음 / 양방향 아님P1 / P2
모든 항목이 unknown검사 불가'미검사' 및 이유 작성, 평가하지 않음
llms_txt존재 여부만 기록'권장하지 않음'에 포함
raw_words / rendered_words한중일 문자는 글자당 1, 다른 언어는 단어 단위언어별 단어 수는 직접 비교 불가

레드라인(Red Lines)

  • 모든 문제는 증거가 있어야 하며, 모든 권장 사항에는 증거 번호와 강도를 표시해야 합니다. 대상 시장이 us가 아닌 경우 '(추정)'을 추가하며, 시장 프로필 8절에 다른 설명이 있는 경우는 예외입니다. 등록되지 않은 시장은 '해당 시장은 등록되지 않았으므로 증거가 약함'이라고 명시합니다.
  • 가져오지 못한 내용은 '미검사'라고 쓰고, 인상에 근거하여 평가하지 마십시오.
  • 데이터 조작, 평가 위조, 리뷰 조작, AI에 숨겨진 명령 삽입, 경쟁사 비방, 기계 번역을 사용한 대량 다국어 버전 생성 등은 권장하지 않습니다 (E13).
  • llms.txt, FAQ화, Schema, 권위적인 어조를 핵심 권장 사항으로 삼지 마십시오 (E10, E9, E7).
  • 트래픽이나 순위 향상을 약속하지 마십시오 (E15).
  • 보고서 언어는 사용자가 질문한 언어와 일치해야 합니다 (사용자가 별도로 지정한 경우 제외).

일반적인 실수

  • suspect를 확정적인 차단으로 간주: robots.txt의 명시적인 차단만이 P0입니다.
  • Google 순위로 AI 가시성 추론: 둘의 겹침은 매우 낮습니다 (E13). 각 시장, 각 엔진을 별도로 봐야 합니다.
  • 보고서 언어로 질문 추론: 추론 질문은 대상 시장의 현지 언어와 현지 사용자의 질문 방식을 사용해야 합니다.
  • 스크립트 개수만 보고 결론 내리기: numbers가 많다고 해서 데이터를 검증할 수 있는 것은 아니며, external_links에는 <div>로 작성된 푸터 링크가 섞여 있을 수 있으므로 본문을 읽어야 합니다.
  • sitemap의 count를 전체 사이트 페이지 수로 간주: truncated가 true일 때는 명시해야 합니다.
  • 속도 제한을 당한 후에도 버티기: '속도 제한 및 시간 예산' 절에 따라 페이지 수를 줄이고, 자체 루프를 작성하여 장시간 기다리지 마십시오.
  • 다른 호스트의 언어 버전 누락: hreflang에서 다른 도메인에 선언된 대상 시장 버전을 감사에 포함해야 합니다.

관련 스킬