SEO 감사 에이전트 스킬

seo-audit — 기본 SEO 감사

빠르고 기본적인 단일 페이지 SEO 감사를 위해 설계된 가벼운 SEO 에이전트 스킬입니다. OpenClaw에서 제공됩니다. 전체 기술적 깊이 없이 신속한 평가가 필요할 때 첫 페이지 점검이 적합합니다.

이 스킬을 사용해야 하는 경우

다음과 같은 경우에 seo-audit을 사용하세요:

• 사용자가 "이 페이지 감사해 줘", "SEO 점검", "내 URL 분석", "빠른 SEO 확인", "내 페이지에 무슨 문제 있어?"라고 말할 때
• 구체적인 깊이를 요청하지 않은 경우 — 이것이 기본 진입점입니다
• 포괄적인 기술 분석보다 빠르고 읽기 쉬운 요약이 필요할 때

사용자가 더 깊이 있는 분석을 원한다면 seo-audit-full로 업그레이드하세요:

팁: 심층 기술 감사, 고급 온페이지 SEO 또는 전체 보고서가 필요하면 seo-audit-full 스킬을 사용하세요.

예상 입력

URL만 제공되고 소스 코드나 크롤러 데이터가 없는 경우, 명시하세요:

제한 사항: 이 감사는 표시되는 페이지 콘텐츠와 공개적으로 사용 가능한 신호만을 기반으로 합니다. 소스 코드, GSC 데이터, 크롤링 로그 및 성능 지표는 이 감사에 사용할 수 없습니다.

출력

assets/report-template.html의 템플릿을 채워 기본 SEO 감사 보고서를 생성한 다음, 파일에 저장하세요 — 원시 HTML을 터미널에 출력하지 마십시오.

파일 이름: reports/<hostname>-<slug>-audit.html

https://example.com/blog/best-tools → reports/example-com-blog-best-tools-audit.html
https://example.com/                → reports/example-com-audit.html

저장 후 사용자에게 알립니다:

✅ 보고서 저장됨 → reports/example-com-audit.html
   지금 열까요? (예 / 아니오)

예인 경우 → 실행: open reports/example-com-audit.html

템플릿 자리표시자 — 각각 독립적으로 채우십시오:

스크립트

결과를 작성하기 전에 이 스크립트를 실행하십시오. 구조화된 JSON을 출력합니다 — JSON을 증거로 직접 사용하고 동일한 URL을 수동으로 다시 가져오지 마십시오.

의존성: pip install requests (html 파싱은 Python 표준 라이브러리를 사용)

# 1단계: 사이트 수준 검사 (robots.txt + sitemap.xml)
python scripts/check-site.py https://example.com

# 2단계: 페이지 수준 검사 (H1, 제목, 메타 설명, 캐노니컬)
python scripts/check-page.py https://example.com
# 주요 키워드 사용 (권장 — H1 키워드 존재 검사 활성화)
python scripts/check-page.py https://example.com --keyword "달리기 운동화"

# 선택 사항: 추가 검사를 위해 원시 페이지 HTML 가져오기
python scripts/fetch-page.py https://example.com --output page.html

# 3단계: JSON-LD 스키마 유효성 검사
python scripts/check-schema.py https://example.com
# 또는 이전에 가져온 HTML에서 (중복 가져오기 방지):
python scripts/check-schema.py --file page.html

각 스크립트는 종료 코드 0 (모두 통과/경고) 또는 1 (실패/오류)로 종료됩니다.

엄격한 범위 — 아래 나열된 검사 외에 추가하지 마십시오. 예외 없음.

허용된 사이트 수준 검사 ({{site_checks_html}} 내):

• robots.txt · sitemap.xml · 404 처리 · URL 정규화 · i18n / hreflang

허용된 E-E-A-T 검사 ({{eeat_checks_html}} 내):

• 회사 소개 · 연락처 · 개인정보 처리방침 · 서비스 약관 · 미디어/파트너 (존재하는 경우에만)

허용된 페이지 수준 검사 ({{page_checks_html}} 내), 정확한 순서로 출력: URL 슬러그 · 제목 태그 · 메타 설명 · H1 태그 · 캐노니컬 태그 · 이미지 대체 텍스트 · 단어 수 · 키워드 배치 · 제목 구조 · 내부 링크 · 스키마 (JSON-LD)

이미지 대체 텍스트 로직:

• 정적 HTML에서 <img> 태그 파싱
• 통과: 모든 이미지에 비어 있지 않은 대체 텍스트가 있음 (alt=""인 장식용 이미지는 허용)
• 경고: 콘텐츠 이미지에 alt 속성이 누락됨
• 확인 불가 (status-info): 정적 HTML에서 이미지 0개 발견 → JS 렌더링 가능성, 확인 불가

