version: "1.0.0" name: video-analyze description: >- Use this skill whenever a user points to a video — a local file (.mp4/.mov/.mkv/.avi 등) or a video URL (YouTube, Vimeo, 웹 링크) — and wants to know what's in it. Triggers on intents like: 요약/무슨 내용/이거 무슨 영상, 받아써줘·전사·누가 무슨 말 했는지, 타임스탬프·챕터 따줘, 화면 속 객체·텍스트·장면 뽑아줘, 특정 구간 분석. Covers 회의녹화·강의·튜토리얼·시연·현장영상·제품소개 등 영상이 입력으로 들어오는 거의 모든 이해/분석 요청. Pick this even when the user is casual ("봐주라", "리스트업 해줘") or only gives a filename/URL with an analysis ask — the video + "understand its content" combo is the signal. Do NOT use for: audio-only files (.mp3 등) 단순 전사, 이미지 한 장 분석, 영상 포맷 변환/압축/화질조정, 다운로드만(분석 없이), 또는 영상 자체가 아닌 댓글·메타데이터 분석. 핵심 = 영상의 시각+음성 내용을 해석하려는 의도일 때만.

video-analyze

영상은 raw 입력을 그대로 LLM에 못 넣는다. 이 스킬은 로컬 경로(프레임 추출+전사)로 그 벽을 넘는다. 데이터는 기기 밖으로 안 나간다.

2026-09-06: Gemini API 경로(경로 B, gemini_analyze.py)는 은퇴했다. 영상 전체가 구글 무료티어 API로 전송되는 구조였고, 하네스에서 API 키 경로를 전부 걷어냈다. 외부 전송 옵션 자체가 없으므로 민감도 분기 질문도 필요 없다.

민감도

경로가 로컬뿐이라 민감·수출통제·사내기밀·개인정보 영상도 그대로 투입 가능하다. 외부 전송 경로는 없다(이 스킬의 1순위 규율이었던 수출통제 게이트는 구조적으로 충족).

최초 1회: 의존성 확인

로컬 경로는 venv가 필요하다. scripts/.venv 가 없으면 먼저:

bash scripts/setup.sh

(ffmpeg 필요 + yt-dlp·faster-whisper를 pip venv에 설치. brew는 Xcode 라이선스로 막힐 수 있어 venv를 쓴다.)

로컬 경로 (유일)

python3 scripts/local_analyze.py "<URL 또는 파일경로>" --out <작업디렉토리>

주요 옵션:

• --model small (기본). 한국어 전문용어는 small 권장. base는 빠르지만 부정확, medium은 정확하나 느림.
• --hint "도메인 용어..." — 이게 한국어 전사 품질의 핵심. whisper는 동음이의 한자어(계수↔개수, 변위↔편의)와 외래 전문어(게르마늄)를 자주 틀리는데, 도메인 용어를 힌트로 주면 거의 100% 회복된다. 기본값은 기계설계 용어. 영상 주제가 다르면 그에 맞는 용어로 바꿔 줘라(예: 의료·법률·SW).
• --min-frames 4 — 씬검출이 이보다 적게 잡으면(긴 정적 영상) 균등간격으로 자동 보강한다.
• --lang ko|en|auto (기본 auto).

스크립트는 JSON을 stdout으로 낸다: frames(추출된 프레임 절대경로 배열), transcript(타임스탬프별 음성), frame_method.

그다음 네가 할 일 (중요): 스크립트는 시각 해석을 안 한다. 반환된 frames 경로들을 Read 툴로 직접 열어 화면 내용(객체·텍스트·도표·UI)을 판독하고, transcript(음성)와 합쳐서 종합 분석을 작성하라. 프레임이 시각, transcript가 청각 — 둘을 교차해야 영상을 이해한 것이다.

출력 형식

분석 결과는 하네스 규율대로 — BLUF 첫 줄, 근거 병기, 불확실한 건 표시. 특히:

• 전사에서 못 알아들은 구간, whisper 오인식 의심 구간은 ⚠️로 표시(특히 고유명사·수치·전문용어). 사용자가 영상 원본을 갖고 있으니 의심구간만 짚어주면 본인이 확인 가능.
• 화면의 수치·규격번호·PN을 프레임에서 읽을 때, 흐릿하거나 추정이면 단정하지 말 것(G4). "프레임상 ~로 보임(저해상도, 확인필요)".
• 타임스탬프는 transcript의 t(초)와 프레임을 함께 활용해 "0:14 — …" 형식으로.

함정 (PoC에서 실측한 것)