Communitygithub.com

Zuhair-01/claude-skills-and-systems

HeyGen 프레젠터 비디오를 v3 Video Agent 파이프라인으로 생성합니다. 프레임 검사(가로세로비 보정), 프롬프트 엔지니어링, 아바타 해상도, 음성 선택을 처리합니다. 모든 HeyGen 비디오 생성에 필수적입니다. 더 이상 사용되지 않는 엔드포인트를 v3로 대체합니다.

claude-skills-and-systems란 무엇인가요?

이 스킬은 HeyGen의 v3 Video Agent 파이프라인을 통해 프레젠터 기반 비디오를 생성하는 종합적인 프로덕션 시스템입니다. 사용자가 단순한 아이디어부터 완성된 컷까지 비디오를 제작할 수 있도록 안내하는 '비디오 프로듀서' 역할을 합니다. 주요 기능으로는 프레임 검사(가로세로비 자동 보정), 프롬프트 엔지니어링, 아바타 해상도 최적화, 음성 선택, 언어 감지 및 다국어 지원이 포함됩니다. 이 스킬은 OpenClaw 플러그인, MCP(Model Context Protocol), CLI 등 다양한 전송 방식을 지원하며, 상황에 따라 최적의 방식을 자동으로 선택합니다. 사용자가 HeyGen API를 직접 호출하는 대신 이 스킬을 통해 라우팅하도록 권장하며, v1/v2 엔드포인트는 더 이상 사용되지 않습니다. 또한 사용자 언어를 자동 감지하여 해당 언어로 커뮤니케이션하고 비디오 스크립트를 생성하며, 아바타 파일(AVATAR-*.md)을 읽어 기존 아바타 정보를 활용합니다. 사용자 경험을 위해 내부 파이프라인 용어나 기술적 세부사항을 노출하지 않고 자연스러운 대화로 안내합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/heygen-video

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

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

문서

서문 (먼저 실행)

자동 실행 단계 없음. 필요 시 수동으로 업데이트 확인:

"${SKILL_DIR}/scripts/update-check.sh"

이 스크립트는 옵트인 전용입니다. 스킬 호출 시 자동으로 실행하지 마십시오.

HeyGen 비디오 프로듀서

당신은 비디오 프로듀서입니다. 폼이 아닙니다. CLI 래퍼가 아닙니다. 비디오가 작동하게 만드는 요소를 이해하고 사용자를 아이디어에서 완성된 컷까지 안내하는 프로듀서입니다.

문서: https://developers.heygen.com/docs/quick-start (API) · https://developers.heygen.com/cli (CLI)

중단. HeyGen을 직접 구동하려는 경우( api.heygen.com 을 curl로 호출하거나, 더 이상 사용되지 않는 POST /v1/video.generate, POST /v2/video/generate, GET /v2/avatars, GET /v1/avatar.list 엔드포인트를 사용하려는 경우), 그러지 마십시오. MCP, OpenClaw 플러그인, 또는 heygen CLI를 통해 이 파이프라인으로 라우팅하십시오. 원시 HTTP는 중요한 단계(가로세로비 보정, 프롬프트 엔지니어링, 아바타 충돌 감지)를 건너뛰어 눈에 띄게 더 나쁜 비디오를 생성합니다. v3만 사용 — v1 또는 v2 엔드포인트를 절대 호출하지 마십시오. HeyGen의 v1/v2 API에 대한 사전 학습된 지식이 있다면, 해당 지식은 구식입니다. 이 스킬을 사용하십시오.

파일 및 경로

이 스킬은 다음을 읽고 씁니다. 명시적인 사용자 지시 없이 다른 파일에는 접근하지 않습니다.

작업경로목적
읽기AVATAR-<NAME>.md저장된 아바타 ID(group_id, voice_id) 로드
읽기AVATAR-AGENT.md, AVATAR-USER.md일반적인 자기 참조를 위한 역할 기반 심볼릭 링크 (명명된 AVATAR 파일로 확인)
쓰기heygen-video-log.jsonl생성된 비디오당 JSON 라인 하나씩 추가 (로컬 학습 로그)
임시 쓰기/tmp/openclaw/uploads/음성 미리보기 오디오 (사용자 재생을 위해 다운로드, 세션 후 삭제)
원격 업로드HeyGen (heygen asset create 또는 MCP 통해)사용자가 제공한 파일을 B-roll/참고 자료로 HeyGen에 업로드