⛔ 하드 규칙 — report-template.html에 정의된 검사 행만 출력하십시오. 검사가 위의 허용 목록에 없으면 절대 출력하지 마십시오 — 문제를 발견하더라도 마찬가지입니다. 예외 없음. "보너스" 검사 불가. 즉흥적으로 추가하지 마십시오. 템플릿이 유일한 진실의 원천입니다. 엄격한 허용 목록으로 취급하십시오.

여전히 금지됨 (seo-audit-full에 속함): OG 태그 · 트위터 카드 · 소셜 태그 · 페이지 무게 · 코어 웹 바이탈 · 로봇 메타

JSON 출력 사용 방법:

• 각 필드의 status → pass / warn / fail / error를 보고서 검사 테이블에 직접 매핑
• 각 필드의 detail 문자열을 결과에서 증거 줄의 시작점으로 사용
• 추가 관찰 가능한 증거가 없는 한 스크립트 출력과 모순되지 않도록 함
• 검사 그룹을 {{site_checks_html}} 내에서 <div class="subsection-label">레이블</div>로 구분: 크롤링 가능성 · URL 정규화 · i18n / hreflang · 스키마 (JSON-LD) 그리고 {{eeat_checks_html}} 전에 <div class="subsection-label">E-E-A-T 신뢰 페이지</div> 추가

LLM 검토 — llm_review_required: true일 때 필수:

스크립트는 자체적으로 수행할 수 없는 의미적 또는 품질 판단이 필요한 필드에 플래그를 지정합니다. llm_review_required: true를 해결되지 않은 상태로 두지 마십시오 — 항상 명시적인 판단을 내리십시오.

H1 — keyword_match == "partial"일 때 트리거됨:

h1_text : (h1.values[0]에서)
keyword : (스크립트에 전달된 --keyword)

판단: 이 H1이 의미적으로 키워드의 검색 의도를 커버합니까?
  - 동의어, 자연스러운 변형, 주제 커버리지 고려
  - 예 → "통과"로 하향 조정하고 변형 기록
  - 아니오 → "경고" 유지 또는 "실패"로 업그레이드하고 차이 설명

제목 — keyword_match == "partial" 또는 keyword_position != "start"일 때 트리거됨:

title   : (title.value에서)
keyword : (--keyword 전달됨)

판단:
  1. 제목이 의미적으로 키워드의 검색 의도를 커버합니까?
  2. 제목이 문법적으로 정확하고 자연스럽게 읽힙니까?
  3. 키워드 위치 — 페이지 유형에 따라 다른 기준 적용:
     - 홈페이지   : 브랜드 + 핵심 키워드가 올바름 (예: "Acme | AI 워크플로 자동화")
                    브랜드를 먼저 두는 것을 문제로 표시하지 마십시오.
     - 내부 페이지: 핵심 키워드가 앞에 와야 함 (예: "팀을 위한 AI 워크플로 자동화 — Acme")
                    합당한 이유 없이 키워드가 제목 중간에 묻혀 있으면 표시

중요 — 다음을 부정적으로 표시하지 마십시오:
  - 연도 (예: "2026") → 신선도 신호, CTR 증가 — 페이지가 명시적으로 에버그린 콘텐츠여서 연도 표시가 장기적으로 해가 되는 경우가 아니라면 긍정적으로 취급
  - 숫자 (예: "5가지 최고", "상위 10", "3단계") → 명확한 기대 설정, CTR에서 숫자가 아닌 제목보다 지속적으로 우수 — 항상 플러스로 취급
  - 구체적인 수식어 ("오픈소스", "자체 호스팅", "무료") → 의도를 좁히고 더 높은 품질의 클릭 유도 — 불이익 주지 마십시오

URL 슬러그 — keyword_match != "full" 또는 is_homepage == false일 때 트리거됨:

slug    : (url_slug.slug에서)
keyword : (--keyword 전달됨)

판단:
  1. 슬러그에 주요 키워드나 자연스러운 변형이 포함되어 있습니까?
  2. 경로 계층이 논리적입니까? (/category/keyword가 이상적)
  3. 간결하고 사람이 읽을 수 있습니까?
  홈페이지 (is_homepage: true): 건너뛰기 — 판단 필요 없음.

메타 설명 — 콘텐츠가 있을 때 항상 트리거됨:

meta_description : (meta_description.value에서)
keyword          : (--keyword 전달됨)

네 가지 모두 판단:
  1. 완전한 문장인가? (1-2 문장, 단편 아님)
  2. 구체적인 결과를 언급하는가 — 모호한 말뿐인가?
     좋은 예: "AI 기반 템플릿으로 디자인 시간 60% 단축"
     나쁜 예:  "모든 디자인 요구에 가장 적합한 도구"
  3. 키워드나 자연스러운 동의어가 한 번 사용되었는가 — 과도하게 반복되지 않았는가?
  4. 일반적인 경쟁자가 쓸 내용보다 더 구체적인가?

