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 대신 사용하십시오:
start도구를 호출합니다(스킬에 필요한 경우params포함).preamble필드를 읽습니다(첫 번째 호출만). XML 태그를 사용 가능한 도구에 매핑합니다.prompt지침을 따릅니다.schema와 일치하는 JSON 객체를 생성합니다.session,step및output과 함께advance도구를 호출합니다.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 컴포넌트 패턴