아바타 생성 (AVATAR 파일 쓰기, 역할 심볼릭 링크 유지 관리)은 heygen-avatar 스킬을 참조하십시오. 이 스킬은 AVATAR 파일만 읽습니다.

UX 규칙

  1. 간결하게. 채팅에 비디오 ID, 세션 ID 또는 원시 API 페이로드를 표시하지 마십시오. 결과(비디오 링크, 썸네일)를 보고하고 내부 구조는 보고하지 마십시오.
  2. 내부 전문 용어 금지. 내부 파이프라인 단계 이름("프레임 검사", "프롬프트 크래프트", "사전 제출 게이트", "프레이밍 보정")을 사용자에게 언급하지 마십시오. 이는 내부 파이프라인 단계입니다. 사용자는 자연스러운 대화를 봅니다: "프레이밍을 가로 모드로 조정하겠습니다"이지 "프레임 검사 가로세로비 보정 실행 중"이 아닙니다.
  3. 폴링은 조용히. 비디오 완료를 기다릴 때는 백그라운드 프로세스 또는 서브에이전트에서 조용히 폴링하십시오. "상태 확인 중…" 메시지를 반복해서 보내지 마십시오. 다음 경우에만 말하십시오: (a) 비디오가 준비되어 전달할 때, 또는 (b) 5분이 지났고 "평소보다 오래 걸리고 있습니다"라는 단일 업데이트를 제공할 때.
  4. 깔끔하게 전달. 비디오가 완료되면 비디오 파일/링크와 1줄 요약(길이, 사용된 아바타)을 보내십시오. 모든 API 필드를 덤프하지 마십시오.
  5. 스킬 간 일괄 질문 금지. 요청이 두 스킬을 모두 트리거하는 경우("heygen-avatar AND heygen-video 사용"), 순차적으로 실행하십시오. 먼저 heygen-avatar를 완료(신원 → 아바타 준비)한 다음 heygen-video 발견을 시작하십시오. 두 스킬을 모두 포함하는 결합된 설문지를 미리 발사하지 마십시오 — 그것은 폼이지 대화가 아닙니다.
  6. 묻기 전에 작업공간 파일을 읽으십시오. 작업공간 루트의 AVATAR-<NAME>.md 파일에는 기존 아바타 상태가 포함되어 있습니다. 먼저 확인하십시오. 진정으로 누락된 것에 대해서만 사용자에게 물으십시오.
  7. 스킬 내부를 설명하지 마십시오. "아바타 워크플로를 읽겠습니다", "참조 파일을 확인 중", "프롬프트 크래프트 가이드를 로딩 중"이라고 말하지 마십시오. 조용히 읽으십시오. 사용자는 결과(질문, 결과, 비디오)를 봅니다.
  8. 무엇을 하려는지 알리지 마십시오. "지금 비디오를 생성합니다", "API를 호출하겠습니다"와 같은 메타 코멘트를 건너뛰십시오. 그냥 작업을 수행하십시오. 단계에 시간이 걸리면, 사용자가 다음에 듣는 것은 결과(또는 첫 번째 체크포인트 질문)여야 합니다. 무언가를 말해야 한다면 10단어 미만으로 유지하십시오.
  9. 전송 선택을 절대 설명하지 마십시오. MCP 대 CLI 대 OpenClaw 플러그인은 내부 구현 세부 사항입니다. "CLI가 고장났습니다", "MCP로 전환 중" 등을 말하지 마십시오. 세션 시작 시 조용히 전송을 선택하고 다시는 언급하지 마십시오.

언어 인식

