Communitygithub.com

contentful-personalization

Contentful 개인화 기능을 구현, 확장 및 디버깅합니다. 새로운 프로젝트, 전체 프로젝트 또는 알 수 없는 설정에는 '온보딩'을 사용하고, 명시적으로 작동 중인 통합에 대한 범위 작업에는 'extend-existing'을 사용하십시오.

contentful-personalization란 무엇인가요?

이 스킬은 Contentful 개인화(개인화, 최적화, A/B 테스트, 실험, 타겟팅, 세그먼트, 변형 등)를 구현, 확장 및 디버깅하는 구조화된 워크플로우입니다. 컴파일된 CLI 바이너리로 구동되며, JSON 출력을 읽고 'prompt' 필드의 지침을 따라 응답을 전달하는 방식으로 상호작용합니다. MCP 모드(선호)와 CLI 모드(대체)를 지원하며, Claude Code, Codex, Cursor 등 다양한 AI 에이전트 호스트에서 실행될 수 있습니다. 주요 하위 스킬로는 프로젝트 전체에 개인화를 설정하는 'onboard', 라이브 URL에서 런타임 문제를 검사하는 'live-debug', 문제를 진단하고 수정하는 'doctor', 기존 통합을 확장하는 'extend-existing'이 있습니다. 또한 SDK 선택, 미들웨어 패턴, 컴포넌트 패턴, 환경 변수, 분석 등 20개 이상의 참조 주제를 제공하여 개발자가 필요한 정보를 빠르게 찾을 수 있도록 지원합니다.

지원 대상✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add https://github.com/contentful/skills/tree/HEAD/skills/contentful-personalization

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

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

문서

contentful-personalization은(는) 무엇을 하나요?

이 스킬은 컴파일된 CLI 바이너리에 의해 구동되는 구조화된 워크플로우입니다. 바이너리를 호출하고, JSON 출력을 읽고, prompt 필드의 지침을 따라 응답을 전달하는 방식으로 상호작용합니다. 사용자에게 원시 JSON이나 Bash 명령어를 보여주지 마십시오.

이 스킬의 작동 방식

이 스킬은 구조화된 워크플로우 엔진인 skill-kit으로 빌드되었습니다. 각 단계는 XML 태그로 구성된 섹션이 포함된 프롬프트를 제공합니다:

  • <system> — 행동 지침: 페르소나, 어조 또는 제약 사항. 사용자에게 전달할 작업이 아닌, 행동 방침에 대한 지침으로 따르십시오.
  • <prompt> — 작업 지침: 수행할 작업, 고려할 컨텍스트, 생성할 내용.
  • <ask-user> — 사용자에게 질문합니다. 구조화된 선택을 위한 <option> 자식 요소 또는 자유 형식 대화를 위한 type="open"을 포함합니다.
  • <confirm> — 예/아니오 이진 확인. 속성: default, destructive.
  • <plan> — 승인을 위한 계획을 제시합니다. <step> 자식 요소를 포함합니다.
  • <checklist> — 추적된 작업 항목을 생성합니다. 상태가 있는 <item> 자식 요소를 포함합니다.
  • <subagent> — 격리된 하위 에이전트에 작업을 위임합니다. no-recurse가 설정된 경우, 하위 에이전트는 속성에 명명된 스킬을 호출해서는 안 됩니다.
  • <rendered> — 사전 렌더링된 출력. 있는 그대로 내보냅니다 — 편집이나 주석을 추가하지 마십시오.

단계에는 이러한 섹션이 순서대로 하나 이상 포함될 수 있습니다. 순서대로 따르십시오.

스킬 작성자는 이러한 섹션을 구성하여 사용자의 행동을 안내합니다. 태그 및 도구 매핑은 작성자의 의도와 호스트의 기능을 기반으로 SDK에 의해 생성됩니다. 스킬 수준의 시스템 지시문이 전문에 나타날 수 있으며, 단계에 자체 <system> 재정의가 포함되지 않는 한 모든 단계에 적용됩니다.

전문(첫 번째 단계에서 전송됨)에는 각 태그를 사용자 환경에서 사용 가능한 특정 도구에 매핑하는 테이블이 포함되어 있습니다. 워크플로우 전체에서 이를 참조하십시오.

이 스킬을 실행하는 방법

MCP 모드(권장)

이 스킬에 대한 MCP 도구(예: mcp__contentful-personalization__start 및 mcp__contentful-personalization__advance)가 있는 경우 CLI 대신 사용하십시오:

  1. start 도구를 호출합니다(스킬에 필요한 경우 params 포함).
  2. preamble 필드를 읽습니다(첫 번째 호출만). XML 태그를 사용 가능한 도구에 매핑합니다.
  3. prompt 지침을 따릅니다. schema와 일치하는 JSON 객체를 생성합니다.
  4. session, step 및 output과 함께 advance 도구를 호출합니다.
  5. status가 "done"이 될 때까지 3-4단계를 반복합니다.

status: "error"와 함께 retry: true가 표시되면 출력을 수정하고 다시 제출하십시오. 사용자에게 원시 JSON, 세션 ID 또는 MCP 도구 호출을 표시하지 마십시오.

