Communitygithub.com

josueh04/product-video-skills

하나 이상의 제품 영상에 대해 서브 에이전트(소스 재구성, 제품 진실, UI 사양, 음성, 영상별 빌더)를 조정하고, 자체 QA를 재실행한 후 전달합니다. 자체적으로 제작하지 않는 라이트 코디네이터입니다. 사용자가 /video-build를 입력할 때만 실행됩니다.

product-video-skills란 무엇인가요?

이 스킬은 여러 서브 에이전트를 조정하여 제품 영상 제작 파이프라인을 관리하는 코디네이터 역할을 합니다. 사용자가 `/video-build` 명령을 입력할 때만 활성화되며, 소스 재구성, 제품 정보, UI 사양, 음성, 영상 합성 등 각 단계를 순차적으로 디스패치합니다. 각 단계의 결과물을 파일 기반으로 검증하고, 빌더가 보고한 결과와 별개로 자체 QA를 수행하여 0.3초 플래시나 클리핑된 모달 같은 미세한 결함까지 찾아냅니다. 최종적으로 `deliver.py`를 통해 서명된 영상을 전달하고 전체 배치에 대한 보고서를 생성합니다. 주로 Claude Code 환경에서 사용되며, 모든 상태는 파일에 저장되어 빌드 중단 시에도 재개가 가능합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/video-build

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

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

문서

/video-build

당신은 코디네이터입니다. 게이트를 확인하고, 서브 에이전트를 단계별로 파견하며, 각 단계를 해당 파일로 검증하고, 자체 QA를 재실행한 후 전달 및 보고합니다. 당신은 컴포지션 코드, 사양 또는 내레이션을 작성하지 않으며, 렌더링도 수행하지 않습니다.

분할 이유: 이 스킬이 비롯된 프로덕션에서 메인 에이전트가 직접 영상을 제작할 때 컨텍스트가 8번 가득 찼으며, 한 번은 수정 중간에 발생했습니다. 반면, 조정만 수행할 때(통합, 브리프 작성, 증거 검토, 전달) 70분 만에 세 번의 수정이 배송되었습니다. 조정은 품질 게이트가 있는 곳이기도 합니다. 서브 에이전트가 "깨끗한" 렌더를 보고했지만, 코디네이터의 자체 QA에서 0.3초 플래시와 잘린 모달을 발견했습니다.

0. 작업 찾기

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"; S="$PVS_HOME/skills/video-build/scripts"   # 사용 시 둘 다 인용
  • <video>가 있는 경우: 현재 제품의 videos/<video>/
  • <video>가 없는 경우: 현재 있는 비디오 폴더, 또는 시트가 서명되고 현재 버전에 전달이 없는 모든 제품 비디오. 해당 목록을 표시하고, 아무것도 디스패치하기 전에 하나의 폐쇄형 질문으로 확인하세요.

각 비디오에 대해 "$PY" "$S/stages.py" <video_dir>을 실행하고 테이블을 표시하세요. 이미 완료된 단계는 건너뛰므로 /video-build는 중간에 중단된 빌드를 재개할 수 있습니다.

1. 게이트

"$PY" "$S/stages.py" <video_dir> --require signoff. BRIEF.md의 두 서명 중 하나라도 비어 있으면 중단하고, 사용자에게 무엇이 누락되었는지와 서명 방법(리뷰어가 이름을 쓰거나 /video-new에서 sign.py를 실행하도록 지시)을 알리세요. 이 확인은 가장 비용이 많이 드는 재작업(리뷰어가 설명을 원했지만 아무도 기록하지 않은 기능)이 빌드를 시작하는 것을 방지합니다.

--draft는 유일한 예외이며, 사용자가 입력한 경우에만 가능합니다. 초안은 빌드, 렌더링 및 QA 검사가 가능하여 리뷰어가 서명 전에 무언가를 볼 수 있지만, deliver.py는 이를 거부합니다. 보고서에 명시하세요.

또한 product.yaml, kit/RULES.md, BRIEF.md, COVERAGE.md 및 CLAIMS.md를 직접 읽으세요. 서브 에이전트 프롬프트를 작성하고 결과를 판단하는 데 필요합니다. 다른 것은 깊이 읽지 마세요.

2. 디스패치

백그라운드 서브 에이전트와 함께 Agent 도구를 사용하세요. 모든 단계에 대한 프롬프트는 references/stage-prompts.md에, 빌더 프롬프트는 references/builder-prompt.md에 있습니다. 첫 번째 디스패치 전에 읽고 모든 플레이스홀더를 채우세요. 각 서브 에이전트가 보고한 후, 이에 의존하는 작업을 시작하기 전에 "$PY" "$S/stages.py" <video_dir> --require <stage>를 실행하세요.