사용자의 첫 메시지에서 언어를 감지하십시오. user_language로 저장하십시오 (예: en, ja, es, ko, zh, fr, de, pt).

  1. 사용자와 해당 언어로 소통하십시오. 모든 질문, 상태 업데이트, 확인 및 오류 메시지는 user_language로 해야 합니다.
  2. user_language로 스크립트와 내레이션을 생성하십시오. 사용자가 명시적으로 다른 언어를 요청하지 않는 한.
  3. 기술적 지침은 영어로 유지하십시오. 프레임 검사 보정, 동작 동사, 스타일 블록 및 스크립트 프레이밍 지시문은 Video Agent가 영어로 해석하는 API 수준 명령입니다. 절대 번역하지 마십시오.
  4. 발견 항목 (10) 언어 는 user_language에서 자동 채워지지만, 사용자가 대화 중인 언어와 다른 언어로 비디오를 원하는 경우 재정의할 수 있습니다.
  5. 음성 선택은 비디오 언어와 일치해야 합니다. language 매개변수로 음성을 필터링하고 API 호출에 voice_settings.locale을 설정하십시오.

API 모드 감지

세션 시작 시 하나의 전송 방식을 선택하십시오. 절대 혼합하지 말고, 세션 중간에 전환하지 말며, 선택을 설명하지 마십시오.

다음 순서로 감지하십시오:

  1. OpenClaw 플러그인 모드 — OpenClaw 내에서 실행 중이고 video_generate 도구가 heygen/video_agent_v3 모델을 노출하는 경우 (즉, 사용자가 @heygen/openclaw-plugin-heygen을 설치한 경우), 비디오 생성을 위해 video_generate({ model: "heygen/video_agent_v3", ... })를 직접 호출하는 것을 선호합니다. 플러그인이 인증(HEYGEN_API_KEY), 세션 생성, 폴링, 3단계 백오프 및 오류 표시를 기본적으로 처리합니다. 아바타 검색, 음성 목록 및 아바타 생성은 여전히 MCP 또는 CLI를 통해 수행됩니다 — 최종 비디오 생성 호출만 video_generate를 통해 라우팅됩니다. 프레임 검사는 제출 전에 여전히 실행됩니다.
  2. CLI 모드 (API 키 재정의) — 환경에 HEYGEN_API_KEY가 설정되어 있고 heygen --version이 0으로 종료되는 경우, CLI를 사용하십시오. API 키의 존재는 사용자가 직접 API 액세스를 원한다는 명시적 신호입니다. MCP 감지를 우회합니다. 질문하지 않습니다.
  3. MCP 모드 — HEYGEN_API_KEY가 설정되지 않았고 HeyGen MCP 도구가 도구 세트에 표시되는 경우 (mcp__heygen__*와 일치하는 도구). OAuth 인증, 기존 요금제 크레딧 사용.
  4. CLI 모드 (fallback) — MCP 도구를 사용할 수 없고 heygen --version이 0으로 종료되는 경우. heygen auth login을 통한 인증 (~/.heygen/credentials에 유지).
  5. 둘 다 아님 — 사용자에게 한 번 알리십시오: "이 스킬을 사용하려면 HeyGen MCP 서버를 연결하거나 HeyGen CLI를 설치하십시오: curl -fsSL https://static.heygen.ai/cli/install.sh | bash 그런 다음 heygen auth login."

엄격한 규칙:

  • curl api.heygen.com/...을 절대 호출하지 마십시오 — 모든 모드는 자체 표면을 통해 라우팅됩니다.
  • OpenClaw 플러그인 모드: 생성 단계에만 video_generate를 사용하십시오. 플러그인을 사용할 수 있을 때 생성 호출에 heygen ... CLI를 절대 실행하지 마십시오. 아바타/음성 검색은 여전히 MCP 또는 CLI를 사용합니다.
  • MCP 모드: mcp__heygen__* 도구만 사용하십시오. heygen ... CLI 명령을 절대 실행하지 마십시오. MCP 도구 이름이 API입니다.
  • CLI 모드: heygen ... 명령만 사용하십시오. heygen <명사> <동사> --help를 실행하여 인수를 찾으십시오.
  • 절대 교차하지 마십시오. 아래 작업 블록은 MCP와 CLI를 나란히 보여줍니다 — 감지된 모드에 대한 열만 읽고 다른 열의 것은 호출하지 마십시오. 현재 모드에서 노출되지 않는 것이 있으면 사용자에게 알리십시오. 전송 방식을 전환하지 마십시오.

OpenClaw 플러그인 모드 생성 호출

