1. claude-seo 가 하는 일
claude-seo 는 Claude Code 안에서 쓰는 오픈소스 플러그인입니다. Claude Code 는 터미널에서 쓰는 Anthropic 의 코딩 에이전트이고, 플러그인은 거기에 기능을 덧붙이는 꾸러미입니다. 이 꾸러미가 하는 일은 SEO 점검입니다. SEO 는 검색 결과에서 내 사이트가 잘 보이도록 사이트를 다듬는 일을 말합니다.
사용자가 사이트 주소를 주면 Claude 가 서브에이전트를 최대 17개까지 동시에 띄웁니다. 서브에이전트는 맡은 일이 정해진 보조 AI 입니다. 기술, 콘텐츠, 구조화 데이터, AI 검색 같은 영역을 하나씩 나눠 맡습니다. 끝나면 0~100점의 점수와 고칠 순서를 적은 계획서를 파일로 남깁니다.
위 숫자는 저장소에서 2026.10.22 에 확인했습니다(최신 릴리스 v2.4.2, 2026.10.04). 서브스킬은 명령 하나가 맡은 일을 적어 둔 설명서입니다. 에이전트 19개 가운데 /seo audit 에서 늘 뜨는 것은 9개이고, 사이트 성격에 따라 8개가 더 붙어 최대 17개가 됩니다.
자주 쓰는 명령
| 명령 | 하는 일 | 남기는 것 |
|---|---|---|
/seo audit <주소> |
사이트 전체를 점검합니다. 최대 500쪽까지 둘러보고 에이전트에게 나눠 맡깁니다. | FULL-AUDIT-REPORT.md, ACTION-PLAN.md, 점수 0~100 |
/seo page <주소> |
한 쪽만 깊게 봅니다. | 화면 보고, 점수 0~100 |
/seo technical <주소> |
검색 엔진이 사이트를 읽는 데 필요한 기술 항목 9분야(크롤링, 색인, 보안, 모바일, 속도 등)를 봅니다. | 분야별 통과·경고·실패 |
/seo schema <주소> |
구조화 데이터를 검사하고 만들어 줍니다. 구조화 데이터는 이 쪽이 무엇인지 검색 엔진에 알려 주는 표시(JSON-LD)입니다. | SCHEMA-REPORT.md, 등급 |
/seo geo <주소> |
ChatGPT 나 구글 AI 답변 같은 AI 검색이 이 글을 인용하기 좋은 모양인지 봅니다. 이 일을 GEO 라고 부릅니다. | GEO-ANALYSIS.md, 점수 |
/seo agentic <주소> |
AI 에이전트가 사이트를 읽고 쓰기 좋은지 봅니다. | N개 중 X개 통과(N 최대 6), 고칠 목록 |
/seo drift compare <주소> |
제목이나 구조화 데이터가 몰래 바뀌지 않았는지 전후를 비교합니다. 먼저 baseline 으로 기준을 저장해 둬야 합니다. |
비교 보고 |
README 는 명령이 34개라고 적습니다. 위는 이 글에서 쓰거나 눈여겨볼 것만 골랐습니다.
점수는 이렇게 정합니다
전체 점수(SEO Health Score)는 영역마다 가중치를 곱해 합칩니다. 콘텐츠 품질 23%, 기술 SEO 22%, 온페이지 SEO 20%(한 쪽 안의 제목·본문·링크 같은 요소), 구조화 데이터 10%, 속도 10%, AI 검색 준비도 10%, 이미지 5%입니다. 이 표는 저장소의 지침서에 적혀 있습니다.
그런데 이 표로 점수를 계산하는 코드는 저장소에 없습니다. Claude 가 지침서를 읽고 점수를 매깁니다. 이 점은 6절에 다시 적었습니다.
2. 설치하기
먼저 준비물입니다. 아래는 저장소 문서에 적힌 것입니다(2026.10.22 확인).
- Claude Code 1.0.33 이상
- Python 3.10 이상(3.11 이상을 권합니다)
- Git
- Claude 구독 또는 API 키. 플러그인은 무료지만, 점검할 때 Claude 사용량이 듭니다.
- Node.js. 문서의 준비물 목록에는 없습니다. 그런데 플러그인의 훅이
node로 실행되는 것을 저는 저장소의hooks/hooks.json에서 확인했습니다. 훅은 파일을 고칠 때마다 자동으로 도는 검사입니다.
Claude Code 입력창에 아래 네 줄을 차례로 넣습니다.
-
플러그인 마켓 추가
/plugin marketplace add AgriciDaniel/claude-seo -
플러그인 설치
/plugin install claude-seo@agricidaniel-claude-seo -
처음 준비 — 전용 파이썬 환경과 크롬(Playwright)을 깝니다
/seo setup -
준비가 됐는지 확인 — 아무것도 바꾸지 않고 상태만 알려 줍니다
/seo doctor
/seo setup 은 전용 파이썬 환경을 만들고, 파이썬 패키지는 PyPI 에서, Chromium 브라우저는 Playwright 의 배포 서버에서 내려받습니다. Playwright 는 브라우저를 코드로 움직이는 도구입니다. 자바스크립트로 그려지는 사이트를 읽고 화면을 찍는 데 씁니다.
설치하기 전에 설치 스크립트 코드를 먼저 읽어 봤습니다(2026.10.22). 수상한 네트워크 호출, 관리자 권한 요청, 원격 코드 실행은 찾지 못했습니다. 내려받는 것은 PyPI 패키지와 Chromium 입니다. 설치 스크립트가 git 으로 받는 저장소와 PyPI 패키지에는 서명이나 해시로 확인하는 단계가 없습니다. 읽어서 본 것이라 안전을 보증하는 말은 아닙니다.
윈도우에서 알려진 문제 — 다른 사람들이 GitHub 에 올린 보고이고, 2026.10.22 에 모두 '열림'(아직 고쳐지지 않음) 상태였습니다.
- 이슈 #344: Claude 데스크톱 앱의 마켓플레이스가 v2.4.2 를 건너뜁니다. 명령줄 Claude Code 에서는 설치됩니다.
- 이슈 #348:
/seo setup이 다 내려받은 뒤 마지막 폴더 교체에서WinError 5(접근 거부)로 멈춥니다. Windows 11 ARM64 에서 보고됐습니다. - 이슈 #354: Python 3.15 가 깔려 있으면
install.ps1이 실패합니다.
이 컴퓨터(Windows 11)에서는 #344 를 피하려고 처음부터 명령줄 Claude Code 로 설치했고, /seo setup 은 한 번에 끝났습니다(#348 은 나지 않았습니다).
제가 실제로 한 설치 — 데스크톱 앱 대신 명령줄에서, 이 사이트 폴더 안에서만 켜지도록(--scope project) 깔았습니다. 그러면 파일을 고칠 때마다 도는 검사 훅이 다른 프로젝트에서는 돌지 않습니다.
claude plugin marketplace add AgriciDaniel/claude-seo --scope project
claude plugin install claude-seo@agricidaniel-claude-seo --scope project
/seo setup 은 전용 파이썬 환경과 Chromium 을 준비했고, /seo doctor 에서도 문제가 없었습니다. 하나 걸린 것은 Git Bash 였습니다. Git Bash 에서 /seo 를 치면 셸이 이것을 파일 경로(C:/Program Files/Git/seo)로 바꿔 버립니다. Git Bash 에서는 //seo 로 치거나 Claude Code 입력창에서 치세요.
3. 첫 점검 돌리기
점검한 사이트는 지금 보고 계신 이 노트 사이트입니다. 막 만들어 올린 날(2026.10.22), 일부러 SEO 를 따로 꾸미지 않은 상태로 돌렸습니다. 쪽은 홈과 이 글, 두 개뿐이었습니다.
/seo audit https://bable.protocolgaia.com
- 걸린 시간과 비용: 89초, 비용 $0.32(Claude 사용량)였습니다. 큰 사이트에서 토큰을 많이 썼다는 보고(6절)와 달리, 두 쪽짜리라 가벼웠습니다.
- 에이전트는 하나도 뜨지 않았습니다. 보고서에 "사이트가 작아서 서브에이전트를 쓸 필요가 없다"고 적고 혼자 점검했습니다. 에이전트 여러 개가 동시에 뜨는 모습은 쪽이 많은 사이트에서 볼 수 있을 것 같습니다.
- 로컬 주소는 점검하지 않습니다. 내 컴퓨터에서 띄운 개발 서버(localhost)는 안전 장치 때문에 막혀 있어서, 사이트를 먼저 올린 뒤 실제 주소로 돌렸습니다. 이 컴퓨터는 인터넷 요청을 내부 프록시로 보내고 있었는데, claude-seo 가 내부 주소 프록시도 거부하게 되어 있어서 점검하는 동안만 프록시 설정을 뺐습니다.
- 결과물: 사이트 이름으로 된 폴더에
FULL-AUDIT-REPORT.md(전체 보고서)와ACTION-PLAN.md(고칠 순서)가 생깁니다.
4. 결과 읽는 법
첫 점검 점수는 52점이었습니다. 보고서는 영역별 점수, 급한 순서대로 묶은 문제(치명 · 높음 · 중간 · 낮음), 잘 된 점으로 나뉩니다.
치명으로 짚은 것 — 둘 다 맞는 지적이었습니다. 주소를 직접 열어 확인했습니다.
robots.txt,sitemap.xml,llms.txt, 파비콘 주소가 모두 홈 화면을 '정상(200)'으로 돌려줬습니다. 검색 엔진에게 줄 안내 파일이 없는데, 있는 것처럼 보였던 것입니다.- 없는 주소(예:
/zzz-nope)도 홈 화면을 200으로 돌려줬습니다. 이렇게 되면 아무 주소나 홈과 같은 쪽으로 보입니다. - 원인은 하나였습니다. 사이트를 올린 Cloudflare Pages 는
404.html이 없으면 없는 주소에 홈을 대신 보냅니다.
높음으로 짚은 것 — 대표 주소 표시(canonical), 공유할 때 보이는 미리보기(Open Graph), 구조화 데이터(이 쪽이 무엇인지 검색 엔진에 알려 주는 표시)가 없었습니다. 세 가지 모두 일부러 넣지 않았던 것이라, 빠짐없이 짚힌 셈입니다.
잘 된 점으로 꼽은 것 — 쪽마다 제목과 설명이 다르고, 자바스크립트 없이도 본문이 읽힌다는 것. 그리고 글마다 확인한 날짜와 출처를 단 것을 "강한 신뢰 신호"라고 했습니다.
한국 사이트다운 권고도 있었습니다. 구글 Search Console 에 더해 네이버 서치어드바이저에도 등록하라고 했습니다.
5. 고치고 다시 점검
보고서의 고칠 순서(ACTION-PLAN.md)대로, 이 사이트를 만드는 빌드 코드에서 고쳤습니다. 계정이 필요한 일(서치콘솔 · 네이버 등록)만 빼고 모두 했습니다.
| 고친 것 | 왜 걸렸나 | 어떻게 고쳤나 |
|---|---|---|
| 없는 주소가 홈으로 나옴 | 404.html 이 없어 Pages 가 홈을 대신 보냄 |
사이트 모양 그대로의 404.html 을 넣음 → 없는 주소는 진짜 404 |
| robots · sitemap · llms.txt | 파일이 없었음 | 빌드가 직접 만들어 넣음(/admin/ 은 막음) |
| canonical · 미리보기 | 넣지 않았음 | 쪽마다 대표 주소와 미리보기 태그 · 그림(1200×630) |
| 구조화 데이터 | 넣지 않았음 | 홈은 WebSite · Organization, 글은 BlogPosting |
| 파비콘 · 보안 헤더 | 없었음 | 파비콘과 HSTS · CSP 같은 보안 헤더 |
다시 올리고 같은 명령으로 다시 점검했습니다(98초, $0.36).
| 영역 | 첫 점검 | 다시 점검 |
|---|---|---|
| 전체 | 52 | 76 |
| 기술 SEO | 35 | 92 |
| 온페이지 | 55 | 85 |
| 구조화 데이터 | 0 | 78 |
| AI 검색 준비 | 55 | 80 |
| 콘텐츠 | 60 | 58 |
| 성능(둘 다 추정) | 70 | 70 |
- 고친 것은 다시 점검에서 모두 "반영된 것을 확인했다"고 나왔습니다.
- 남은 가장 큰 지적은 글이 하나뿐이라는 것입니다. 이건 코드로 고칠 수 없고, 글을 쌓아야 합니다.
- 틀린 지적도 하나 있었습니다. "저자와 날짜가 사람이 보는 화면에 없다"고 했지만, 이 글 맨 위에 '쓴 날 · 확인한 날'이 보입니다. 맞는 부분은 날짜에
<time>표시가 없고 저자 이름이 없다는 것까지였습니다. 6절에 적은 대로, 고치기 전에 한 번 되물어 보는 게 좋습니다. - 같은 명령인데 첫 보고서는 영어로, 두 번째 보고서는 한국어로 나왔습니다.
- 점수는 Claude 가 매기기 때문에 실행마다 흔들립니다(6절). 오른 24점이 모두 고친 덕분이라고 단정할 수는 없습니다. 다만 기술 SEO 처럼 실제로 바뀐 것을 짚어 오른 부분은 분명합니다.
6. 알아 둘 점
- README 의 성장 그래프는 만든 사람의 자료입니다. 그래프는 이 도구를 홍보하는 사이트(claude-seo.md)의 Search Console 화면입니다(2026.03.23~06.12, 3개월 클릭 약 1만 800, 노출 약 32만 4천). 고객 사례가 아니고, 도구 덕분인지 따로 가릴 수도 없습니다. 이 도구를 쓰면 검색 유입이 오른다는 증거로 읽으면 안 됩니다.
- 공개판과 별도로 유료 커뮤니티 안에 비공개판이 있습니다. 공개 저장소는 MIT 라이선스로 무료입니다. 비공개 저장소는 Skool 의 유료 커뮤니티 Pro 회원용이고, 새 기능이 먼저 들어간다고 README 가 밝힙니다. Pro 는 월 $144 로 표시돼 있었습니다(2026.10.22 확인). 이 글은 공개판(v2.4.2) 기준입니다.
- 점수는 Claude 가 매깁니다. 0~100점을 계산하는 코드가 저장소에 없습니다. README 에는 "deterministic"(같은 입력이면 같은 결과)이라는 말이 있지만, 점수에는 맞지 않습니다. 외부 벤치마크는 같은 사이트에서 실행마다 ±8점쯤 흔들린다고 적었습니다. 점수는 참고로만 보세요.
- 사용량(토큰)을 많이 씁니다. 5쪽짜리 블로그를 점검하는 데 에이전트 11개가 합쳐 약 85만 토큰을 썼다는 보고가 있습니다(이슈 #272, v2.2.5, Windows 11, 2026.08.29). 그중 10개는 턴 한도에 걸려 결과 파일을 못 썼습니다. 이 문제는 2026.09.10 에 턴 한도를 늘리고 중간 결과를 저장하도록 고쳐졌습니다(이슈 #177).
- 그 뒤로 비용이 더 늘었습니다. v2.3.1 에서 에이전트 5개를 더 비싼 Opus 모델로 올렸고, README 가 "점검 비용이 v2.3.0 보다 늘었다"고 직접 적었습니다. v2.4.2 에는 그 5개를 Sonnet 으로 돌리는 절약 모드가 선택 기능으로 생겼습니다. 외부 벤치마크의 1회 중앙값은 $1.70, 415초였습니다(2026.07.07, 일반 프롬프트로 돌린 것이라
/seo audit와 같지는 않습니다). 구독 한도가 빠듯하면/seo page로 한 쪽부터 해 보세요. - Claude Code 만 쓴 것보다 낮게 나온 측정이 1건 있습니다. seo-skill-bench(2026.07.07)에서 claude-seo 는 67.7점(심어 둔 결함 발견 38%), 스킬 없는 Claude Code 는 73.0점(71%)이었습니다. 다만 이 벤치마크를 운영하는 쪽이 경쟁 스킬을 만든 곳이고(스스로 밝혔습니다), 프롬프트가
/seo audit가 아니었으며, 점수 차 ±8 안은 무승부로 보라고 적혀 있습니다. 신호 하나로만 보세요. - 한국어 글은 평가 잣대가 다릅니다. 콘텐츠 품질 검사는 v2.3.0 부터 한국어를 낱말로 나누지만, 군더더기와 AI 말투를 찾는 낱말 목록은 영어만 있다고 변경 기록에 적혀 있습니다. 한국어 글의 콘텐츠 점수는 영어 사이트와 같은 기준이 아닙니다.
- 틀린 지적이 나올 수 있습니다. 쇼핑몰 플랫폼 Shopify 에서 정상인 canonical(대표 주소 표시)을 '치명적'이라 했다가 되물으니 거둬들였다는 유튜브 댓글이 있습니다. 구조화 데이터 검사 훅이 멀쩡한 파일을 막았다는 이슈도 반복됩니다(#333, #357, 열림). 고치기 전에 한 번 되물어 확인하세요.
- 외부 글을 읽는 구조라 주의가 필요합니다. 에이전트가 남의 사이트 HTML 을 그대로 읽으므로, 그 안에 숨은 명령에 속는 공격(프롬프트 주입)의 길이 열려 있습니다. 제3자 점검(Gen Agent Trust Hub, 2026.10.05)은 '안전' 판정을 내리면서도 같은 점을 주의 항목으로 표시했습니다. 남의 사이트를 점검하거나 구글 API 키 같은 민감한 키를 연결할 때는 권한 요청을 한꺼번에 허용하지 마세요.
- 플러그인을 켜 두면 파일을 고칠 때마다 검사 훅이 돕니다. 웹 프로젝트가 아니어도 모든 프로젝트에서 돌고(저장소의
hooks/hooks.json에서 확인), 수동 설치용 제거 스크립트는 이름이seo-로 시작하는 스킬을 모두 지웁니다. 같은 이름의 내 스킬이 있다면 조심하세요.
7. 개인 의견
막 만든 사이트에서 빠진 것들을 빠짐없이 짚었고, 그 자리에서 고치고 다시 점검하는 흐름이 편했습니다. 두 번 점검하는 데 합쳐 3분, 1달러가 안 들었습니다. 다만 점수는 참고로만 보고, 짚힌 것은 주소를 직접 열어 맞는지 확인하는 게 맞다고 느꼈습니다. 실제로 틀린 지적이 하나 있었으니까요.
점검 점수는 이 글 안에서 바로 올릴 수 있었지만, 실제로 검색을 타고 사람이 들어오는지는 몇 주가 지나야 압니다. 결과는 아직 모르지만, 이 노트가 필요한 분들께 잘 닿기를 바랍니다.
영상으로 보기
출처 · 확인한 날
- github.com/AgriciDaniel/claude-seo — README, 릴리스, 변경 기록, 저장소 정보 (2026.10.22 확인, 읽은 커밋 23a2a81)
- GitHub 이슈 #344 · #348 · #354 · #272 · #177 · #333 · #357 (2026.10.22 확인)
- seo-skill-bench 순위표 — 2026.07.07 판 (2026.10.22 확인)
- Skool AI Marketing Hub Pro 소개 페이지 — 월 $144 표시 (2026.10.22 확인)
- Gen Agent Trust Hub 점검 결과 — 2026.10.05 판정 (2026.10.22 확인)
- claude-seo 소개 영상 댓글 — Shopify canonical 지적 (2026.10.22 확인)