Communitygithub.com

josueh04/product-video-skills

제품의 실제 프론트엔드 코드를 1:1로 재구성한 비디오용 명세로 변환합니다. 화면별 읽기 전용 서브 에이전트를 사용하여 모든 변수가 리터럴 값과 인용(role/path:line@sha)으로 해결된 정적 HTML, CSS, 상태, 전환(정확한 지속 시간 및 이징), 아이콘, i18n 문자열을 생성합니다. 또한 `resolve_tokens.py`를 실행하여 제품 디자인 토큰을 `kit/tokens.css`로 추출합니다.

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

이 스킬은 제품의 실제 프론트엔드 코드를 기반으로 비디오 제작에 필요한 UI 명세를 자동 생성합니다. 각 화면마다 읽기 전용 서브 에이전트를 실행하여 모든 CSS 변수, 상태 전환, 애니메이션 지속 시간, 아이콘 라이브러리, i18n 문자열을 코드에서 직접 추출하고 인용합니다. `resolve_tokens.py` 스크립트를 통해 디자인 토큰을 리터럴 값으로 해결하여 `kit/tokens.css` 파일로 내보냅니다. 지원하는 프레임워크 어댑터로는 Angular with PrimeNG(검증됨), React, Vue, Tailwind, 일반 HTML(미검증)이 있습니다. 코드 검토에서 발견되지 않는 미묘한 버그(런타임 루트 폰트 크기, 정의되지 않은 CSS 변수, 누락된 상태)를 캐치하고, 제품의 실제 모습과 1:1로 일치하는 정적 HTML/CSS 명세를 생성합니다.

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

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

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

문서

코드에서 UI 명세 추출

비디오는 제품 인터페이스를 녹화하는 대신 HTML과 CSS로 재구성합니다. 따라서 인터페이스의 정확성은 명세가 기반한 원본 코드에 달려 있습니다. 근사치는 금방 드러납니다. 이 스킬이 비롯된 실제 제작 환경에서는 검토자가 첫 리뷰에서 손으로 그린 아이콘과 로고를 거부했고, 크기와 이름이 잘못된 수제 배지는 검토자를 분노하게 만들었습니다. 수정 사항은 코드를 읽음으로써 발견되었으며, 코드에는 눈으로는 발견할 수 없는 함정이 숨어 있었습니다. 루트 폰트 크기는 앱 셸에 의해 런타임에 설정되었고(14px, 스타일시트가 선언한 10px가 아님), 여러 CSS 변수가 프로덕션에 존재하지 않아 폴백 값을 사용했으며, 한 컴포넌트는 두 달 전 커밋에서 악센트 막대를 잃어버렸고, 두 개의 "대화상자"는 라이브러리의 대화상자가 아닌 사용자 정의 팝업이었습니다.

따라서 명세의 모든 값은 리터럴이고 인용되며, 인용할 수 없는 값은 표시됩니다. 절대 추측하지 않습니다.

입력

  • videos/<video>/SOURCES.md (source-recon에서 생성): 각 화면, 라우트, 컴포넌트 및 상태. 파일이 없으면 먼저 source-recon을 실행하세요.
  • sources/<role>/ 및 sources.lock. 모든 인용은 잠긴 sha를 사용합니다.
  • product.yaml: app_canvas.logical (UI가 재구성되는 뷰포트), app_canvas.theme, app_canvas.rem_px, sources[].framework.
  • 프레임워크용 어댑터: references/adapters/<framework>.md. 서브 에이전트 프롬프트를 작성하기 전에 이를 읽어 해당 스택에서 값이 어디에 숨어 있는지 확인합니다.
product.yaml의 frameworkadapter상태
angular-primengreferences/adapters/angular-primeng.md프로덕션에서 검증됨
reactreferences/adapters/react.md미검증
vuereferences/adapters/vue.md미검증
Tailwind를 사용하는 모든 스택references/adapters/tailwind.md (자체 프레임워크 어댑터와 함께)미검증
html, other, 서버 템플릿references/adapters/html.md미검증

미검증 어댑터의 경우 사용자에게 미검증 상태임을 알리고, 어댑터를 따르되 마지막에 배운 내용을 추가하여("에서 배운 점" 섹션) 다음 제품이 더 나은 출발점을 가질 수 있도록 합니다.

1. 글로벌 렌더링 사실 (제품당 한 번)

