Community코딩 & 개발github.com

schema-implementation

Schema.org 구조화된 데이터를 웹사이트 전반에 구현하기 위한 코딩 스킬입니다. 페이지 유형 분석부터 개발자 준비 완료 티켓(JIRA, Wrike 등) 생성까지 전체 워크플로를 다룹니다.

schema-implementation란 무엇인가요?

이 스킬은 웹사이트에서 Schema.org 구조화된 데이터를 분석, 설계, 구현하고 개발자에게 전달하는 종합적인 방법론을 제공합니다. 브라우저 접근, 웹 검색, 파일 시스템 접근 등 다양한 도구를 활용하여 페이지 유형을 자동으로 발견하고, HTML을 분석하며, 개발자 준비 완료 티켓(상위 티켓 및 하위 티켓)을 생성합니다. 이 스킬은 다국어, 다지역 웹사이트에서 실제 프로젝트를 통해 정제된 5단계 프리 딜리버리(설정, 발견, 스키마 설계, 티켓 생성, 재생성 및 전달)와 2단계 포스트 딜리버리(배포 후 검증, 영향 측정) 프로세스를 정의합니다. Claude는 사용자의 프로젝트 컨텍스트와 피드백을 바탕으로 페이지 유형 발견, HTML 분석, 스키마 설계, 티켓 초안 작성, 최종 재생성 티켓 세트 제공을 수행하며, JIRA, Wrike, Asana 등 다양한 프로젝트 관리 플랫폼을 지원합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rebelytics/schema-implementation/tree/HEAD

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

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

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

문서

Schema.org 구조화된 데이터 구현 — 전체 워크플로 스킬

이 스킬은 웹사이트를 분석하고, Schema.org 마크업을 설계하며, 개발자 준비 완료 티켓을 생성하는 종단간 방법론을 제공합니다. 다국어, 다지역 웹사이트 전반에 걸쳐 구조화된 데이터를 구현하는 실제 프로젝트를 통해 정제되었습니다.

이 방법론은 클라이언트에 구애받지 않습니다. 프로젝트 관리 도구(JIRA, Wrike 등)를 통해 개발자에게 전달하며 포괄적인 Schema.org 적용 범위를 목표로 하는 모든 웹사이트에서 작동합니다.

라이선스: 이 스킬은 Creative Commons Attribution 4.0 International (CC BY 4.0) 라이선스에 따라 배포됩니다. 적절한 저작자 표시를 제공하는 한, 어떤 목적으로든 이 스킬을 자유롭게 공유 및 수정할 수 있습니다.

관련 감사: 이 스킬의 5단계는 라이브 출력물을 2단계에서 설계된 사양과 비교하여 검증합니다. 작업이 로케일 전반에 걸쳐 보고된 수정 사항을 확인하는 경우("모든 언어에서 수정됨", "모든 곳에 배포됨"), JSON-LD 검증 감사를 실행하십시오. 이 감사에는 캐시 무효화 게이트, 사이트맵 인덱스/라이브 hreflang 세트의 인구 조사, 양성 대조군과 같은 이 스킬이 포함하지 않는 클레임 검증 규율이 적용됩니다. 빵 부스러기 작업의 감사 측면은 빵 부스러기 탐색 감사입니다. 이 스킬은 티켓 측면을 처리합니다.


이 스킬의 작동 방식

이것은 프로젝트 스킬로, 일반적으로 대부분의 웹사이트에서 1-2 세션에 걸쳐 1-3시간 안에 완료됩니다. 많은 페이지 유형이 있는 복잡한 다국어 사이트는 더 오래 걸릴 수 있습니다. 이 스킬은 5가지 순차적 전달 단계를 정의합니다: 0단계(설정), 1단계(발견), 2단계(스키마 설계), 3단계(티켓 생성), 4단계(재생성 및 전달) — 이어서 개발자가 배포한 후 실행되는 두 가지 포스트 배포 단계: 5단계(배포 후 검증), 6단계(영향 측정). Claude는 사용자가 현재 어느 단계에 있는지 식별하고 이를 안내해야 합니다.