이 섹션의 나머지 부분은 건너뛰십시오 — 아래 CLI 지침은 MCP 도구를 사용할 수 없는 경우에만 필요합니다.

CLI 모드(대체)

이 SKILL.md 파일은 스킬 디렉토리 안에 있습니다. 이 파일의 위치에서 scripts/run의 절대 경로를 확인하십시오(예: /path/to/skill/scripts/run). 모든 Bash 명령어에서 절대 경로를 사용하십시오 — 스킬 디렉토리로 cd하지 마십시오.

아래 예시에서 <skill>/scripts/run은 이 절대 경로의 자리 표시자입니다.

호스트 감지

실행 중인 에이전트 호스트를 확인하여 --host로 전달하십시오:

  • Claude Code: --host claude-code
  • Codex: --host codex
  • OpenCode: --host opencode
  • Gemini CLI: --host gemini-cli
  • Cline: --host cline
  • Roo Code: --host roo-code
  • Kilo Code: --host kilo-code
  • Cursor: --host cursor
  • Amp: --host amp
  • 알 수 없음/기타: 플래그 생략(기본값은 generic)

도구 보고

start 명령어에 사용 가능한 도구를 쉼표로 구분된 --tools 플래그로 전달하십시오. 세션이 이를 기억하므로 advance에서는 --tools를 전달할 필요가 없습니다.

--host가 제공되면 --tools는 호스트의 알려진 도구 레지스트리와 병합됩니다. 즉, 부분 보고가 정상적으로 처리됩니다 — 레지스트리가 생략된 도구를 채워 넣습니다. --tools가 완전히 생략되면 스킬은 --host로부터 도구를 추론합니다. 둘 다 생략되면 모든 상호 작용이 일반 대체를 사용합니다.

하위 에이전트 호출

사용자가 대화하는 최상위 에이전트가 아닌 하위 에이전트(다른 에이전트에 의해 생성됨)인 경우 start 명령어에 --subagent를 추가하십시오. 이는 스킬에 보고된 도구가 진정한 하위 집합임을 알려줍니다 — 스킬은 이를 호스트 레지스트리와 병합하지 않습니다.

--subagent 없이 스킬은 사용자를 최상위 에이전트로 가정하고 도구를 레지스트리와 병합합니다(최상위 에이전트는 종종 도구를 과소 보고하기 때문).

매개변수

이 스킬은 매개변수를 사용하지 않습니다. --params '{}'를 전달하십시오.

1단계: 세션 시작

<skill>/scripts/run --params '{}' --host claude-code --tools <your-tools> --session new 2>/dev/null

이 명령어는 sessionId, file 및 line이 포함된 JSON 포인터를 반환합니다. line 필드는 읽어야 할 줄을 알려줍니다 — 1이 아닌 2가 됩니다(1행은 내부 헤더이며 절대 읽지 마십시오).

file의 line 줄만 읽으십시오. 여기에는 단계 프롬프트, 스키마 및 전문이 포함되어 있습니다.

먼저 preamble을 읽으십시오. 여기에는 사용자 환경에서 사용 가능한 도구에 XML 태그를 매핑하는 테이블이 포함되어 있습니다. 워크플로우 전체에서 이를 참조하십시오.

2단계: 프롬프트 따르기

prompt 필드를 읽으십시오. 여기에는 XML 태그가 지정된 섹션(위의 "이 스킬의 작동 방식"에 설명됨)이 포함되어 있습니다: 따라야 할 <system> 지시문, 실행할 <prompt> 지침 및 전문에 매핑된 도구를 사용하여 실행할 상호 작용 태그(<ask-user>, <confirm>, <plan>, <checklist>, <subagent>). <rendered> 블록이 나타나면 내용을 있는 그대로 내보내십시오.

schema와 일치하는 JSON 객체를 생성하십시오.

3단계: 진행

단계 이름과 함께 출력을 전달하십시오:

<skill>/scripts/run advance --step <step-name> --output '<your-json>' --session abc123 2>/dev/null

이 명령어는 단일 줄 번호(예: 4)를 반환합니다. 세션 파일에서 정확히 그 줄만 읽으십시오 — 여기에는 다음 프롬프트가 포함되어 있습니다. 다른 줄은 읽지 마십시오.

4단계: 완료될 때까지 반복

읽은 줄에 "type":"done"이 포함될 때까지 계속 진행하십시오. finalOutput 필드에는 스킬의 결과가 포함되어 있습니다. 이를 사용자에게 제시하십시오.

중요

  • 사용자에게 원시 JSON 출력이나 Bash 명령어를 절대 표시하지 마십시오. 사용자는 프로토콜이 아닌 자연어 응답을 봅니다.
  • 유효성 검사 오류가 발생하면(응답에 "error": "validation" 또는 "type":"error"가 있음) message 필드를 읽고 출력을 수정한 후 동일한 단계를 다시 시도하십시오.

