Repo Demo Video

이 스킬을 사용하면 저장소를 세련된 제품 데모 계획으로 전환하고, 충분한 런타임 정보를 사용할 수 있을 때 브라우저에서 녹화된 데모 비디오까지 생성할 수 있습니다.

핵심 원칙

완벽한 사용자 설정보다 저장소 증거를 우선시합니다:

demo.config.json 또는 demo.config.yaml이 있으면 사용합니다.
DEMO_GUIDE.md가 있으면 사용합니다.
README.md를 사용합니다.
package.json, 프레임워크 파일, 라우트 폴더, 컴포넌트 이름, 페이지 제목 및 소스 구조를 사용합니다.
안전한 URL이 있을 때 배포된 앱 또는 로컬 앱을 브라우저에서 탐색합니다.
신뢰도 점수와 함께 대체 가정을 생성합니다.

README.md와 소스 코드를 기본 소스로, DEMO_GUIDE.md를 권장되는 사람 친화적인 가이드로, demo.config.*를 선택적 기계 친화적인 재정의로 취급합니다.

워크플로

대상 저장소 경로 또는 URL을 확인합니다. MVP CLI의 경우 로컬 저장소 경로를 사용하고, GitHub URL이 주어지면 향후 복제 워크플로가 명시적으로 제공되지 않는 한 사용자에게 로컬 클론을 제공하도록 요청합니다.

분석기를 실행합니다:

npm run demo -- --repo ./path-to-repo

선택적 입력:

npm run demo -- --repo ./path-to-repo --config ./demo.config.json
npm run demo -- --repo ./path-to-repo --url https://example.com
npm run demo -- --repo ./path-to-repo --mode draft
npm run demo -- --repo ./path-to-repo --mode full

타임스탬프가 찍힌 출력 폴더(예: demoOutput-2026-05-10-143012/)에서 생성된 아티팩트를 검토합니다:
- project_summary.md
- demo_plan.draft.json
- demo_plan.json (신뢰도가 충분히 높을 때)
- narration_script.draft.md
- narration_script.md
- script_quality_report.json
- timing_plan.json
- demo_storyboard.md
- manual_recording_guide.md
- recordings/ (브라우저 캡처 성공 시)
- screenshots/ (브라우저 탐색 성공 시)
- voiceover.mp3 (TTS_PROVIDER=openai 및 OPENAI_API_KEY를 사용할 수 있을 때)
- demo_video.html (MP4 합성이 불완전할 때 로컬 미리보기 대체)
- demo_video.mp4 (녹화, 실제 오디오 및 ffmpeg를 사용할 수 있을 때만)

신뢰도 규칙

명시적인 문서 및 설정 주장을 high로 표시합니다.
프로젝트 이름, 요약 및 하나 이상의 기능이 명확할 때 README 기능 목록을 최종 계획을 생성하기에 충분한 증거로 취급합니다.
라우트 이름, 컴포넌트 이름, 패키지 메타데이터 및 명확한 코드 구조를 medium으로 표시합니다.
추측성 제품 주장 및 추정된 작업을 low로 표시합니다.
중요한 주장의 신뢰도가 낮으면 demo_plan.draft.json을 생성하고, 누락된 사항을 설명하며, 최종 비디오 계획을 확정된 것으로 제시하지 않습니다.

README 파싱