사용자가 제공: 프로젝트 컨텍스트, 분석 및 티켓 초안에 대한 피드백, 프로젝트별 규칙, 미해결 질문에 대한 답변. Claude가 제공: 페이지 유형 발견, HTML 분석, 스키마 설계, 티켓 초안(상위 + 하위), 최종 재생성된 티켓 세트.

용어 참고: 이 스킬은 "티켓"을 개발자 대상 전달물에 대한 일반적인 용어로 사용합니다. 실제 형식은 0단계에서 선택한 프로젝트 관리 플랫폼(JIRA 티켓, Wrike 작업 등)에 따라 달라집니다.


참조 파일 — 필요 시 로드

1단계부터 6단계는 참조 파일에 있으며, 각 단계마다 하나의 파일이 있습니다. 각 포인터는 트리거를 명명합니다. 이러한 로드는 필수 단계입니다: 단계가 시작되면, 작업을 수행하기 전에 해당 파일을 로드하십시오 — 이 핵심 파일에서 단계를 즉흥적으로 수행하지 마십시오. 단계가 파일을 로드하지 않고 처리된 것을 발견하면, 이를 언급하고 파일을 로드한 후 지금까지 수행된 작업을 다시 확인하십시오.

  • references/discovery.md — 1단계: 페이지 유형 카탈로그, 분류, Google 가이드라인 확인, 페이지 유형별 분석(세 가지 형식의 기존 스키마, 조건부 스키마 분류, 로케일 전달), 실제 데이터 저장, 통합, 분류. 페이지 유형 카탈로그를 구축하고 페이지 유형의 HTML을 분석하기 전에 로드하십시오.
  • references/schema-design.md — 2단계, 섹션 2.1–2.7: 글로벌 및 페이지별 스키마, @id 상호 참조, 폐기 vs 제거, 형식 마이그레이션 처리, 속성 선택 규칙, 다국어 속성 값, 가정 확인, 프로젝트 규칙. 어떤 페이지 유형에 대해 스키마 유형이나 속성을 선택하기 전에 로드하십시오.
  • references/ticket-writing.md — 3단계: 사전 점검, 티켓 템플릿, 서브에이전트 가이드라인, 번호가 매겨진 티켓 작성 규칙(1–46), 상위 티켓, 전달 전 체크리스트, 피드백 워크플로우, 일반적인 스키마 결정(§3.7). 티켓 초안 작성, 수정 또는 확인 전, 서브에이전트에 티켓 관련 브리핑 전, 설계 중 §3.7 결정 사항이 나올 때 로드하십시오.
  • references/delivery.md — 4단계: 재생성 계획, 플랫폼별 형식 지정(Wrike, JIRA, 리치 텍스트 편집기, WAF 보호 도구), 전달 형식 결정 트리, 편집 패스, 티켓 간 일관성 확인, 패키징, Wrike XLS + HTML 붙여넣기. 최종 재생성 전과 대상 도구에 맞게 티켓 형식을 지정하기 전에 로드하십시오.
  • references/post-deployment-verification.md — 5단계: 전체 인구 스윕 트리거, 5단계 사전 점검 체크리스트, 다국어 검증 및 가져오기 기법, 네 가지 발견 범주 및 보고서 템플릿, 후속 주석, URL 및 소스 값 확인, GSC 오류 조정 및 진단, 단일 가져오기 거짓 긍정, 크롤링 내보내기에서 적용 범위 감사. 배포된 스키마를 확인하기 전, 티켓 완료를 확인하기 전, 클라이언트가 보고한 불일치에 응답하기 전, Search Console 구조화된 데이터 오류를 진단하기 전에 로드하십시오.
  • references/measuring-impact.md — 6단계: 검색 결과 표시 분석, 예상 명세서, 측정 가능한 채널, 데이터 보존. 클라이언트가 구조화된 데이터가 달성한 성과를 물을 때, 영향 수치를 가져오기 전에 로드하십시오.

섹션 번호(§1.2, §5.4) 및 규칙 번호(규칙 35, 안티패턴 21)는 모든 파일에서 동일하므로, 이 맵을 통해 상호 참조가 해결됩니다.


0단계: 설정 및 도구

