Communitygithub.com

simpletibr/simplicio-loop-marketing

원샷 부트스트랩 스킬: HyperFrames를 마케팅 엔진 클론에 비디오 제공자(video provider)로 연결합니다. 세 가지 런타임 스킬, 제공자 클래스 + 목, 라우팅 행렬, 환경 변수, CLAUDE.md 업데이트를 자동으로 처리합니다. 멱등적이며, 새 클론에 HyperFrames를 추가하거나 리베이스 후 통합이 끊겼을 때 호출하세요.

simplicio-loop-marketing란 무엇인가요?

이 스킬은 마케팅 엔진 저장소에 HyperFrames를 비디오 제공자로 통합하는 완전 자동화된 워크플로우입니다. 'CLAUDE.md'에 정의된 '새 제공자 추가' 3단계 계약을 한 번의 실행으로 재현하며, 각 단계는 멱등적이어서 이미 통합된 저장소에서 다시 실행해도 변경 사항이 없습니다. Cursor, Claude Code, Codex와 같은 AI 에이전트 플랫폼에서 사용할 수 있으며, 저장소 구조 확인부터 스킬 파일 생성, 제공자 레이어 확장, 라우팅 행렬 업데이트, 환경 변수 설정, CLAUDE.md 문서 업데이트, 최종 검증 및 커밋까지 모든 과정을 자동으로 처리합니다. 특히, 신규 클론 설정, 리베이스 후 누락된 아티팩트 복구, 새로운 클라이언트 요구사항 대응, 신규 운영자 온보딩 등 다양한 상황에서 유용하게 활용할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/install-hyperframes

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

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

문서

HyperFrames 설치

HyperFrames를 비디오 제공자로 추가하는 통합을 한 번에 재현합니다. CLAUDE.md의 3단계 새 제공자 추가 계약을 따릅니다. 존재해야 하는 모든 아티팩트의 자체 완결형 체크리스트이며, 누락된 것만 확인하고 생성합니다.

이 스킬을 처음부터 통합을 다시 유도하는 대신 사용하십시오. 이는 이 저장소에서 "HyperFrames가 연결되었다"는 의미의 표준 기록입니다.

호출 시기

  • HyperFrames 지원이 아직 없는 새 marketing-engine 클론
  • 리베이스 또는 병합으로 아래 아티팩트 중 일부가 누락된 경우(router:check에서 오류 발생, 비디오 라우팅이 타이포그래피 작업에 higgsfield로 대체, 또는 .skills/hyperframes*/ 디렉터리 누락)
  • 새 클라이언트가 프로그래밍 방식의 짧은 동영상/모션 타이포그래피/데이터 시각화 릴을 원하고 매트릭스에 세 가지 작업 종류를 연결해야 하는 경우
  • 세 개의 커밋을 읽는 대신 단일 명령 가능한 플레이북이 필요한 새 운영자를 온보딩하는 경우

입력

  • repo_root: 문자열. marketing-engine 클론의 절대 경로. 기본값은 process.cwd().
  • branch: 문자열, 선택 사항. 커밋할 브랜치. 기본값은 claude/install-hyperframes. 브랜치가 없으면 생성합니다. 절대 main에 커밋하지 않습니다.
  • dry_run: 부울, 선택 사항. true이면 계획된 변경 사항을 출력하고 종료합니다.

프로세스

각 단계를 순서대로 실행합니다. 각 단계는 멱등적입니다. 이미 통합된 저장소에서 다시 실행해도 아무런 변경이 없습니다.

1단계 — 사전 점검

  1. repo_root에 ## How to Add a New Provider 줄이 포함된 CLAUDE.md가 있는지 확인합니다. 없으면 실행을 거부합니다—이는 marketing-engine 저장소가 아닙니다.
  2. lib/providers/video.ts, lib/providers/matrix.ts, lib/providers/types.ts, lib/providers/__mocks__/video.ts 파일이 모두 존재하는지 확인합니다. 하나라도 없으면 실행을 거부합니다.
  3. 활성 브랜치가 main이 아닌지 확인합니다. main인 경우 먼저 branch를 생성하고 체크아웃합니다.

2단계 — 세 가지 런타임 스킬 추가