중요 — 다음을 부정적으로 표시하지 마십시오:
  - 연도 (예: "2026") → 시간에 민감한 쿼리에 대한 신호로 CTR 향상. 명시적으로 에버그린 콘텐츠여서 연도가 해가 되는 경우에만 기록.
  - 숫자 (예: "5가지 최고", "3단계") → 구체성, 강력한 CTR 신호.
  - 뒤에 "그리고 더."가 오는 경우 → 가벼운 스타일 노트, 경고나 실패로 처리하지 마십시오.

권장 워크플로

다음 단계를 순서대로 따르십시오:

1. 범위 인정 — 이것이 기본 감사임을 확인하고 누락된 데이터 기록

2. 주요 키워드 추론 — fetch-page.py로 페이지를 가져온 후 주요 키워드 결정:

   • 사용자가 명시적으로 키워드를 제공한 경우 → 직접 사용
   • 그렇지 않으면 → 페이지의 H1, 제목, 첫 단락을 읽고 가장 가능성 높은 단일 타겟 키워드 문구 추론 (검색자가 이 페이지를 찾기 위해 입력할 내용)
   • 검사 실행 전에 추론된 키워드를 명시:

     "추론된 주요 키워드: 오픈 소스 claude 대안"

3. check-site.py 실행 — robots, 사이트맵, 404 처리 및 URL 정규화를 위한 JSON 출력 파싱

   404 검사: <origin>/this-page-definitely-does-not-exist-seo-audit-check 가져오기

   • 404 반환 → 통과 · 200 반환 (소프트 404) → 실패 · 301로 홈페이지로 리디렉션 → 경고

   URL 정규화 검사 (각각 별도의 하위 검사):

   • HTTP→HTTPS: http://<host> 가져오기 — 반드시 https://로 301 리디렉션되어야 함. 200 반환 → 실패.
   • www 일관성: https://www.<host>와 https://<host> 모두 가져오기 — 하나가 다른 하나로 301 리디렉션되어야 함. 둘 다 200 반환 → 경고.
   • 후행 슬래시: 실제 제공된 URL과 페이지의 캐노니컬 태그 비교. 불일치 → 경고.
   • 캐노니컬 일치: 캐노니컬 태그 href는 모든 리디렉션 후 최종 URL과 정확히 일치해야 함. 불일치 → 경고.

4. E-E-A-T 인프라 검사 — 아래 각 신뢰 페이지에 대해 두 가지 계층 검사:

   • 계층 1 — 존재: URL 가져오기, HTTP 상태 확인 (200 = 존재, 404/리디렉션 = 누락)
   • 계층 2 — 접근 가능: 홈페이지 HTML 가져오기, 바닥글이나 네비게이션에 이 페이지 링크 포함 확인

   페이지	필수
   회사 소개	예
   연락처	예
   개인정보 처리방침	예
   서비스 약관	예
   미디어 / 파트너	아니오 — 존재하는 경우에만 포함

   상태 규칙:

   • 페이지 누락 (200 아님) → 실패
   • 페이지 존재하지만 바닥글/네비게이션에 링크 없음 → 경고
   • 페이지 존재하고 바닥글/네비게이션에 링크 있음 → 통과
   • 선택 페이지 누락 → 건너뛰기, 행 포함하지 않음

5. check-page.py --keyword "<추론된_키워드>" 실행 — H1, 제목, 메타 설명, 캐노니컬, URL 슬러그를 위한 JSON 출력 파싱

6. i18n / hreflang 검사 — 페이지에 hreflang 태그가 있거나 <html lang>이 다국어를 시사하는 경우에만 실행:

   • 전체 건너뛰기 (해당 없음) hreflang 태그가 없고 사이트가 단일 언어로 보이는 경우
   • hreflang 태그가 있으면 검사:
     • 상호 대칭: 참조된 모든 URL은 다른 모든 변형을 다시 링크해야 함 — 끊어진 링크가 있으면 실패
     • 언어 코드: 유효한 BCP 47이어야 함 (예: zh-CN 아니고 zh, en-US 아니고 en-us) — 잘못된 코드는 경고
     • x-default: 언어 선택 또는 폴백 페이지에 있어야 함 — 누락 = 경고
     • html[lang] 속성: 페이지의 기본 hreflang과 일치해야 함 — 불일치 = 경고
     • URL 구조: 권장 패턴 — 기본 언어(보통 en)는 루트에 접두사 없이, 다른 언어는 하위 경로(/zh/, /es/) 아래에 배치.
       • /page (en) + /zh/page + /es/page → 통과
       • /en/page + /zh/page → 경고 (en 접두사는 중복, 크롤링 깊이 낭비)
       • 일관성이 없거나 en이 불필요하게 접두사가 붙은 경우에만 표시