목표: 사용 가능한 도구와 액세스를 평가하고, 가장 효율적인 워크플로를 설정하며, 콘텐츠 작업을 시작하기 전에 프로젝트 수준의 선호도를 수집합니다.

0.1 사용 가능한 도구 평가

분석 작업을 시작하기 전에 어떤 기능을 사용할 수 있는지 확인하십시오:

  • 브라우저 액세스 (예: Chrome 확장 프로그램, Cowork 브라우저 도구의 Claude) — Claude가 페이지를 직접 탐색하고, 렌더링된 HTML을 캡처하고, 데이터를 추출하고, 자율적으로 사실을 확인할 수 있습니다. 이것이 가장 효율적인 워크플로입니다.
  • 웹 검색 — Claude가 브라우저 액세스 없이 사이트 구조를 매핑하고, 사이트맵을 찾고, 페이지 유형을 발견할 수 있습니다.
  • 파일 시스템 액세스 — 분석 문서와 티켓 초안을 점진적으로 저장할 수 있습니다.
  • 직접 사이트 액세스 — 일부 사이트는 자동화된 액세스를 차단합니다(403 오류). 웹 가져오기가 실패하면 브라우저 액세스 또는 수동 HTML 업로드가 대체 방법입니다.

0.2 사용자를 브라우저 액세스로 안내

브라우저 지원 분석은 이 스킬의 기본 권장 워크플로입니다. 이를 통해 Claude는 다음을 수행할 수 있습니다:

  • 페이지 유형을 자율적으로 발견하고 매핑
  • 수동 복사-붙여넣기 없이 모든 페이지에서 렌더링된 HTML 캡처
  • 몇 분 안에 감지 신호, 데이터 소스, 템플릿 구조 추출
  • 티켓을 작성하기 전에 사실 확인(URL 패턴, 언어 변형, 필드 가용성)

브라우저 액세스를 아직 사용할 수 없는 경우, 이점을 설명하고 설정을 안내하십시오. 사용자의 역할은 "HTML 수집자"(지루하고 가치가 낮음)에서 "검토자 및 의사 결정자"(고부가 가치, 도메인 전문 지식이 중요한 역할)로 전환됩니다.

브라우저 액세스를 사용할 수 없거나 사이트가 자동화된 브라우징을 완전히 차단하는 경우, 1.2단계에 설명된 수동 워크플로로 대체하십시오.

비용 인식: 브라우저 액세스는 가장 철저한 분석을 가능하게 하지만 토큰 사용량이 상당히 더 비쌉니다. Chrome 도구 호출은 대규모 페이로드를 반환하며, 대화가 길어질수록 이차적으로 증가합니다. 실시간 페이지 검사가 실제 가치를 더하는 초기 발견 및 검증 단계에 브라우저 워크플로를 예약하십시오. 페이지 유형 목록이 이미 확립된 작업(예: 완료된 감사에서 티켓 작성)의 경우, 브라우저가 아닌 워크플로도 동등하게 효과적이고 훨씬 저렴합니다. 브라우저를 사용할 때는 무거운 호출(read_page 전체 DOM, read_network_requests 전체 트래픽)보다는 목표 지향적인 호출(get_page_text, find, javascript_tool 정밀 추출)을 선호하십시오.

0.3 프로젝트 선호도 수집

콘텐츠 작업을 시작하기 전에 사용자에게 물어보십시오:

  1. 프로젝트 관리 플랫폼 — "이 티켓들은 어떤 시스템에서 생성될까요? (JIRA, Wrike, Asana 등)" 이는 용어(티켓 vs 작업 vs 항목), 형식 제약(Wrike는 목록 항목 내 중첩 코드 블록을 렌더링하지 않음 — references/delivery.md §4.4 플랫폼별 형식 지정 패스 참조) 및 전달 파일 명명 규칙을 결정합니다.
  2. 티켓 구조 — "조직에서 개발자 작업을 위한 확립된 티켓 구조나 템플릿이 있습니까? 있다면 템플릿이나 티켓 생성 가이드라인을 공유해 주십시오. 팀의 관례에 맞게 스키마 티켓을 조정하겠습니다." 템플릿이 없으면 스킬의 기본 구조를 사용하십시오.
  3. 인사말 및 어조 — 예: "안녕하세요 팀," 동료 간 어조 또는 격식 있는 어조.
  4. 프로젝트별 규칙 — 개인정보 보호 제약, 용어, 브랜드 규칙 등 (2단계에서도 수집 가능).