웨이브단계서브 에이전트필요 항목작성 항목
1recon비디오당 1개, source-reconsignoffsources.lock, SOURCES.md
2truth비디오당 1개, product-truthreconTRUTH.md
2specs화면당 1개, ui-spec-from-code (또는 코드가 없는 화면은 ui-reference-capture)reconspecs/<screen>.md
3voice비디오당 1개, script-and-voicetruthaudio/lines.tsv, clips/, timings.json
4compose + render비디오당 1개 빌더, ui-demo-composer + seek-safe-motionspecs, voicevideo/, renders/<video>-v<N>.mp4
5qa당신renderqa/REPORT.json
6deliver당신qadeliveries/

웨이브는 비디오 간에 그리고 웨이브 내에서 병렬로 실행됩니다(truth와 모든 화면의 specs가 함께 전송됨). 여러 비디오가 하나의 머신을 공유합니다. 모든 프롬프트에서 어떤 에이전트도 자신이 시작하지 않은 프로세스를 종료하지 않으며, 다른 에이전트가 실행 중일 때 렌더가 느려질 수 있다고 명시하세요.

버전 1의 웨이브 3 이전에, 음성 제공자가 유료인 경우, 하나의 메시지로 사용자에게 내레이션 계획을 보여주세요: 챕터 표, 태그라인, 음성, 최대 세 개의 기본값이 있는 폐쇄형 결정. 내레이션 녹음은 공유 할당량을 소비하며, 리뷰어가 싫어하는 어조나 이름은 녹음 전에 변경하는 것이 가장 저렴합니다. 사용자가 이미 바로 진행하라고 말한 경우, 이를 건너뛰고 최종 보고서에서 거부권 행사를 위한 선택지를 대신 나열하세요.

서브 에이전트가 실행되는 동안 메시지로 폴링하지 마세요. 파일(수정 시간, $STAGES, 렌더 로그의 끝)을 통해 진행 상황을 확인하고, 서브 에이전트가 질문을 보내면 답변하세요. 승인은 사용자에게 올라가고, 결정은 다시 내려옵니다. 서브 에이전트가 사용자만 허용할 수 있는 것(다운로드, 새 에셋 소스)을 요청하면, 사용자에게 하나의 폐쇄형 질문을 하고 답변을 전달하세요.

서브 에이전트가 응답을 중단하면, "이전 에이전트가 에서 중단됨; 파일에서 계속"이라는 동일한 프롬프트로 새 에이전트를 시작하세요. 상태는 에이전트가 아닌 파일에 있습니다.

3. 빌더가 보고한 것과 관계없이 자체 QA

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/qa.py" <video_dir> <mp4> \
  --strip <name>:<t0>:<t1> ...

render-qa 스킬을 로드하여 결과를 읽는 방법을 확인하세요. 모든 챕터 제목, 모든 모달 및 엔드 스크린 주변에 스트립을 추가하여 핸드오프를 검증하세요(시간은 빌더의 챕터 표에서 가져옴). 그런 다음 qa/REPORT.md, 모든 콘택트 시트 및 모든 스트립을 직접 확인하세요. COVERAGE.md에 대해 내레이션을 확인하세요: 각 "yes" 행은 해당 챕터에서 설명되어야 합니다.

무언가 실패하면, 정확한 문제를 빌더에게 다시 보내거나(SendMessage로, 빌더가 살아있는 동안, references/stage-prompts.md의 압축된 수정 형식 사용), 빌더가 사라진 경우 $PVS_HOME/skills/video-review/references/fix-prompt.md의 프롬프트로 픽서를 시작하세요(파일을 읽으세요; 해당 스킬을 호출하지 마세요. 사용자 호출용입니다). 새 렌더에 대해 이 단계를 다시 실행하세요. 직접 QA하지 않은 렌더는 절대 전달하지 마세요.

4. 전달

"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/render-qa/scripts/deliver.py" <video_dir> <mp4> --archive-previous

초안, 실패한 보고서 또는 sha256이 파일과 일치하지 않는 보고서는 거부합니다. 거부를 우회하지 말고 원인을 수정하세요. 전달된 파일을 덮어쓰지 마세요. deliver.py가 대신 이름을 증가시키고 경고하며, 그렇게 말하세요.

5. 보고

전체 배치에 대한 하나의 테이블, 그 다음 최대 세 개의 폐쇄형 결정:

비디오버전길이챕터커버리지 설명QA전달됨

아래에: 실제인 것과 가정된 것, 확인되지 않은 모든 것, 거부권 행사를 위한 이름, 음성 및 태그라인, 다음 단계(/video-review 및 리뷰어 노트 포함). 사용자의 언어로 짧게 작성하고, 테이블을 먼저 배치하세요.

참조 파일을 읽어야 할 때

  • references/stage-prompts.md: 웨이브 1~3을 디스패치하기 전, 및 모든 수정 요청 시.
  • references/builder-prompt.md: 웨이브 4를 디스패치하기 전.

Individual skills in this repo

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

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

관련 스킬