GA4를 대화로 분석하기 — 클로드·코덱스에서 쓰는 스킬 ga4-skill 사용법

구글 애널리틱스 4(GA4)에서 숫자 하나 뽑겠다고 탐색 분석을 새로 만들고, 측정기준을 붙였다 뗐다 하고, 결국 원하는 표가 안 나와서 포기해본 경험이 다들 있을 것이다. 그럴 때마다 "이거 그냥 말로 물어보면 안 되나" 싶은데, 막상 AI에게 GA4를 맡기려고 하면 문이 생각보다 단단히 닫혀 있다. AI 시대, 웹 분석은 어떻게 달라지는가에서는 AI가 우리 사이트로 오는 유입을 어떻게 바꾸는지 이야기했는데, 이번에는 방향이 반대다. 분석 도구 자체를 AI가 대신 조작하는 쪽 이야기다. 그 문을 직접 열어보려고 스킬을 만들어 MIT 라이선스로 공개했고, 이번 글에서는 그 ga4-skill이 무엇이고 어떻게 쓰는지 정리하고자 한다.

ga4-skill은 AI 에이전트와 대화만으로 GA4를 연결하고 분석하게 하는 오픈소스 에이전트 스킬 4종이다. npx skills add ogaeng/ga4-skill 한 줄로 클로드 코드·코덱스·커서·제미나이 CLI 등에 설치된다. 판단은 에이전트가 하고 계산은 파이썬 스크립트가 맡는 구조라, AI가 GA4 숫자를 그럴듯하게 지어내지 못하게 막는 장치가 안에 들어 있다.

GA4를 AI에게 맡기려면 지금 어떤 선택지가 있는가

2026년 7월 기준으로 GA4를 AI에게 맡기는 방법은 크게 세 가지다. 구글이 공개한 GA4 MCP(Model Context Protocol) 서버, GA4 안에 붙은 대화형 분석 Ask Advisor, 그리고 GA4 Data API를 직접 호출하는 방식이다. 셋 다 실제로 동작하지만, 비개발자인 마케터가 혼자 앉아서 끝까지 가기에는 저마다 벽이 하나씩 있다. 공식 MCP는 gcloud와 GCP 설정을 요구하고, Ask Advisor는 영어 환경에서만 열리며, Data API 직접 호출은 그냥 개발이다.

선택지	설치	gcloud 필요	한국어 UI	정의서 대조
구글 공식 GA4 MCP	파이썬·pipx·GCP API 활성화	필요	가능	없음
Ask Advisor	불필요	불필요	불가	없음
Data API 직접 호출	직접 개발	필요	가능	직접 구현
ga4-skill	npx skills add 한 줄 + OAuth 클라이언트(조직당 1회)	불필요	가능	있음

오해를 막기 위해 먼저 밝혀두면, ga4-skill도 GCP에서 애널리틱스 API를 켜고 OAuth 클라이언트를 만드는 작업은 똑같이 필요하다. 다른 점은 그 작업이 조직당 한 번으로 끝나고, 마케터 개인은 gcloud를 만질 일이 없다는 것이다.

구글 공식 GA4 MCP 서버는 무엇이 문턱인가

구글 공식 MCP 서버는 저장소 제목부터 Google Analytics MCP Server (Experimental)이다. 요구 사항이 파이썬 3.10 이상, pipx, GCP 프로젝트에서 Admin API와 Data API 두 개를 손으로 켜기, 그리고 애플리케이션 기본 사용자 인증 정보 구성이다. README가 안내하는 인증 명령은 gcloud auth application-default login --scopes ... --client-id-file=... 형태다. 여기까지 읽고 대부분이 창을 닫는다.

Ask Advisor는 왜 한국어 환경에서 못 쓰는가

Ask Advisor는 반대로 설치가 아예 필요 없다. GA4 안에서 바로 물어보면 된다. 그런데 결정적인 제약이 있다. 구글 공식 도움말이 이렇게 못 박아뒀다.

Ask Advisor is currently available in properties with English as the selected language, with plans to expand support to other languages.