1단계: 발견 및 페이지 유형 카탈로그

목표: 웹사이트의 모든 페이지 유형에 대한 완전한 인벤토리를 구축합니다. 감지 신호, 기존 스키마 적용 범위, 티켓 코드 예제를 위한 저장된 실제 데이터를 포함합니다.

이 단계를 시작하기 전에 references/discovery.md를 로드하십시오. 전체 단계를 포함합니다:

  • 1.1 페이지 유형 목록 수집
  • 1.1b 우선순위 평가/분류
  • 1.1c Google의 현재 가이드라인 확인
  • 1.2 각 페이지 유형 분석
  • 1.3 티켓 코드 예제를 위한 실제 데이터 저장
  • 1.4 발견 사항 문서화
  • 1.5 통합 기회 식별
  • 1.6 각 페이지 유형 분류

2단계: 스키마 설계

목표: 각 페이지 유형에 대해 사용할 스키마 유형과 속성을 결정하고, 스키마가 사이트 전체에서 어떻게 서로 관련되는지 결정합니다.

스키마 유형이나 속성을 선택하기 전에 references/schema-design.md를 로드하십시오. 섹션 2.1–2.7을 포함합니다:

  • 2.1 글로벌/공유 스키마 설계
  • 2.2 페이지별 스키마 설계
  • 2.3 상호 참조 설계
  • 2.4 폐기 vs 제거
  • 2.4b 형식 마이그레이션 티켓 — 기존 형식 처리
  • 2.5 속성 선택 규칙 적용
  • 2.5b 다국어 속성 값
  • 2.6 최종 확정 전 가정 확인
  • 2.7 프로젝트별 규칙

§2.8은 모든 티켓과 모든 검증에 적용되므로 이 핵심 파일에 남아 있습니다:

2.8 범용 기술 요구 사항

