Communitygithub.com

설명형 영상 스킬 (Hellboy)

기술에 익숙하지 않은 시청자를 위해 2-3분 분량의 세로형(9:16) 기술 설명 영상을 제작합니다. 만화 캐릭터 'Hellboy'가 인도 영어 음성으로 진행하며, 챕터 트래커, 건축 다이어그램, 가라오케 자막, 립싱크 등의 스타일을 따릅니다.

설명형 영상 스킬 (Hellboy)란 무엇인가요?

이 스킬은 사용자가 제공한 하나의 기술 주제를 바탕으로, 비전문가도 한 번에 이해할 수 있는 완성도 높은 2-3분 분량의 MP4 영상을 자동으로 제작합니다. 영상은 1080×1920 해상도의 세로형(9:16)이며, Hellboy라는 독특한 만화 캐릭터가 고정된 인도 영어 음성으로 설명합니다. 스킬은 스크립트 작성과 스토리보드 생성부터 영상 유효성 검증, 프리뷰, 최종 렌더링까지 전 과정을 안내합니다. 특히 스크립트는 '훅-긴장-로드맵-본문-반전-요약-마무리'의 7단계 구성을 따르며, 모든 문장이 화면의 시각적 요소와 정확히 매칭되도록 설계되어 있습니다. 이 스킬은 Claude Code, Cursor 등 터미널 기반 AI 에이전트에서 사용할 수 있으며, 대규모 모델과 소규모 모델 모두를 위한 별도의 플레이북을 제공합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bhuvanchandmaddi/video-generator-skill/tree/HEAD/skills/explainer-video

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

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

문서

설명형 영상 스킬 (Hellboy)은(는) 무엇을 하나요?

당신은 하나의 기술 주제를 비전문가가 처음 보자마자 이해하는 완성된 2-3분 분량의 1080×1920 MP4 영상으로 바꿉니다. 시각 스타일, 속도감, 스크립트 구조는 참조 채널(docs/01-style-bible.md에서 분석)에서 가져옵니다. 우리만의 것으로 고정된 두 가지는 **캐릭터(Hellboy)**와 음성입니다.

당신은 텍스트 파일(스크립트와 storyboard.json)만 작성합니다. engine/ 내의 엔진이 음성, 자막, 애니메이션, 캐릭터, 배경 음악 및 렌더링을 처리합니다.


사용자가 주제만 제시했을 때

추가 질문 없이 전체 작업을 수행합니다:

  1. 주제로부터 슬러그(slug)를 만듭니다 (예: how-dns-works) 그리고 python engine/make_video.py new videos/<slug>를 실행합니다.
  2. videos/<slug>/script.md(docs/02)를 작성한 다음, videos/<slug>/storyboard.json(docs/03 + docs/04)를 작성합니다. examples/upi-explained/의 패턴을 복사합니다.
  3. python engine/validate_storyboard.py videos/<slug>를 실행합니다. 모든 ERROR를 수정하고 0 error(s)가 출력될 때까지 반복합니다.
  4. python engine/make_video.py preview videos/<slug>를 실행합니다. 이미지가 보이면 build/preview.png를 docs/06 섹션 B와 비교하여 수정합니다.
  5. python engine/make_video.py render videos/<slug>를 실행합니다. 경로 output/<slug>.mp4, 재생 시간, 2줄 요약과 함께 응답합니다.

절대 지켜야 할 사항

  1. Hellboy는 절대 다시 그려지지 않습니다. 그는 오직 character/hellboy/hellboy.js에서만 가져옵니다. show, arm(down/point/explain), expression만 설정할 수 있으며 그 외는 불가능합니다. character/hellboy/CHARACTER_BIBLE.md를 한 번 읽으십시오.
  2. 음성은 고정되어 있습니다 (engine/config.json에서 설정). 비디오마다 변경하지 마십시오.
  3. 길이: 내레이션 360–470단어, 2:00–2:50분. 문장은 20단어 이하.
  4. 모든 문장은 화면에서 무언가를 변경합니다. 항목은 해당 단어가 언급되는 시점("at")에 나타납니다.
  5. 정확함이 단순함보다 우선입니다. 거짓된 내용을 말하지 말고, 내용을 생략함으로써 단순하게 만드십시오.
  6. 검증기는 통과해야 합니다 (렌더링 전 0 errors).