속성의 선택 언어가 영어일 때만 쓸 수 있다는 뜻이다. GA4에서 언어는 사용자 환경에 따른 설정이라, 한국어 UI로 GA4를 쓰는 국내 마케터는 자기 언어 설정을 영어로 돌리기 전에는 이 기능을 만질 수 없다. 도움말에 계정 자격 조건도 함께 걸려 있어서 영어로 바꾼다고 항상 열린다는 보장도 없다. 게다가 Ask Advisor는 속성 단위 데이터만 본다. 우리가 따로 관리하는 이벤트 정의서 스프레드시트 같은 건 아예 시야 밖이다.

참고: Google for Developers - Try the Google Analytics MCP server | Analytics Help - Ask Advisor in Google Analytics (Beta)

ga4-skill은 무엇이고 어떻게 구성되어 있는가

ga4-skill은 GA4 작업을 라우터(ga4), 연결(ga-auth), 정의서 대조(ga-taxonomy), 분석(ga-use) 네 덩어리로 쪼갠 에이전트 스킬 묶음이다. 한 번만 하고 마는 일과 매일 하는 일을 하나의 거대한 도구에 몰아넣지 않고, 성격이 다른 작업을 각자의 스킬로 분리했다. 그래서 필요한 것만 골라 쓸 수도 있다.

스킬	역할	빈도
ga4	라우터. 모호하거나 복합적인 요청을 받아 현재 상태를 진단하고 다음 단계를 제안	처음·헤맬 때
ga-auth	GA4 연결. 브라우저 로그인과 속성 선택	1회
ga-taxonomy	이벤트 정의서 파싱과 실측 대조	선택
ga-use	자연어 질문을 GA4 리포트로 변환	매일

재미있는 부분은 네 스킬이 서로의 코드를 전혀 import하지 않는다는 점이다. 대신 프로젝트 안의 .ga4/ 디렉터리에 파일을 남겨서 느슨하게 이어진다. ga-auth가 token.json과 config.json을 떨어뜨리면 ga-use가 그걸 주워서 쓰고, ga-taxonomy가 만든 taxonomy.md가 있으면 ga-use가 질문을 이벤트 이름에 매핑할 때 참고한다. 없으면 없는 대로 동작한다.

각 스킬은 SKILL.md(에이전트가 따르는 절차) + scripts/(결정적인 계산을 하는 파이썬) + tests/ + references/(상세 문법)로 구성된다. 원칙은 하나다. 판단은 에이전트가 하고, 계산은 파이썬이 한다. 숫자를 만들어내는 일에 언어 모델을 끼워 넣지 않는 것이 이 구조의 핵심이다.

ga4-skill 설치와 GA4 연결은 어떻게 하는가

ga4-skill 설치는 터미널에서 npx skills add ogaeng/ga4-skill 한 줄로 끝나고, GA4 연결은 OAuth 클라이언트 JSON을 .ga4/oauth_client.json에 놓은 뒤 에이전트에게 연결을 요청하면 된다. 브라우저 로그인과 속성 선택까지 5분에서 10분이면 마무리된다. OAuth 클라이언트를 만드는 작업만 조직에서 한 사람이 한 번 하면 되고, 그다음부터 팀원은 로그인만 하면 된다.

npx skills add ogaeng/ga4-skill

설치를 맡는 Agent Skills CLI(npx skills로 실행하는 오픈 스킬 설치 도구)는 에이전트를 가리지 않는다. 클로드 코드, 코덱스, 커서, 제미나이 CLI, 안티그래비티, 깃허브 코파일럿 등 이 규격을 지원하는 곳이면 어디서든 같은 스킬이 그대로 동작한다. 전역으로 깔고 싶으면 -g를 붙이고, 특정 에이전트에만 넣고 싶으면 -a codex나 -a cursor처럼 지정하면 된다. 네 스킬은 세트로 설계했으니 넷 다 까는 편이 좋다.

설치만으로 끝나지는 않는다. 구글 애널리틱스 데이터를 읽으려면 OAuth 클라이언트를 요구하기 때문이다. 다만 이 작업은 조직에서 한 사람이 한 번만 하면 된다. 순서는 이렇다.