화면 작업 전에 모든 화면이 의존하는 사실을 확인하고 인용과 함께 kit/render-facts.md에 기록합니다.

  • 런타임 루트 폰트 크기 (CSS뿐만 아니라 설정하는 코드를 앱 셸에서 검색), rem 변환이 올바르게 이루어지도록 합니다. 다르다면 product.yaml의 app_canvas.rem_px를 업데이트합니다.
  • 테마: 비디오의 테마를 활성화하는 선택자와 기본적으로 켜져 있는지 여부.
  • 토큰 파일, CSS 레이어 또는 가져오기 순서(어느 규칙이 우선하는지), 정확한 버전의 컴포넌트 라이브러리(잠금 파일에서) 및 해당 테마 프리셋.
  • 실제로 로드된 글꼴(링크 태그, @font-face, 글꼴 패키지). CSS에서 이름만 지정되고 로드되지 않은 글꼴은 프로덕션에서 폴백으로 렌더링됩니다.
  • 데스크톱 중단점. app_canvas.logical이 데스크톱 레이아웃을 표시하는지 확인합니다.

그런 다음 비디오 테마에 대해 리터럴로 해결된 토큰을 작성합니다.

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
  [--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]

이 스크립트는 sources/<role>/에서 CSS 사용자 정의 속성, 최상위 SCSS 변수 및 Tailwind v3 테마(정적으로)를 읽고, 모든 var() 및 $variable을 해결하며, 각 줄에 /* role/path:line@sha */ 인용과 함께 kit/tokens.css를 작성합니다. UNDEFINED로 표시된 줄은 프로덕션에서 정의되지 않은 변수(가능한 결함)이고, needs a Sass compile은 Sass 함수로 빌드된 값을 표시하며, 서브 에이전트가 함수와 입력에서 수동으로 해결해야 합니다. 내보내기에 관련 없는 스타일시트(문서 사이트, 이메일 템플릿, 벤더 CSS)가 포함된 경우 --files를 사용합니다.

2. 화면당 하나의 서브 에이전트

화면당(또는 큰 화면의 패널당) 하나의 읽기 전용 서브 에이전트를 실행합니다. 모두 병렬로 실행하며, references/ui-spec-prompt.md를 채우고 어댑터의 "값이 숨은 위치" 목록을 추가합니다. 각 서브 에이전트를 sources/<role>/(사용자의 체크아웃이 아님)로 지정하고 렌더링 컨텍스트(논리적 캔버스 크기, 테마, rem, 렌더링 사실, 토큰 및 이미 재구축된 조각의 CSS)를 제공하여 새 조각이 일치하도록 합니다.

각 서브 에이전트는 다음을 반환합니다. 캔버스 내부의 지오메트리, 상태별 정적 HTML(프레임워크 구문 없음), 각 값에 대한 리터럴 값과 인용이 있는 하나의 CSS 블록, 추가 클래스로 표현된 hover/focus/active/disabled/loading 상태, 정확한 지속 시간과 이징이 있는 전환 및 키프레임, 라이브러리 및 이름별 아이콘(또는 인라인 SVG 그대로), 모든 표시 문자열, 그리고 명시적인 "미확인" 목록.

조정자(당신)는 직접 명세를 추출하지 않습니다. 실제 앱의 한 화면은 수십 킬로바이트의 결과를 생성할 수 있으며, 중간에 컨텍스트가 가득 차면 전체 빌드의 추적을 잃게 됩니다.

3. 아이콘 및 이미지

아이콘은 제품 자체 아이콘 세트와 자산에서 가져옵니다. 절대 그리지 않으며 브라우저 프로필이나 확장 폴더에서 가져오지 않습니다. 제품당 한 번(그리고 새 화면에 대해 다시) references/icon-extraction-prompt.md를 실행하여 비디오에 필요한 모든 아이콘을 라이브러리 및 이름에 매핑한 다음, 이름을 product-kit의 collect_icons.py에 전달합니다. 이 스크립트는 SVGs를 인용과 함께 kit/icons/으로 복사합니다. SVG 파일이 없는 아이콘 글꼴의 경우 빌드는 라이브러리 자체 CSS에서 코드 포인트를 작성하고, 빈 상자를 렌더링하는 대신 알 수 없는 이름에서 실패해야 합니다.

4. 명세 작성