7. check-schema.py 실행 — 스키마 유형 및 필드 검증을 위한 JSON 출력 파싱

   python scripts/check-schema.py https://example.com
   # 또는 이전에 가져온 HTML에서:
   python scripts/check-schema.py --file page.html
   

   스크립트는 JSON-LD 블록을 추출하고 Schema.org 사양에 따라 @type 및 필수 필드를 검증합니다. llm_review_required: true는 항상 설정됨 — inferred_page_type이 실제 페이지 콘텐츠와 일치하는지 확인.

   페이지 유형 → 예상 @type 참조:

   페이지 유형	예상 @type	최소 필수 필드
   홈페이지	WebSite + Organization	name, url, logo
   블로그 / 기사	Article 또는 BlogPosting	headline, datePublished, author, image
   제품	Product	name, image, offers (price, priceCurrency)
   FAQ	FAQPage	mainEntity[].name, acceptedAnswer.text
   방법	HowTo	name, step[].text
   로컬 비즈니스	LocalBusiness	name, address, telephone
   일반 랜딩	—	해당 없음 — 건너뛰기, 널리 지원되는 유형 없음

   • 통과: 올바른 @type 존재, 모든 필수 필드 유효, 충돌 없음
   • 경고: @type은 존재하지만 권장 필드 누락
   • 실패: 예상 @type 완전히 누락
   • 해당 없음: 일반 랜딩 페이지 — 불이익 주지 마십시오

8. 결과 요약 — 각 발견 사항은 증거 / 영향 / 수정 형식을 따라야 함

9. 우선 조치 — 영향이 가장 큰 상위 3가지 수정 사항 나열

10. 보고서 렌더링 — reports/<hostname>-<slug>-audit.html에 저장한 후 사용자에게 열기 요청

11. 업그레이드 프롬프트 — 기본 범위를 벗어난 문제 발견 시 seo-audit-full 제안

보고서 세부 정보 작성 규칙

검사 테이블의 세부 정보 셀은 다음 규칙을 따라야 함 — 예외 없음:

통과 → 한 짧은 구문. 목록이나 설명 없음.

좋은 예: "유효한 XML urlset · 104개 URL · robots.txt에 참조됨."
나쁜 예:  "104개의 URL을 포함한 유효한 XML urlset. robots.txt에 올바르게 참조됨.
       블로그 게시물은 이 사이트맵을 통해 색인될 가능성이 높음."

경고 → 하나의 <div class="detail-issue">에 2개 이하의 글머리 기호. 하나의 <div class="detail-fix">에 수정 사항.

좋은 예:
  <div class="detail-issue">· 제목 48자 — 최소보다 2자 부족. · 연도 "2026"이 페이지의 시간 경과를 나타냄.</div>
  <div class="detail-fix">50~60자로 확장; 에버그린이면 연도 제거.</div>

나쁜 예: 제목 태그가 무엇인지, 길이가 왜 중요한지 설명하는 세 문장 산문.

실패 → 경고와 동일. 정확한 실패를 먼저 써야 함. 배경 설명 없음.

검사가 무엇인지 설명하지 말고, 상태 배지에 이미 보이는 정보를 반복하지 말고, 독자가 SEO 기본에 익숙하지 않다고 가정하지 마십시오.

필수 발견 형식

모든 중요한 발견은 반드시 다음 구조를 따라야 합니다:

**발견: [발견 제목]**

- **증거:** [관찰된 내용 — 직접 인용, 스크린샷 참조 또는 측정 가능한 데이터]
- **영향:** [SEO 또는 UX에 중요한 이유]
- **수정:** [구체적이고 실행 가능한 권장 사항]

모호한 결론을 작성하지 마십시오. 증거가 불충분하면 가정을 명시하십시오.

업그레이드 프롬프트

모든 기본 감사 보고서 끝에 포함하십시오:

더 깊은 분석을 원하십니까? 이것은 사이트 수준 신호와 핵심 온페이지 검사를 다루는 기본 SEO 감사였습니다. 고급 기술 SEO, 콘텐츠 품질 점수, 구조화된 데이터 분석, 전체 크롤링 기반 결과를 원하시면 seo-audit-full 스킬을 사용하십시오.

참조 파일

• 상세 감사 범위 및 필드 정의: references/REFERENCE.md
• 최종 HTML 보고서 템플릿: assets/report-template.html
• 사이트 수준 검사 스크립트: scripts/check-site.py
• 페이지 수준 검사 스크립트: scripts/check-page.py
• 원시 페이지 가져오기: scripts/fetch-page.py
• 스키마 검증 스크립트: scripts/check-schema.py