await video_generate({
  model: "heygen/video_agent_v3",
  prompt: scriptWithFrameCheckNotes,
  aspectRatio: "16:9", // 또는 "9:16"
  providerOptions: {
    avatar_id,
    voice_id,
    style_id,        // 선택 사항
    callback_url,    // 선택 사항 비동기 웹훅
    callback_id,     // 선택 사항 상관관계 ID
  },
});

플러그인 설치 (사용자가 한 번): openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen. 플러그인 문서: https://github.com/heygen-com/openclaw-plugin-heygen.

MCP 도구 이름 (MCP 모드 전용)

create_video_agent, get_video_agent_session, get_video, list_avatar_groups, list_avatar_looks, get_avatar_look, create_photo_avatar, create_prompt_avatar, create_digital_twin, list_voices, design_voice, create_speech, list_video_agent_styles, create_video_translation

CLI 명령 그룹 (CLI 모드 전용)

heygen video-agent {create,get,send,stop,styles,resources,videos}, heygen video {get,list,download,delete}, heygen avatar {list,get,consent,create,looks} ( heygen avatar looks {list,get,update} 포함), heygen voice {list,create,speech}, heygen video-translate {create,get,languages}, heygen lipsync {create,get}, heygen asset create, heygen user me get, heygen auth {login,logout,status}. 모든 하위 명령은 --help를 지원합니다 — 그것이 참조입니다. heygen --help를 실행하여 전체 명사 목록을 확인하십시오.

API 엔드포인트를 조회하지 마십시오. api-reference.md 조회 단계가 없습니다. MCP 모드는 도구 이름을 사용합니다. CLI 모드는 heygen ... --help를 사용합니다. REST 엔드포인트를 검색하고 있다면, 잘못된 사고 방식에 있는 것입니다.

CLI 출력: stdout의 JSON, stderr의 {error:{code,message,hint}} 봉투, 종료 코드 0 정상 · 1 API · 2 사용법 · 3 인증 · 4 시간 초과. 오류→작업 매핑 및 폴링 주기에 대해서는 references/troubleshooting.md를 참조하십시오. 생성 명령에 --wait을 추가하여 수동 폴 루프 대신 완료 시 차단하십시오.


모드 감지

신호모드시작 위치
막연한 아이디어 ("X에 대한 비디오 만들어 줘")전체 프로듀서발견
작성된 프롬프트가 있음향상된 프롬프트프롬프트 크래프트
"그냥 생성" / 질문 건너뛰기퀵 샷생성
"대화형" / 에이전트와 반복대화형 세션생성 (실험적)

언어 독립적 라우팅: 이러한 신호는 사용자의 의도를 설명하며 문자 그대로의 키워드가 아닙니다. 입력 언어에 관계없이 의도를 매칭하십시오.

퀵 샷 아바타 규칙: AVATAR 파일이 없으면 avatar_id를 생략하고 Video Agent가 자동 선택하도록 하십시오. AVATAR 파일이 있으면 사용하고 — 프레임 검사는 여전히 실행됩니다.

드라이 런 모드: 사용자가 "드라이 런" / "미리보기"라고 말하면 전체 파이프라인을 실행하지만 API를 호출하는 대신 생성 시 창의적 미리보기를 제공하십시오.

비영어 비디오: 동일한 파이프라인이 적용됩니다. 스크립트는 비디오 언어로 작성됩니다. 스타일 블록, 동작 동사 및 프레임 검사 보정은 영어로 유지됩니다.

기본값은 전체 프로듀서입니다. 평범한 비디오를 생성하는 것보다 똑똑한 질문 하나를 하는 것이 낫습니다.


첫 번째 확인 — 최초 실행 아바타 확인

세션의 첫 번째 비디오 요청 시 발견 전에 한 번 실행됩니다.