워크플로우 (순서대로 수행)

#단계읽을 문서산출물
1스캐폴드–python engine/make_video.py new videos/<slug>
2계획 및 스크립트 작성docs/02-script-writing.mdvideos/<slug>/script.md (360–470단어, 7비트)
3시각 자료 계획docs/03-visual-planning.md장면 목록: 내레이션 → 유형, 헤드라인, 캐릭터
4스토리보드 작성docs/04-storyboard-reference.mdvideos/<slug>/storyboard.json (또는 meta.json + scenes.jsonl → assemble)
5유효성 검사–python engine/validate_storyboard.py videos/<slug> → 오류 0개가 될 때까지 수정
6프리뷰 + QAdocs/06-qa-checklist.mdmake_video.py preview videos/<slug> → build/preview.png 검사 후 수정
7렌더링docs/05-production.mdmake_video.py render videos/<slug> → output/<slug>.mp4
8최종 QAdocs/06-qa-checklist.md점수 ≥ 85, 모든 MUST 항목 통과

소형/로컬 모델인 경우? 단계 2–5 대신 docs/07-small-model-playbook.md를 따르십시오. 작업을 한 번에 한 장면씩 처리하는 프롬프트로 나눕니다.

7비트 스크립트 (암기)

훅 (22단어 이하: "X 설명" / "X는 실제로 어떻게 작동할까?" / 놀라운 주장 / 공감 가는 행동) → 긴장 (미스터리) → 로드맵 ("함께 따라가 봅시다…") → 본문 (3–6개 챕터: 개념 → 쉬운 설명 → 일상 예시 → 결과; 이름이 있는 사람을 포함한 하나의 실행 예시) → 반전 ("하지만 여기서 재미있는 점은…") → 요약 ("이렇게 기억하세요." 챕터당 한 줄) → 마무리 (훅을 반향하는 단편: "한 번의 스캔. 네 명의 플레이어. 2초.").

장면 레시피 (암기)

  • 1개 장면 = 1–3문장 (8–28단어, 3–8초); 비디오당 20–32개 장면.
  • visual.type은 docs/03-visual-planning.md의 결정 테이블에서 선택합니다. 비디오당 7–12가지 유형을 사용합니다.
  • 40–70%의 장면에서 Hellboy를 표시합니다 (항상: 첫 장면, 반전, 요약, 마지막 장면). sequence, hub, diagram, compare 유형에서는 숨깁니다.
  • 큰 다이어그램은 "continue": true + "shown": true 항목과 동일한 헤드라인을 사용하여 2–4개 장면에 걸쳐 구축합니다.
  • 헤드라인은 2–6단어이며 하나의 *강조* 단어를 포함합니다. 화면 라벨은 1–4단어입니다.

명령어 (저장소 루트에서 실행)

# 먼저 활성화:  source .venv/bin/activate   |   Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new       videos/<slug>   # 템플릿 생성
python engine/make_video.py assemble  videos/<slug>   # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py  videos/<slug>   # 오류 0개여야 함
python engine/make_video.py preview   videos/<slug>   # build/preview.png (장면당 1 프레임)
python engine/make_video.py render    videos/<slug> [--fast]

해당 머신에서 처음 실행 시: ./setup.sh (Linux/macOS) 또는 setup.ps1 (Windows). 완성된 비디오는 **output/<slug>.mp4**에 저장됩니다.

참고 자료

  • examples/upi-explained/ (따뜻한 종이 스타일) 및 examples/load-balancer-explained/ (청사진 스타일) — 완전한 작업 예제입니다. 그 패턴을 복사하십시오.
  • templates/ — script.template.md, storyboard.template.json.
  • docs/01-style-bible.md — 참조 채널의 방식과 측정된 규칙 (규칙이 존재하는 이유).
  • engine/icon_names.txt — 허용된 2,359개의 아이콘 이름 (Lucide).

관련 스킬