다음 세 개의 디렉터리를 SKILL.md 파일과 함께 생성합니다. 각 파일은 이미 트리 내 표준 버전으로 존재합니다. 아래 참조 아티팩트 세트 섹션에서 그대로 복사하십시오. 파일이 이미 존재하고 프론트매터 name이 일치하면 건너뜁니다.

  • .skills/hyperframes/SKILL.md — 컴포지션 작성 규칙(애니메이션 전 레이아웃, 타임라인 일시 중지 및 window.__timelines에 등록, Math.random()/시간 기반 로직 금지, data-composition-variables를 통해 변수 선언).
  • .skills/hyperframes-cli/SKILL.md — npx hyperframes lint → inspect → render 개발 루프. 항상 --strict --strict-variables로 렌더링합니다.
  • .skills/hyperframes-prompt-builder/SKILL.md — 매트릭스가 hyperframes로 해석될 때 video-prompt-builder가 호출하는 전문가; clients/<slug>/design.md에서 브랜드 토큰을 로드하고, task_kind별 템플릿을 선택한 후 컴포지션 스펙과 렌더 인자를 반환합니다.

3단계 — 디스패처 스킬 업데이트

.skills/video-prompt-builder/SKILL.md에서:

  1. hyperframes-prompt-builder를 시작 단락과 관련 스킬 섹션의 전문가 목록에 추가합니다.
  2. task_kind 입력 열거형에 motion_typography, data_viz_reel, programmatic_short를 추가합니다.
  3. 환경 변수를 확인하는 프로세스 단계에서 HYPERFRAMES_ACTIVE를 목록에 추가합니다.
  4. 제공자→전문가 매핑에 Hyperframes -> hyperframes-prompt-builder 행을 추가합니다.
  5. 예제 추가: Hyperframes로 라우팅되고 task_kind: programmatic_short인 주간 KPI 릴.

대상 문자열이 이미 존재하는 하위 단계는 건너뜁니다.

4단계 — 제공자 레이어 확장

lib/providers/types.ts에서 VideoTask 유니온에 세 멤버를 추가합니다:

| "motion-typography"
| "data-viz-reel"
| "programmatic-short"

lib/providers/matrix.ts에서:

  • EMBEDDED_DEFAULTS.video에 세 개의 행을 추가합니다: motion-typography, data-viz-reel, programmatic-short — 각각 기본값은 hyperframes입니다.
  • TASK_LABEL_MAP에 레이블 별칭을 추가합니다: "motion typography", "kinetic typography", "data viz reel", "data-viz reel", "programmatic short", "parametrized short".

lib/providers/video.ts에서:

  • RealVideoBase를 확장하고 process.env.HYPERFRAMES_ACTIVE === "true"에서 게이트되는 HyperframesVideoProvider 클래스를 추가합니다. realGenerate에서 기존 higgsfield/topview 스텁 패턴과 일치하게 "로컬 CLI 렌더가 호출자 컨텍스트에서 필요합니다. 스텁" 오류를 던집니다.
  • REAL_VIDEO_REGISTRY에 hyperframes: () => new HyperframesVideoProvider()를 등록합니다.

lib/providers/__mocks__/video.ts에서:

  • BaseMockVideo를 확장하고 name = "hyperframes"인 MockHyperframesVideoProvider를 추가합니다.
  • MOCK_VIDEO_REGISTRY에 hyperframes: () => new MockHyperframesVideoProvider()를 등록합니다.

5단계 — 라우팅 매트릭스 파일 업데이트

.specs/architecture/PROVIDERS.md에서 비디오 라우팅 테이블에 세 행을 추가합니다:

| Motion typography | hyperframes | HTML/GSAP 동적 타이포그래피, 브랜드 충실, 결정론적 |
| Data viz reel | hyperframes | 선언된 변수 → 재렌더링 가능한 차트 (NYT 스타일) |
| Programmatic short | hyperframes | 매개변수화된 HTML 컴포지션; 바이트 동일 재렌더링 |

6단계 — .env.example 업데이트

WAVESPEED_API_KEY= 뒤에 다음을 추가합니다:

# HyperFrames는 로컬 HTML→MP4 렌더러입니다. API 키가 필요하지 않습니다.
# 로컬에서 `npx hyperframes doctor`가 통과하면 HYPERFRAMES_ACTIVE=true로 설정하십시오.
# (Node >= 22, PATH에 FFmpeg 필요). https://github.com/wesleysimplicio/hyperframes 참조
HYPERFRAMES_ACTIVE=false

7단계 — CLAUDE.md 업데이트

  1. 스택 테이블에서 Video 행의 제공자 셀에 hyperframes (로컬 HTML→MP4)를 포함하도록 변경합니다.
  2. 사용 가능한 스킬에서 wavespeed-batch 뒤에 세 줄을 삽입합니다:
    • hyperframes — HTML을 진실 공급원으로 사용하는 모션 컴포지션 제작.
    • hyperframes-cli — npx hyperframes lint/inspect/preview/render를 실행합니다.
    • hyperframes-prompt-builder — 매트릭스가 hyperframes로 해석될 때 video-prompt-builder가 선택합니다.