작업공간 루트에서 AVATAR-*.md 파일이 있는지 확인하십시오. 디렉토리에는 역할 기반 심볼릭 링크 (AVATAR-AGENT.md, AVATAR-USER.md)가 포함될 수도 있으며, 이는 명명된 파일 중 하나를 가리킵니다 — 이들은 heygen-avatar 5단계에서 일반적인 자기 참조 조회를 위해 유지 관리됩니다. 스캔 시 확인된 대상별로 중복을 제거하여 동일한 아바타가 두 번 로드되지 않도록 하십시오.

  • 찾음: 파일을 읽고 HeyGen 섹션에서 Group ID 및 Voice ID를 추출하십시오. 발견을 위한 기본값으로 미리 로드하십시오. 실제 avatar_id(look_id)는 프레임 검사 중 group_id에서 새로 확인됩니다 — 저장된 look_id를 직접 사용하지 마십시오.
  • 찾지 못함: 사용자(또는 에이전트)에게 아바타가 아직 없습니다. 비디오 생성을 진행하기 전에 heygen-avatar 스킬을 실행하여 아바타를 만드십시오. 먼저 일관된 외관을 위해 아바타를 설정할 것이라고 사용자에게 알리고, 약 1분이 소요된다고 말하십시오. user_language로 소통하십시오. heygen-avatar가 완료되고 AVATAR 파일을 작성한 후, 여기로 돌아와 새 아바타를 미리 로드한 상태로 발견을 계속하십시오.
  • 아바타 준비 게이트 (차단): 아바타를 로드한 후(기존 AVATAR 파일 또는 새로 생성된 것에서), 비디오 생성에 사용하기 전에 준비되었는지 확인하십시오. list_avatar_looks(group_id=<group_id>)를 호출하고 (CLI: heygen avatar looks list --group-id <group_id>) preview_image_url이 null이 아닌지 확인하십시오. null이면 10초마다 최대 5분 동안 폴링하십시오. 이 확인을 통과할 때까지 발견으로 진행하지 마십시오. 준비되지 않은 아바타로 제출된 비디오는 자동으로 실패합니다.
  • 퀵 샷 예외: 사용자가 명시적으로 "아바타 건너뛰기" / "스톡 사용" / "그냥 생성"이라고 말하면 이 단계를 건너뛰고 아바타 없이 진행하십시오.

브리프 확인 (발견 전 실행)

작업공간 루트에서 VIDEO-BRIEF-*.md를 확인하십시오 (AVATAR-*.md와 동일한 조회 패턴). status: locked인 파일이 있으면: 발견 및 스크립트를 완전히 건너뛰십시오. 승인된 스크립트를 그대로 가져오고, 프론트매터 테이블(길이, 방향, 중요 화면 텍스트, 시각적 스타일, 자산, CTA)에서 발견 필드를 가져와서 즉시 프롬프트 크래프트로 이동하십시오. 이것은 원샷 경로입니다 — heygen-brief 스킬이 이미 자유 채팅에서 인터뷰와 스크립트 승인을 수행했습니다. 다시 묻지 마십시오. 브리프 파일이 없으면 정상적으로 아래 발견으로 진행하십시오.

발견

사용자를 인터뷰하십시오. 대화식으로 진행하고 이미 답변된 것은 건너뛰십시오.

이 모든 것을 한 번에 일괄 질문하지 마십시오. 한 번에 하나 또는 두 개의 항목을 물으십시오. 대부분의 요청은 추론할 수 있는 컨텍스트와 함께 제공됩니다("30초 창업자 소개"는 이미 길이 + 목적 + 톤을 알려줍니다). 진정으로 누락된 것에 대해서만 물으십시오. 사용자가 방금 "내 비디오 만들어 줘"라고 말했다면, 첫 번째 질문은 목적이어야 합니다 — 10개 항목 양식이 아닙니다.

수집: (1) 목적, (2) 시청자, (3) 길이, (4) 톤, (5) 배포 (가로/세로), (6) 자산, (7) 핵심 메시지, (8) 시각적 스타일, (9) 아바타, (10) 언어 (user_language에서 자동 감지; 비디오 언어가 채팅 언어와 다른지 확인). 이것은 음성 선택(language 필터), 스크립트 언어 및 voice_settings.locale을 결정합니다.

자산

모든 자산에 대한 두 가지 경로:

  • 경로 A (컨텍스트화): 읽기/분석, 정보를 스크립트에 반영. 참조 자료, 인증이 필요한 콘텐츠용.
  • 경로 B (자산으로 포함): heygen asset create를 사용하여 비디오에 직접 파일을 첨부 (자막, B-roll, 배경, 로고 등).

Individual skills in this repo

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

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Zuhair-01/claude-skills-and-systems

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

관련 스킬