각 화면에 대해 videos/<video>/specs/<screen>.md 및 specs/<screen>.html:

# 명세: <screen>
출처: frontend@1a2b3c4 (SOURCES.md 참조). 캔버스 1440x810, 테마 라이트, rem 16.

## 지오메트리
| 요소 | x | y | w | h | 인용 |

## 상태
S1 <name>: <표시되는 내용, 가상 데이터>. HTML은 <screen>.html, 섹션 S1.

## CSS
<하나의 블록, 리터럴 값, 각 줄에 /* role/path:line@sha */>

## 모션
| 항목 | 속성 | 시작 | 끝 | 지속 시간 | 이징 | 지연 | 인용 |

## 아이콘
| 키 | 라이브러리 | 이름 | kit/icons의 파일 | 인용 |

## 문자열
| 키 | 텍스트 | 인용 |

## 수정 사항 (비디오에서 수정된 프로덕션 결함)
| 항목 | 프로덕션 동작 | 비디오 동작 | 이유 |

## 미확인
- <값 또는 동작, 이유 및 사용 가능한 최상의 참조>

외관 유지, 결함 수정

레이아웃, 토큰 및 동작을 1:1로 재구성하며, 실제 제품처럼 느껴지게 하는 애니메이션, 호버, 타이핑 및 로딩 상태를 포함합니다. 하지만 가시적인 프로덕션 결함은 수정합니다. 비디오는 제품의 최상의 모습을 보여주며 검토자는 왜 버그가 화면에 보이는지 질문할 것이기 때문입니다. 누락된 패딩, 오버플로, 잘린 텍스트, 기본 브라우저 컨트롤(회색 기본 오디오 플레이어)이 디자인된 것으로 의도된 위치에 있는 경우, 정의되지 않은 변수가 폴백을 표시하는 경우, 클릭 후 포커스 링이 남아 있는 경우 등입니다. 각 수정 사항을 명세의 수정 사항 테이블과 BRIEF 노트에 나열합니다. 디자인 결정인 특이점은 유지합니다(필드를 덮는 스티키 푸터, 콘텐츠와 함께 스크롤되는 사이드바). 이를 변경하는 것은 수정이 아니라 재설계입니다.

명세가 적용하고 기록하는 두 가지 추가 변환:

  • 정식 이름. product.yaml names의 레거시 문자열을 라이브 UI에 여전히 이전 이름이 표시되더라도 정식 이름으로 바꾸고, 해당 요소의 다른 모든 것은 유지합니다.
  • 금지 용어. 실제 화면에 벤더 또는 banned_terms의 용어(모델 선택기, 통합 카드)가 표시되면 해당 부분을 프레임 밖으로 남깁니다. 비어 있거나 깨져 보이지 않아야 합니다. 자연스럽게 없는 프레이밍 또는 상태를 선택합니다.

데이터

명세는 product.yaml cast의 가상 데이터만 전달합니다. 저장소의 픽스처, 시드 및 스크린샷은 실제 이름을 보유할 수 있습니다. 모양은 사용하고 값은 사용하지 마십시오.

명세를 빌드에 전달하기 전 체크리스트

  • 잠긴 커밋 인용됨; 렌더링 사실 작성됨; 비디오 테마에 대해 토큰 해결됨
  • 캔버스 크기가 데스크톱 중단점 이상; rem이 런타임과 일치
  • 모든 var() 해결됨; 정의되지 않은 변수는 폴백과 함께 나열됨(또는 결함으로 수정됨)
  • 모든 문자열이 i18n 파일 또는 템플릿에서 가져옴; 정식 이름 적용됨
  • 모든 아이콘이 앱의 라이브러리에서 가져옴; 빌드가 누락된 글리프에서 실패
  • 로고 및 이미지가 저장소 자산에서 가져옴
  • 기본 상태(탭, 아코디언, 토글)가 코드와 일치
  • 오버레이, 팝업 및 전환 타이밍이 정확한 이징과 함께
  • 스크롤 범위가 실제 콘텐츠 내에 있음; 가장자리에서 텍스트 잘림 없음
  • 프레임 내에 벤더, 금지 용어, 내부 ID 또는 실제 고객 데이터 없음
  • 수정 사항 및 유지된 특이점이 나열됨; 미확인 값이 검토자용으로 나열됨

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

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

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

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.

관련 스킬