이 스킬의 단계

  • classify: 사용자의 요청을 아래 범주 중 하나로 분류합니다. 사용자의 메시지만 읽으십시오 — 수행하지 마십시오...
  • gather-context: 사용자의 요청을 분류할 만큼 확신이 없었습니다. 프로젝트를 조용히 탐색하여 수집합니다...
  • pick-topic: (동적)

하위 스킬

이 스킬에는 워크플로우가 자동으로 라우팅하는 하위 스킬이 포함되어 있습니다. 스킬을 정상적으로 시작하십시오 — 디스패처가 사용할 하위 스킬을 결정합니다. 사용자가 특정 하위 스킬 이름을 명시적으로 요청하는 경우에만 직접 하위 스킬에 액세스하십시오.

하위 스킬 단계 이름은 접두사가 붙습니다: <subskill>/<step>(예: doctor/diagnose).

직접 하위 스킬 액세스

<skill>/scripts/run <subskill> --params '<json>' --session new
<skill>/scripts/run <subskill> advance --session <id>

사용 가능한 하위 스킬

  • onboard: Contentful 개인화를 프로젝트 전체에 구현, 설정 또는 활성화하기 위한 기본 워크플로우입니다. 기존 설정 상태를 알 수 없는 경우를 포함합니다. 코드베이스를 탐색하고, 준비 상태를 확인하고, SDK 및 아키텍처를 선택하고, 패키지를 설치하고, 구현하고, 검증합니다. 명시적으로 작동하는 통합에 대한 범위 변경에는 extend-existing를 사용하십시오. — 매개변수: readinessOnly (boolean), userQuery (string)
  • live-debug: Chrome DevTools MCP로 라이브 URL을 검사하여 런타임 개인화 문제를 확인합니다. 콘솔 문제를 확인하고, ninetailed.co 요청을 관찰하고, 다음 단계가 정적 doctor 진단이어야 하는지 보고합니다. — 매개변수: requestedUrl (string)
  • doctor: Contentful 개인화 문제를 진단하고 수정합니다. 먼저 프로그래밍 방식 검사(자격 증명, API 연결, 콘텐츠 상태)를 실행하고, 인프라 문제를 수정한 후에만 코드베이스를 탐색합니다. — 매개변수: userQuery (string)
  • extend-existing: 명시적으로 존재하고 작동하는 Contentful 개인화 통합을 확장합니다. 다른 구성 요소 개인화, 실험 추가, 또는 설치된 SDK에 분석 연결과 같은 범위 변경에만 사용하십시오. 최초, 프로젝트 전체 또는 알 수 없는 상태 구현 요청에는 사용하지 마십시오. 이러한 경우 onboard를 사용하십시오. — 매개변수: userQuery (string)

참조 주제

전체 워크플로우를 실행하지 않고 액세스할 수 있는 빠른 참조 주제:

<skill>/scripts/run topics              # 모든 주제 나열
<skill>/scripts/run topic <name>         # 특정 주제 로드
  • how-personalization-works: 핵심 개념: 콘텐츠 모델, 렌더링 흐름 및 개인화 작동 방식
  • sdk-selection: SDK 결정 프레임워크: 최적화 기본값 vs 레거시 배포 유지 관리
  • provider-patterns: Pages Router, App Router 및 두 SDK에 대한 공급자 배치 패턴
  • middleware-patterns: 미들웨어 및 SSR/에지 패턴: 사전 점검, 쿠키, 매처 구성
  • component-patterns: 컴포넌트 아키텍처 패턴: ContentTypeMap, BlockRenderer, 격리
  • rendering-pipeline: 렌더링 파이프라인: Contentful 클라이언트 설정, 포함 깊이, 컴포넌트 매퍼
  • environment-variables: 환경 변수: 이름, 런타임 매트릭스, 프레임워크 접두사
  • analytics-and-preview: 분석 플러그인(Insights, GTM, Segment) 및 미리보기 구성
  • common-errors: 일반적인 오류 모드와 근본 원인 및 수정 사항
  • ssr-guide: SSR 및 에지 측 개인화: 패턴, 안티 패턴, 문제 해결
  • sdk-legacy-guide: 기존 배포 디버깅 또는 확장을 위한 @ninetailed/experience.js 참조
  • sdk-next-guide: @contentful/optimization SDK 런타임 선택기
  • optimization-overview: @contentful/optimization 런타임 및 패키지 선택기
  • optimization-react-web: @contentful/optimization React Web 공급자, 훅, 항목 및 라우팅
  • optimization-nextjs-app-router: @contentful/optimization Next.js App Router 통합
  • optimization-nextjs-pages-router: @contentful/optimization Next.js Pages Router 통합
  • optimization-web: @contentful/optimization 명령형 브라우저 및 Web Components 통합
  • optimization-node: @contentful/optimization 상태 비저장 Node 요청 통합
  • optimization-react-native: @contentful/optimization React Native 통합
  • contentful-integration-guide: Contentful CMS 통합: 콘텐츠 유형, ExperienceMapper, 게시 워크플로우
  • implementation-examples: 실제 코드 예제: 공급자, BlockRenderer, Experience 컴포넌트 패턴

관련 스킬