1. GCP 프로젝트에서 Google Analytics Admin API와 Google Analytics Data API를 켠다.
2. OAuth 동의 화면을 설정하고, 로그인할 계정을 테스트 사용자로 등록한다.
3. 데스크톱 앱 유형으로 OAuth 클라이언트를 만든다.
4. 내려받은 JSON을 팀원에게 나눠준다.

2번의 테스트 사용자 등록을 빠뜨리면 아래에서 이야기할 가장 흔한 실패로 바로 이어지니 이때 같이 해두자. 데스크톱 앱 클라이언트의 client_secret은 원래 숨길 수 없는 값이라 조직 안에서 같은 파일을 돌려 써도 문제가 없다.

마케터가 할 일은 그 JSON을 자기 프로젝트의 .ga4/oauth_client.json에 놓는 것뿐이다.

.ga4/는 .gitignore에 넣어두자. oauth_client.json은 원래 숨길 수 없는 값이 맞지만, 로그인하고 나면 같은 폴더에 생기는 token.json은 내 GA4 데이터에 실제로 접근할 수 있는 토큰이다.

그다음은 에이전트에게 말만 걸면 된다. "GA4 연결해줘"라고 하면 ga4 라우터가 현재 상태를 진단하고 ga-auth로 넘긴다. 브라우저가 열리고, 로그인하고, 접근 가능한 속성이 계정별로 묶여서 목록으로 나오면 하나 고르면 끝이다.

경험상 여기서 막히는 지점은 늘 세 군데였고, 그래서 스킬이 이걸 미리 짚어준다.

• 테스트 사용자 미등록 — 개인 지메일로 만든 동의 화면은 테스트 모드라, 로그인할 계정을 테스트 사용자로 등록해두지 않으면 "액세스 차단됨"으로 튕긴다. 가장 흔한 실패다.
• "확인되지 않은 앱" 경고 — 내가 만든 내 앱이라 정상이다. [고급] → [계속]으로 통과하면 된다.
• 계정 전환 — 속성 목록이 비어 있으면 십중팔구 GA4 속성에 접근 권한이 없는 계정으로 로그인한 것이다.

참고: Vercel - Introducing skills, the open agent skills ecosystem

ga4-skill에 무엇을 물어볼 수 있는가

ga4-skill의 분석 스킬 ga-use는 GA4 Data API가 제공하는 여섯 가지 리포트를 다룬다. 표준 리포트·실시간·피벗·코호트·퍼널·메타데이터가 여기에 해당한다. 마케터가 이 중에서 리포트 유형을 고를 필요는 없다. 질문을 평소 말하듯 던지면 ga4-skill이 알맞은 리포트로 매핑하고, 필요한 측정기준과 측정항목까지 직접 채운다. 어떤 질문이 어디로 가는지만 알아두면 감이 잡힌다.

이렇게 물으면	이 리포트를
"지난주 페이지뷰 상위 20개 알려줘"	표준 리포트
"지금 접속자 몇 명이야?"	실시간 (최근 30분, 360은 60분)
"국가별로 모바일이랑 데스크톱 나눠서 보여줘"	피벗
"6월 가입자가 주차별로 얼마나 다시 오는지"	코호트
"상품 조회에서 구매까지 어디서 빠지는지"	퍼널
"이 속성에서 쓸 수 있는 측정기준이 뭐가 있어?"	메타데이터

한 번의 요청으로 끝나지 않는 질문도 그냥 던지면 된다. "왜 지난주보다 매출이 떨어졌지?" 같은 질문은 에이전트가 레시피(자주 쓰는 분석 절차를 미리 적어둔 문서)를 따라 여러 조회로 쪼갠다. 기간을 비교하고, 채널별로 분해하고, 어느 단계에서 이탈이 늘었는지 퍼널로 확인한 뒤 결과를 합쳐서 설명하는 식이다.

네이버 키워드 광고, 구글 애널리틱스로 쉽게 추적하기 글을 쓰던 시절을 떠올려보면 격세지감이 있다. 그때는 UTM을 일일이 손으로 붙이고 리포트를 조립하는 게 일의 절반이었는데, 이제는 그 조립 과정을 통째로 위임할 수 있게 됐다.

