Walkthrough GIF Skill (워크스루 GIF 스킬)
브라우저 워크스루를 녹화하고 MP4 + GIF로 내보내는 자체 포함된 Node.js 프로젝트를 생성합니다.
이 스킬을 사용해야 하는 경우 vs. claude-in-chrome gif_creator
사용자의 라이브 브라우저 세션 내에서 빠른 일회성 캡처가 필요한 경우 (프로필, 열린 탭, 이미 로그인된 상태) claude-in-chrome의 gif_creator 도구가 훨씬 간단합니다. 프로젝트 스캐폴딩이나 API 키가 필요 없습니다. 사용자가 gif_creator로는 얻을 수 없는 재실행 가능/버전 관리 가능 스크립트 (UI 변경 후 재녹화), MP4 출력, 고품질 gifski GIF, 깨끗한 프로필 녹화 (개인 북마크/확장 프로그램 제외), 또는 CI 반복성이 필요할 때 이 스킬을 사용하세요.
아키텍처
자연어 설명
↓
Claude가 TypeScript 스크립트 생성
↓
Stagehand v3 (AI 브라우저 제어) — Playwright가 CDP를 통해 연결
↓
Playwright 녹화 컨텍스트가 비디오 캡처 (.webm)
↓
ffmpeg 변환 → .mp4
gifski 프레임 변환 → .gif
↓
출력: walkthrough.mp4 + walkthrough.gif + walkthrough.md
워크플로우
1단계: 요구 사항 수집
전제 조건 — LLM API 키: Stagehand는 각 AI 작업에 대해 LLM을 호출합니다. 사용자에게 .env 파일에 사용할 수 있는 ANTHROPIC_API_KEY (또는 설정된 모델과 일치하는 제공자 키 (예: OPENAI_API_KEY))가 필요합니다. 이를 미리 확인하세요 — 키가 없으면 생성된 스크립트를 실행할 수 없습니다.
코드를 생성하기 전에 다음을 확인하세요:
- 대상 URL — 워크스루가 시작되는 위치는? (예:
https://app.example.com/login) - 흐름 설명 — 어떤 단계를 시연해야 합니까? (자연어 사용 가능)
- 인증 상황 — 페이지가 공개되어 있습니까, 아니면 로그인이 필요합니까? 로그인이 필요한 경우:
.env에 자격 증명을 하드코딩할 것인지, 사전 인증된 세션/쿠키 내보내기를 사용할 것인지, 아니면 로그인된 상태에서 시작할 것인지? - 출력 형식 — GIF만, MP4만, 아니면 둘 다? (기본값: 둘 다)
- 기간/속도 — 빠른 데모 또는 신중한 단계별? (단계 사이에 약 1-2초 일시 중지가 기본값)
- 뷰포트 — 기본값은 1280×800입니다. 모바일 스타일 데모의 경우 더 좁게.
사용자가 처음부터 풍부한 설명을 제공하는 경우, 추론할 수 있는 것은 추론하고 누락된 부분에 대해서만 질문하세요.
2단계: 프로젝트 생성
./walkthrough-[name]/에 완전하고 실행 가능한 프로젝트를 출력합니다:
walkthrough-[name]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│ └── walkthrough.ts ← 메인 스크립트
└── scripts/
└── convert.sh ← ffmpeg + gifski 변환
Stagehand API 및 단계 변환 패턴은 references/stagehand-patterns.md를 참조하세요.
ffmpeg/gifski 변환 명령 및 GIF 튜닝은 references/output-pipeline.md를 참조하세요.
3단계: 단계 변환
사용자의 자연어를 stagehand.act() 호출로 변환합니다 (v3: act()는 stagehand 인스턴스에 있으며, 일반 문자열을 받고 variables 및 page와 같은 옵션이 있습니다). 패턴 및 주의 사항은 references/stagehand-patterns.md를 참조하세요.
주요 변환 규칙:
- 각 논리적 UI 작업 = 하나의
stagehand.act("...", { page })호출 (명확한 영어 명령 포함) - 입력은
variables(%name%플레이스홀더)를 통해 입력 — 명령 문자열에 비밀 정보를 인라인으로 절대 넣지 마세요 - 주요 단계 사이에
page.waitForTimeout(1500)을 추가하여 페이싱 조절 (시청자에게 표시됨) - 탐색 후
page.waitForLoadState('networkidle')추가 - 선택자를 절대 하드코딩하지 마세요 — Stagehand는 자연어 명령에서 선택자를 알아냅니다
- 인증이 필요한 흐름의 경우: 자격 증명에
.env를 사용하고 절대 하드코딩하지 마세요
4단계: 녹화 전략
항상 Playwright 비디오 녹화를 기본 캡처 방법으로 사용하세요:
- Stagehand v3에는 기본 제공 녹화 기능이 없습니다 —
chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() })를 통해 Playwright를 Stagehand의 브라우저에 연결하고,recordVideo옵션으로 컨텍스트를 생성한 다음, 해당 컨텍스트의 페이지를 구동합니다 (references/stagehand-patterns.md참조) - 해당 녹화 컨텍스트를 통해 전체 세션을
.webm으로 녹화합니다 - 개별 스크린샷을 직접 GIF로 연결하려고 시도하지 마세요 — 비디오 → 프레임 → GIF가 더 높은 품질입니다
- 스크립트가 완료된 후
convert.sh를 실행하여 MP4 및 GIF를 생성합니다
GIF를 기본 아티팩트로 만들지 마세요. MP4가 항상 먼저 생성됩니다. GIF는 MP4에서 파생됩니다. GIF는 15초를 초과하는 경우 크기가 크고 품질이 낮습니다 — 사용자에게 경고하고 워크스루를 60초 미만으로 유지할 것을 권장합니다.
5단계: 클릭/커서 오버레이 (선택 사항이지만 권장)
워크스루가 시작되기 전에 page.addInitScript()를 통해 클릭-하이라이트 오버레이를 주입합니다. 스니펫은 references/stagehand-patterns.md → "클릭 오버레이" 섹션을 참조하세요.
이렇게 하면 각 클릭 지점에 미묘한 리플 애니메이션이 추가되어 후처리 없이 워크스루를 훨씬 더 읽기 쉽게 만듭니다.
6단계: 출력
생성 후 다음을 생성합니다:
- 프로젝트 디렉토리 (모든 파일)
- 대화에 간단한 설정 체크리스트:
## 설정
npm install
npx playwright install chromium
cp .env.example .env # ANTHROPIC_API_KEY + 필요한 자격 증명 입력
## 실행
npx tsx src/walkthrough.ts
## GIF + MP4로 변환
bash scripts/convert.sh
또한 사용자에게 예상 사항 (대략적인 기간, 뷰포트 크기, 출력 파일 이름)을 알려줍니다.
직접 실행 제안: Claude Code는 전체 파이프라인 (npm install, npx playwright install chromium, 워크스루 스크립트 실행, bash scripts/convert.sh)을 직접 실행할 수 있습니다 — 사용자가 동의하는 경우 (여전히 .env 값을 제공해야 함). 직접 실행할 때는 ffprobe로 MP4의 합리적인 기간을 확인하고 GIF/MP4 파일 크기가 무시할 수 없는 수준인지 확인하여 (convert.sh는 인증 테일에서 이를 출력함) 출력을 검증하세요.
경고 / 중단 조건
다음 중 해당 사항이 있으면 사용자에게 미리 알리세요:
| 조건 | 지침 |
|---|---|
| 페이지에 MFA/SSO 로그인 필요 | 스크립트가 자동으로 처리할 수 없음 — 사용자가 로그인된 브라우저 세션에서 쿠키를 내보내야 함 |
| 대상 페이지에 CAPTCHA | Playwright가 중단됨 — 대신 데모/샌드박스 환경 사용 |
| 무거운 애니메이션 / 무한 스크롤러 | 녹화는 캡처하지만 GIF 변환 시 크기가 커짐 — 클리핑 제안 |
| 흐름이 90초 초과 | MP4만 권장; GIF는 사용할 수 없을 정도로 커짐 |
| 페이지 콘텐츠가 무작위/동적임 | Stagehand는 시각적 타겟팅을 처리하지만 재실행 시 모양이 다를 수 있음을 경고 |
출력 명명 규칙
walkthrough-[slug]/
output/
walkthrough.webm ← 원시 Playwright 녹화
walkthrough.mp4 ← 변환됨 (H.264, 웹 안전)
walkthrough.gif ← gifski 출력, 최대 너비 800px
walkthrough.md ← 단계별 주석 (자동 생성)
.md 파일은 각 act() 호출을 타임스탬프가 있는 번호가 매겨진 단계로 나열합니다 — GIF와 함께 캡션으로 포함하는 데 유용합니다.
참조 파일
references/stagehand-patterns.md— Stagehand API, 단계 변환, 클릭 오버레이 스니펫, 인증 패턴references/output-pipeline.md— ffmpeg 명령, gifski 플래그, GIF 최적화, 문제 해결