제품 요약을 추출할 때 배지, 쉴드 이미지, 장식용 이미지 행, 원시 URL 및 라이선스/상태 메타데이터를 무시합니다.
제품 요약을 추출할 때 DEMO_GUIDE.md 피치, README 블록 인용 요약, README 개요/소개/설명 섹션, 그다음 패키지 설명을 선호합니다.
이모지나 기호가 포함된 장식된 제목(예: ## Features)을 일치시키기 전에 제목을 정규화하여 인식합니다.
기능/역량/하이라이트 제목 아래의 글머리 기호 목록을 고신뢰도 기능으로 추출합니다.
사용법/방법/데모/퀵 스타트 제목 아래의 번호가 매겨진 워크플로를 중간 신뢰도 데모 흐름 힌트로 추출합니다.
스크립트를 작성하기 전에 나레이션 입력을 정리합니다. Markdown 배지, 이미지 구문 또는 원시 URL을 음성 해설 텍스트로 가져오지 않습니다.

안전

저장소 분석은 읽기 전용으로 유지합니다.
생성된 아티팩트는 대상 저장소의 새로운 타임스탬프가 찍힌 demoOutput-YYYY-MM-DD-HHMMSS/ 폴더에만 씁니다.
파일을 재귀적으로 삭제하거나 파괴적인 명령을 실행하지 않습니다.
배포 명령을 실행하지 않습니다.
사용자가 내레이터 출력을 요청하거나 공급자 환경 변수를 구성할 때 외부 LLM/TTS 호출이 허용됩니다. 정리된 프로젝트 요약, 데모 계획, 브라우저 관찰 및 나레이션 스크립트 텍스트만 전송합니다.
원시 .env 파일, API 키, 개인 토큰, 개인 사용자 데이터, 실제 자격 증명 또는 불필요한 소스 파일을 외부 LLM/TTS 공급자에게 보내지 않습니다.
나레이션, 스크린샷, 비디오, 로그 또는 생성된 아티팩트에서 비밀, API 키, 개인 토큰, .env 값, 개인 사용자 데이터 또는 실제 자격 증명을 노출하지 않습니다.
테스트 계정이 문서화된 경우, 사용자가 명시적으로 다른 것을 요청하지 않는 한 데모 계정이 사용된다고만 언급합니다.

브라우저 및 비디오 동작

설정, DEMO_GUIDE.md, README 또는 --url 인수의 배포된 demoUrl을 선호합니다.
Playwright를 사용할 수 있을 때 표시되는 제목, 버튼, 링크, 양식을 검사하고 스크린샷 또는 녹화를 캡처합니다.
보수적인 DOM 휴리스틱을 사용하여 안전한 샘플 입력을 채우고, 비어 있지 않은 선택 옵션을 선택하며, 추가, 계산, 메서드, 리소스, 새로 만들기, 만들기와 같은 일반적인 데모 컨트롤을 클릭합니다.
각 계획된 장면을 나레이션 속도에 맞춰 화면에 충분히 오래 유지하고, 휴리스틱 작업 후 잠시 멈추어 녹화가 단순히 빠른 클릭이 되지 않도록 합니다.
정식 .webm 녹화 경로를 run_report.json에 등록합니다.
실행 지침이 불확실할 때 로컬 프로젝트 시작을 강제하지 않습니다.
Playwright, TTS, ffmpeg 또는 앱 런타임을 사용할 수 없는 경우에도 작성된 아티팩트, 부분 결과물, demo_video.html 및 수동 녹화 가이드를 생성합니다.
음성 해설 길이에 맞춰 최종 MP4를 구성합니다. 최단 스트림 자르기를 사용하지 않습니다. 브라우저 녹화가 음성 해설보다 짧으면 ffmpeg tpad로 최종 비디오 프레임을 확장하고 확장 길이를 보고합니다.

전문 스크립트 작성

결정론적 초안을 대체로 사용하지만, SCRIPT_PROVIDER=openai이고 OPENAI_API_KEY가 설정된 경우 OpenAI 스크립트 작성기를 선호합니다.
최종 스크립트를 작성하기 전에 timing_plan.json을 생성합니다. 사용 가능한 기능, 브라우저 장면, 구성된 비디오 길이 및 속도 경고를 기반으로 합니다.
스크립트 작성 및 OpenAI TTS에 동일한 OPENAI_API_KEY를 사용합니다.
제품 데모 작성을 위한 프롬프트는 src/prompts/demoNarrationPrompt.ts에서 제어합니다.
OpenAI Responses API 모델은 OPENAI_SCRIPT_MODEL로 제어합니다. 설정되지 않은 경우 OPENAI_MODEL, 그다음 gpt-5.4-mini로 대체합니다.
템플릿 초안에 대해 narration_script.draft.md를, 최종 LLM 또는 대체 스크립트에 대해 narration_script.md를 작성합니다.
script_quality_report.json을 공급자, 모델, 대체 이유 및 품질 게이트 경고와 함께 작성합니다.
프롬프트는 스크립트 작성자가 먼저 제품을 이해하고, 배지 및 원시 README 메타데이터를 피하고, 청중/문제/가치에 집중하고, 불확실한 주장에 대해 보수적인 표현을 사용하며, 타이밍 계획의 장면 수 및 단어 예산을 존중하도록 해야 합니다.

데모 시각적 안내

세련된 브라우저 녹화를 위해 앱 소스 코드를 편집하는 대신 Playwright를 통해 임시 비영구 시각적 안내 오버레이를 삽입합니다.

다음을 사용합니다:

현재 나레이션 비트에 대한 미묘한 캡션.
활성 UI 요소 또는 결과 영역 주변의 강조 링.
높은 z-index, pointer-events: none 및 고정 위치.
제품 UI를 가리지 않는 중립적인 스타일.

기능을 위조하기 위해 오버레이를 사용하지 마십시오. 실제 UI 상태 변경으로 시청자의 주의를 안내하는 데만 사용하십시오. 오버레이는 녹화 브라우저 세션에만 존재해야 하며 세션이 종료되면 사라져야 합니다.

음성 해설

OPENAI_API_KEY가 설정된 경우 전체 모드에서 기본적으로 OpenAI TTS를 사용합니다.
실제 오디오를 명시적으로 생성하려면 TTS_PROVIDER=openai 및 OPENAI_API_KEY를 설정합니다.
TTS_PROVIDER가 설정되지 않았지만 OPENAI_API_KEY가 있는 경우 OpenAI TTS를 사용합니다.
로컬 모의 모드를 강제하려면 TTS_PROVIDER=mock을 설정합니다.
OPENAI_API_KEY는 전문 스크립트 작성기가 사용하는 것과 동일한 키일 수 있습니다.
선택적 변수: OPENAI_TTS_MODEL, OPENAI_TTS_VOICE, OPENAI_TTS_INSTRUCTIONS, TTS_VOICE.
실제 오디오를 현재 실행 폴더(예: demoOutput-2026-05-10-143012/voiceover.mp3)에 씁니다.
음성 해설 오디오를 생성하려면 정리된 voiceover_script.txt 텍스트를 구성된 TTS 공급자에게 보내야 합니다.
API 키를 생성된 파일에 절대 쓰지 마십시오.
데모를 게시할 때 생성된 음성 해설이 AI 생성임을 공개합니다.

스킬 확장

아키텍처를 모듈식으로 유지합니다. CLI를 하나의 큰 스크립트로 만드는 대신 해당 src/*.ts 모듈을 확장하여 향후 GitHub URL 복제, 더 깊은 UI 상호 작용, 실제 TTS 공급자, 캡션, 비디오 스타일, 로컬 시작 및 인간 검토에 대한 지원을 추가합니다.

저장소 데모 비디오 스킬