이벤트 정의서와 실제 수집은 어떻게 대조하는가

ga4-skill의 정의서 대조 스킬 ga-taxonomy는 이벤트 정의서에 적어둔 설계와 GA4에 실제로 쌓이는 데이터를 맞춰보는 스킬이다. 구글 시트 URL이나 로컬 xlsx·csv를 넘기면 정의서를 파싱한 뒤, 정의했는데 안 들어오는 이벤트와 정의하지 않았는데 들어오는 이벤트를 갈라서 보고한다. 권한이 있는 속성에서 직접 돌려보니, 정의서에 적힌 이벤트 31개 중 14개가 최근 30일 동안 0건이었다. 절반 가까이가 문서상으로만 존재했다는 뜻이다. 선택 단계라 없어도 분석은 되지만, 이 대조가 빠지면 분석 결과 전체가 틀어질 수 있다.

파싱 결과는 taxonomy.json과 taxonomy.md로 떨어진다. 헤더 이름이나 열 순서가 템플릿과 달라도 적당히 알아서 인식하고, 애매하면 --map으로 보정하면 된다. 정의서가 아예 없는 조직이라면 반대로 실제 수집되고 있는 데이터에서 CSV 초안을 역산해준다.

진짜 쓸모는 대조에서 나온다. 어긋남을 두 종류로 갈라서 보고한다.

• 정의했는데 안 들어오는 이벤트 — 구현 누락이다. 구축이 필요하다.
• 안 정의했는데 들어오는 이벤트 — 문서화 누락이다. 정의서를 고쳐야 한다.

앞서 이야기한 절반 가까운 미수집 이벤트가 무서운 이유가 여기 있다. 정의서만 믿고 퍼널을 짜면 실제로는 몇 명 지나가지도 않은 단계에 "3명 중 1명 완료, 전환율 33%" 같은 숫자가 붙어 아무렇지 않게 리포트에 올라간다.

이벤트를 심는 것까지는 어쩔 수 없다 쳐도, 심은 것과 적어둔 것이 일치하는지 확인하는 일만큼은 이제 자동으로 돌릴 수 있다.

AI가 GA4 데이터를 틀리게 읽지 않게 하려면 어떻게 해야 하는가

AI가 GA4 데이터를 틀리게 읽지 않게 하려면, 응답에 딸려 오는 신뢰도 정보를 도구가 대신 읽고 밝혀줘야 한다. ga4-skill에는 네 가지 장치가 들어 있다. 잘린 결과가 전부인 척하지 않고, 샘플링 표본이면 표본이라고 말하고, 표본이 작으면 비율을 말하지 않고(30건 미만이면 방향만 언급), 응답이 모호하면 판정을 포기한다. 분석 도구에서 가장 위험한 실패는 오류가 아니라 그럴듯하게 틀린 답이기 때문이다. 오류는 눈에 띄지만 틀린 답은 그대로 보고서에 실린다.

첫째, 잘린 결과를 전부인 척하지 않는다. GA4 Data API는 기본적으로 첫 1만 행만 돌려주고, limit을 올려도 25만 행이 상한이다. 상위 10개만 받았는데 실제로는 45개가 있었다면 "전체"라고 서술하는 순간 결론이 뒤집힌다. 그래서 ga4-skill은 API가 알려주는 전체 행 수(rowCount)를 근거로 응답에 truncated와 total_row_count를 자체적으로 덧붙이고, 에이전트는 그걸 보면 "상위 N개 기준"이라고 밝히거나 범위를 넓혀 다시 조회한다.

둘째, 샘플링된 표본이면 표본이라고 말한다. GA4 Data API는 응답이 표본추출된 경우 samplingMetadatas에 몇 퍼센트의 이벤트를 썼는지 담아준다. 표본이 아니면 이 필드 자체가 안 붙는다. 즉 API는 이미 알려주고 있는데, 대부분의 도구가 그걸 안 읽는다. 실제로 샘플링된 응답에서 객단가 같은 비율 지표를 매출과 같이 요청했더니 매출 숫자가 실제의 약 13분의 1로 나온 사례가 있었다. 이벤트 수는 멀쩡했기 때문에 눈으로는 안 잡힌다. 같은 맥락에서 subjectToThresholding(임계값 미달 데이터 제외)과 dataLossFromOtherRow((other) 행으로 뭉뚱그려짐)도 함께 읽는다.