이는 모든 프로젝트에 적용됩니다:

  • 스키마는 서버측에서 렌더링되어야 합니다 — 서버에서 반환된 초기 HTML에 존재해야 하며, JavaScript에 의해 동적으로 주입되지 않아야 합니다. 이는 SEO 모범 사례이며 프로젝트별 선호도가 아닙니다.
  • JSON-LD 형식 — 항상 <head> 섹션에서 <script type="application/ld+json">로 구현합니다.
  • 별도의 script 태그 — 각 스키마 유형은 자체 <script> 태그를 받습니다.
  • @context 형식 — 항상 https://schema.org를 사용합니다(후행 슬래시 없음). 모든 티켓에서 일관되게 적용합니다.
  • 실제 JSON 직렬화기를 통해 방출 — CMS 값의 문자열 연결/템플릿으로 JSON-LD를 수동으로 조립하지 마십시오. 수동으로 작성된 JSON-LD는 이스케이프되지 않은 문자만이 아닌 더 광범위한 손상 클래스에 취약합니다. 즉, 보간된 값의 이스케이프되지 않은 따옴표, 스마트/곱슬 따옴표 대체(직선 "이 속하는 위치에 U+201C/U+201D/U+201E), 중괄호 이중/잘못된 배치(예: @id 값이 추가 중괄호 쌍으로 래핑됨) 등이 있습니다. 직렬화기는 전체 클래스를 제거합니다. 이스케이프 규칙만으로는 충분하지 않습니다.
  • 텍스트 값에서 HTML 엔티티 디코딩 — 텍스트 속성은 디코딩된 문자(', &)를 전달하며, CMS 필드나 페이지 소스가 저장하는 HTML 엔티티(&#039;, &amp;)를 절대 전달하지 않습니다. 소스 필드가 인코딩된 텍스트를 보유하는 경우 템플릿은 직렬화하기 전에 디코딩합니다.
  • 날짜는 ISO 8601, 날짜-시간은 시간대 오프셋 포함 — 모든 날짜 및 날짜-시간 속성(datePublished, dateModified, startDate, validFrom …)은 ISO 8601을 사용합니다. 날짜-시간은 오프셋(YYYY-MM-DDThh:mm:ss+hh:mm)을 전달하며, 페이지에서 복사된 로컬 시간이나 표시 형식을 절대 사용하지 않습니다.

3단계: 티켓 생성

목표: 개발자 준비 완료 티켓을 생성합니다 — 공유 스키마용 상위 티켓 하나, 페이지 유형(또는 통합 그룹)당 하위 티켓 하나.

티켓 초안 작성, 수정 또는 확인 전에 references/ticket-writing.md를 로드하십시오. 전체 단계를 포함합니다:

  • 3.1 사전 점검
  • 3.2 티켓 구조 템플릿
  • 3.2b 서브에이전트 사용 가이드라인
  • 3.3 티켓 작성 규칙
  • 3.4 상위 티켓 작성
  • 3.5 전달 전 체크리스트
  • 3.6 피드백 및 반복 워크플로
  • 3.7 일반적인 스키마 결정

4단계: 최종 재생성 및 전달

목표: 모든 축적된 규칙, 결정 및 수정 사항을 적용하여 단일 패스로 모든 티켓을 재생성하고 티켓 간 일관성을 유지합니다.

최종 재생성 패스 전에 references/delivery.md를 로드하십시오. 전체 단계를 포함합니다:

  • 4.1 재생성 계획 수립
  • 4.2 먼저 모든 미해결 질문 해결
  • 4.3 순차적으로 재생성
  • 4.4 플랫폼별 형식 지정 패스
  • 전달 형식 결정 트리
  • 4.5 편집 패스
  • 4.6 티켓 간 일관성 확인
  • 4.7 전달용 패키징
  • 4.8 Wrike 전달 — XLS 스켈레톤 + HTML 붙여넣기

5단계: 배포 후 검증

목표: 개발자가 스키마를 배포한 후 라이브 출력이 사양과 일치하는지 확인합니다. 특히 다국어 적용 범위와 숫자 유형 정확성에 주의를 기울입니다.

배포된 스키마 확인, 티켓 완료 확인 또는 Search Console 오류 진단 전에 references/post-deployment-verification.md를 로드하십시오. 전체 단계를 포함합니다:

  • 단계 서문 — 범위 참고(보고된 수정 사항 확인은 JSON-LD 검증 감사로 이동), 전체 인구 스윕을 위한 두 가지 트리거, 사이트 전체 티켓 템플릿 인벤토리
  • 5단계 사전 점검 체크리스트(보고서 보내기 전)
  • 5.1 다국어 검증 패턴
  • 5.2 감사 결과 범주
  • 5.3 사양 재개방 시점
  • 5.4 URL 검증 — 게시 전 절차
  • 5.5 소스 값 검증 — 미러 감사만으로는 충분하지 않음
  • 5.6 GSC 오류 수와 라이브 크롤 조정
  • 5.7 동적으로 렌더링된 필드의 단일 가져오기 거짓 긍정
  • 5.8 동일 페이지 유형 URL에서 GSC "구문 분석 불가능한 구조화된 데이터 / 잘못된 값 유형" 진단
  • 5.9 크롤링 내보내기에서 적용 범위 감사

6단계: 영향 측정

목표: 구조화된 데이터 구현이 검색 결과 표시 및 트래픽에 미친 영향을 측정합니다.

이 단계를 시작하기 전에 references/measuring-impact.md를 로드하십시오.

  • 6.1 검색 결과 표시 분석
  • 6.2 예상 명세서
  • 6.3 측정 가능한 채널
  • 6.4 데이터 보존

작업 흐름 요약

0단계: 설정 및 도구 결정
    ↓
1단계: 발견 및 페이지 유형 카탈로그 (references/discovery.md 로드)
    ↓
2단계: 스키마 설계 (references/schema-design.md 로드)
    ↓
3단계: 티켓 생성 (references/ticket-writing.md 로드)
    ↓
4단계: 재생성 및 전달 (references/delivery.md 로드)
    ↓ 개발자 배포
5단계: 배포 후 검증 (references/post-deployment-verification.md 로드)
    ↓
6단계: 영향 측정 (references/measuring-impact.md 로드)

관련 스킬