8단계 — 검증

  1. 아래 테스트를 통해 .specs/architecture/PROVIDERS.md를 파싱하고 motion-typography, data-viz-reel, programmatic-short가 모두 hyperframes로 해석되는지 확인합니다.
  2. npm run typecheck 실행 — 변경 사항과 관련 없는 기존 실패(예: @types/node 누락)는 수용합니다. 제공자 레이어를 참조하는 새로운 TS 오류가 있으면 실패합니다.
  3. 저장소에 .env가 있으면 npm run router:check 실행; 그렇지 않으면 건너뜁니다(스크립트는 .env를 요구하며 통합 형태와 무관합니다).
  4. git status가 예상 파일만 표시하는지 확인합니다.
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
  if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
    console.error('MISSING:', key); process.exit(1);
  }
}
console.log('PROVIDERS.md OK');
"

9단계 — 커밋 및 푸시

  1. 이 스킬이 건드린 파일만 정확히 스테이징합니다. 절대 git add -A 하지 마십시오.
  2. 표준 메시지로 커밋합니다:
    feat(skills): wire HyperFrames as a video provider
    
    그리고 3단계 계약 실행을 설명하는 본문을 추가합니다(병합된 참조 커밋의 문구 참조).
  3. origin <branch>에 푸시합니다. 브랜치에 PR이 없으면 초안 PR을 엽니다.

출력

  • branch: 문자열. 커밋을 보유한 브랜치.
  • pr_url: 문자열. 생성되었거나 이미 존재하는 초안 PR URL.
  • files_written: 실제 생성되거나 수정된 상대 경로 배열.
  • files_skipped_idempotent: 이미 올바른 상대 경로 배열.
  • verification: { providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }.

불가침 규칙

  • 멱등적. 이미 통합된 저장소에서 다시 실행하면 파일을 전혀 건드리지 않습니다.
  • 절대 main에 커밋하지 않습니다. 먼저 기능 브랜치를 생성하십시오. 엔진의 브랜치 정책은 상위에서 적용됩니다.
  • 스킬 본문은 계약 외부에서 hyperframes를 언급하지 않습니다. 제공자 선택은 여전히 PROVIDERS.md + lib/router.ts를 통해 이루어집니다. 이 스킬은 부트스트랩입니다. 런타임 선택은 제공자에 무관합니다.
  • 렌더링된 MP4 또는 outputs/ 아래의 파일을 편집하지 마십시오. 이 스킬은 엔진 배관만 변경합니다.
  • 기존 compliance-<활성 클라이언트> 스킬 또는 클라이언트별 아티팩트를 절대 삭제하지 마십시오. 통합은 추가적입니다.

실패 모드

  • 1단계 사전 점검 실패(marketing-engine 저장소 아님): 누락된 파일을 표시하고 중지합니다. "수정"하려고 시도하지 마십시오.
  • 파일이 이미 충돌하는 내용으로 존재하는 경우(예: .skills/hyperframes/SKILL.md가 수동 편집됨): 표준 내용과 비교하여 차이점을 표시하고, 덮어쓰기 전에 운영자에게 문의합니다.
  • npm run typecheck가 lib/providers/에 새로운 TS 오류를 보고하는 경우: 중지하고 오류를 표시하며 커밋하지 않습니다.
  • git push가 네트워크 이외의 이유로 실패하는 경우: 중지합니다. 네트워크 실패는 프로젝트의 git 정책(2초, 4초, 8초, 16초 백오프, 최대 4회 시도)에 따라 재시도됩니다.

관련 스킬

  • hyperframes: 런타임 제작(이 스킬에 의해 2단계에서 설치됨).
  • hyperframes-cli: 런타임 lint/inspect/render(이 스킬에 의해 2단계에서 설치됨).
  • hyperframes-prompt-builder: 런타임 전문가(이 스킬에 의해 2단계에서 설치됨).
  • video-prompt-builder: 이 스킬에 의해 3단계에서 업데이트되는 디스패처.
  • llm-router: 관련 없음. LLM 제공자 라우팅은 별도의 디스패처입니다.

참조 아티팩트 세트

이 스킬이 쓰는 모든 파일의 표준 내용은 main의 병합된 커밋에 있습니다:

  • 스킬: .skills/hyperframes/SKILL.md, .skills/hyperframes-cli/SKILL.md, .skills/hyperframes-prompt-builder/SKILL.md
  • 제공자 레이어: lib/providers/types.ts, lib/providers/matrix.ts, lib/providers/video.ts, lib/providers/__mocks__/video.ts
  • 라우팅 매트릭스: .specs/architecture/PROVIDERS.md
  • 환경: .env.example
  • 헌장: CLAUDE.md

의심스러우면 병합된 참조 커밋의 origin/main과 비교하고 표준 버전을 그대로 복사하십시오. 기억에 의존하여 다시 입력하지 마십시오.

상위 참조

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