셋째, 표본이 작으면 비율을 말하지 않는다. 전환 7건에서 "71% 전환"은 숫자로 포장된 노이즈다. N에 따라 분석 깊이를 제한하는 관문을 레시피에 넣었다. 10건 미만이면 비율 표현 자체를 금지하고 실제 건수로만 말한다. 30건 미만이면 방향만 언급한다. 100건 미만이면 범위로 표현한다.

넷째, 판단이 안 서면 판단을 포기한다. GA4 퍼널 API는 데이터가 없는 스텝을 응답에서 빼는 경우가 있다. 코어 리포트에는 keepEmptyRows라는 대응 옵션이 문서화되어 있지만 퍼널 리포트에는 같은 장치가 없다(퍼널 리포트는 아직 v1alpha 단계다). 그러면 응답을 그냥 순서대로 읽었을 때 스텝이 한 칸씩 밀려 엉뚱한 이름에 숫자가 붙을 수 있다. 그래서 요청한 스텝과 돌아온 스텝을 직접 대조해 steps_without_data로 분리하고, 그 차이가 "실제로 0명"인지 "응답에서 빠진 것"인지 확신이 안 서면 아예 판정하지 않는다. 틀린 단정보다 침묵이 낫다.

여기에 합산하면 안 되는 지표를 미리 경고하는 장치도 들어 있다. "이번 달 구매자 수"를 날짜별로 쪼개 합치면 같은 사람이 여러 날 구매한 만큼 부풀려진다. 한 속성에서 확인해보니 날짜별 합산은 176명, 날짜 측정기준 없이 다시 조회한 진짜 합계는 169명이었다. 7명 차이가 대단해 보이지는 않지만, 기간이 길어지고 쪼개는 측정기준이 늘수록 이 격차는 벌어진다.

이 장치들은 전부 실제 API 응답을 측정해서 만들었다. 추측으로 만든 분기는 통과하는 테스트를 달고도 실제로는 한 번도 도달하지 못하는 죽은 코드가 되기 때문이다. 우리 코드에서 정렬 키를 desc 대신 descending으로 잘못 쓴 탓에 그 값이 조용히 무시되어, "매출 상위 3개"를 요청했는데 최하위 3개가 정상처럼 돌아오던 문제도 그렇게 잡았다.

참고: Google Analytics Data API - Create a report | Google Analytics Data API - ResponseMetaData

왜 MCP가 아니라 에이전트 스킬로 만들었는가

MCP와 에이전트 스킬은 경쟁 관계가 아니다. MCP는 에이전트가 외부 시스템에 붙는 연결 규격이고, 에이전트 스킬은 "이 상황에서는 이렇게 하라"는 절차 지식이다. 굳이 비유하자면 MCP는 배관이고 스킬은 매뉴얼에 가깝다. GA4에서 필요했던 건 연결보다 절차였다. 어떤 값을 먼저 확인하고 어떤 경고가 붙으면 어떻게 해석할지를 정해두는 일이 대부분이었기 때문이다.

또 하나의 이유는 컨텍스트 비용에 있다. 에이전트 스킬 규격을 처음 제안한 앤트로픽의 공식 문서가 점진적 공개(progressive disclosure)를 3단계로 설명하면서 레벨별 토큰 비용을 명시해뒀는데, 같은 규격을 따르는 다른 에이전트도 이 방식으로 스킬을 읽어들인다.

단계	로드 시점	비용
메타데이터	항상	스킬당 약 100 토큰
SKILL.md 본문	해당 작업이 걸릴 때	5,000 토큰 미만
참조 문서·스크립트	필요할 때만	접근 전까지 0

스킬 네 개를 깔아둬도 GA4 관련 요청을 하지 않는 동안에는 400 토큰 남짓만 먹는다는 뜻이다. 그리고 결정적으로, 스크립트의 코드는 컨텍스트에 들어가지 않고 출력만 들어간다. 스크립트가 아무리 길어져도 에이전트가 읽는 건 실행 결과뿐이다. "판단은 에이전트가, 계산은 파이썬이"라는 구조가 성립하는 근거가 여기 있다.

한 가지 덧붙이면, 공식 문서는 신뢰할 수 없는 출처의 스킬을 쓰지 말라고 경고한다. 스킬은 결국 에이전트에게 시킬 일을 적어둔 문서이기 때문이다. ga4-skill을 MIT로 공개하고 소스를 그대로 열어둔 이유도 이것이다. 무엇을 시키는지 직접 읽어보고 판단하면 된다.

참고: Anthropic - Agent Skills overview | GitHub - ogaeng/ga4-skill

자주 묻는 질문

Q. 개발을 몰라도 설치할 수 있는가?

설치 자체는 npx skills add ogaeng/ga4-skill 한 줄이라 어렵지 않다. 다만 OAuth 클라이언트를 만드는 단계는 GCP 프로젝트 편집 권한이 있는 사람이 해야 한다. 조직당 한 번만 하면 되는 작업이므로, 개발자나 관리자에게 5분만 부탁하고 받은 JSON 파일을 .ga4/oauth_client.json에 놓으면 그 뒤로는 브라우저 로그인만 하면 된다.

Q. GA4 설정이 바뀌거나 데이터가 삭제될 위험은 없는가?

없다. 로그인할 때 요청하는 권한이 읽기 전용 스코프인 analytics.readonly와 spreadsheets.readonly 두 개뿐이다. 애초에 쓰기 권한을 받지 않으므로 속성 설정을 바꾸거나 데이터를 지우는 동작 자체가 불가능하다. 구글 공식 GA4 MCP 서버도 읽기 전용인데, 공식 문서가 읽기 요청만 지원하며 GA4 설정이나 구성을 수정할 수 없다고 못 박아뒀다.

Q. 구글 공식 GA4 MCP 서버와 같이 써도 되는가?

같이 써도 충돌하지 않는다. 둘은 서로 다른 경로로 GA4에 접근하고 인증 정보도 따로 관리한다. 다만 두 도구가 같은 GCP 프로젝트의 API 할당량을 나눠 쓰게 되므로, 대량 조회를 반복한다면 할당량 소진 속도가 빨라질 수 있다는 점만 염두에 두면 된다.

Q. 클로드 코드 말고 커서나 코덱스에서도 쓸 수 있는가?

쓸 수 있다. Agent Skills CLI가 지원하는 에이전트라면 어디서든 동작하며 여기에는 클로드 코드, 코덱스, 커서, 제미나이 CLI, 안티그래비티, 깃허브 코파일럿 등이 포함된다. 특정 에이전트에만 설치하고 싶으면 설치 명령 뒤에 에이전트 이름을 붙이면 된다. 다만 파이썬 스크립트를 실행하고 네트워크로 GA4 API를 호출해야 하므로, 로컬에서 명령을 실행할 수 있는 환경이어야 한다.

마치며

정리하면 ga4-skill은 GA4 연결·정의서 대조·분석을 네 개의 에이전트 스킬로 쪼개어, 마케터가 대화만으로 GA4를 다루게 만드는 오픈소스 도구다. 설치는 한 줄이고, OAuth 세팅은 조직당 한 번이면 끝난다.

만들면서 가장 많이 고민한 건 기능이 아니라 신뢰였다. AI에게 분석을 맡기는 흐름은 이미 현실이 되었다. 문제는 그때 나오는 숫자를 믿을 수 있느냐다. 잘린 결과를 전부인 척하지 않고, 표본을 표본이라 말하고, 확신이 안 설 때는 판정을 포기하는 것. 이런 장치가 앞으로 분석 도구를 고르는 기준이 되지 않을까 하는 생각이 든다.

GA4 속성에 접근 권한이 있다면 한 번 설치해서 사용해보기를 바란다. 무엇이 부족한지 직접 써봐야 알 수 있고, 저장소는 github.com/ogaeng/ga4-skill에 열려 있으니 이슈든 PR이든 남겨주면 고맙겠다.