나만의 Agent skills ① — YouTube 자막 생성

이번 글에서는 제가 직접 만들어서 상당히 유용하게 사용하고 있는 Skill을 소개하려고 합니다. 바로 영상에서 자막을 생성하는 Skill입니다.

1. 영상에 자막이 필요한 이유

저는 유튜브로 상당히 많은 콘텐츠를 소비합니다. 그 중에서도 Software engineering, AI 관련된 영상을 특히 많이 봅니다. 이런 영상들은 대부분 화자가 영어로 말하기 때문에 자막이 없으면 이해하기 어려운 경우가 많습니다. 또는 한국어로 자막이 제공되더라도 너무 기계번역투가 심한 경우가 많습니다.

유튜브는 실시간 번역을 지원하지만 제가 원하는 수준의 자막 품질은 여전히 아니고 또 실시간 번역이어서인지 자막이 생성되는 시점과 화자의 말하는 시점이 어긋나는 경우가 종종 발생합니다.

안 그래도 이해하기 힘든 영상 내용인데 언어의 장벽 없이 온전히 제가 제일 잘하는 '한국어'로 보고 싶다는 생각을 자주 했었습니다.

2. 1차 시도 - 실패한 경험

대략 2년 전에 저는 유튜브 영상으로부터 한국어 자막을 만드는 소프트웨어를 직접 만들기 시작했습니다.

자세한 내용은 이미 블로그에 공개했으니 관심 있으신 분들은 한 번 읽어보셔도 좋겠습니다.

동영상 자막 자동 번역기 만들기

대략적인 동작 과정은 다음과 같았습니다.

유튜브 영상 링크를 제공
프로그램이 영상을 다운로드 (yt-dlp 활용)
GCP Speech to Text API를 이용해서 음성을 텍스트로 변환
변환된 텍스트를 Gemini API를 통해 한국어로 번역 시도
번역 결과물로 SRT 생성 (자막 파일)
(선택) 자막을 영상에 합성 (FFmpeg 활용)

솔직히 당시 이 과정을 통해 만들어진 자막 품질은 썩 좋지 못했습니다. 제가 프로그램을 잘 만들지 못한 탓도 있겠지만 당시의 LLM(Gemini)가 영어를 한국어로 매끄럽게 번역하는데 한계가 있지 않았나 싶습니다.

또한 GCP STT(Speech-to-Text) API의 성능과 속도가 제가 원하는 수준이 아니었습니다. 특히 화자의 발음이 불분명하여 고유 명사가 의미가 다른 단어로 인식되는 경우가 종종 발생했고 이것은 영상 전체를 이해하는 데는 큰 문제가 되지 않았지만 미묘하게 다른 맥락을 만들어 내는 경우가 많았습니다.

결국 저는 완성도 높은 자막을 얻기 위해서 다른 방법을 찾아야 했습니다.

3. 2차 시도 - Claude Code와 같이

제가 직접 만든 프로그램도 나름 쓸만했습니다. 그래서 그냥저냥 사용해오다가 불현듯 지난 7월에 이런 생각이 들었습니다.

그냥 Claude Code한테 유튜브 영상 하나 툭 던져주면 내가 원하는 자막을 뚝딱 만들어주지 않을까?

그래서 실제로 시도를 해보았습니다. 유튜브 영상 하나를 던져주고 한국어 자막을 만들어 달라는 요청을 해보았습니다. 물론 처음부터 원하는 결과를 바로 얻지는 못했습니다. Claude Code는 영상을 이해할 수 있는 능력도 없거니와 음성 파일에서 텍스트를 전사하는 기능이 없기 때문입니다.

그래서 Claude와 몇 번의 소통을 통해 아래와 같은 절차를 정의할 수 있었습니다.

사람이 유튜브 영상 링크를 제공한다
Skill이 나머지 모든 과정을 자동 수행한다
- 영상 다운로드
- 영상으로부터 화자의 발화문을 전사(transcribe)
- 전사한 텍스트를 한국어로 번역
최종적으로 한국어 자막(SRT/VTT) 파일을 생성한다

전체 과정에서 Claude가 스스로 할 수 없는 것은 발화문 전사 기능 뿐입니다. Claude는 2가지 선택지 중에 하나를 고를 수 있다고 안내했습니다.

로컬에 전사 모델 설치
클라우드 기반 전사 모델 사용

고민 끝에 저는 로컬에 전사 모델을 설치하는 선택지를 골랐습니다. 굳이 돈을 내고 전사 서비스를 이용할 필요가 있을까 싶기도 했고 로컬에 설치할 수 있는 작은 모델로도 충분한 성능이 나온다는 후기도 보았기 때문입니다.

제가 선택한 모델은 OpenAI에서 공개한 Whisper 기반의 faster-whisper 입니다.

SYSTRAN/faster-whisper

저는 맥북을 사용 중이기 때문에 GPU 없이 CPU만으로 구동시킬 수 있는 로컬 모델이 필요했습니다. 그래서 보다 가볍고 빠르게 동작하는 이 모델을 선택한 것입니다.

유일하게 Claude가 혼자서 할 수 없는 부분을 채웠기 때문에 나머지 과정은 일사천리로 진행할 수 있었습니다.

Claude Code로 모든 프로그램 작성이 순조롭게 완료되었고, 테스트 용도로 아래 유튜브 영상을 입력했습니다.

7월 당시의 Opus 모델로 돌린 결과 13분 길이의 영상의 한글 자막을 만드는 데 대략 30분 정도 소요되었습니다. 이것은 전사 모델 다운로드에 10분을 사용한 것과 코드 문제를 Claude Code가 스스로 고치는 데 걸린 시간을 포함한 것입니다. 하나의 영상 링크를 3번 정도 돌려서 자막의 품질을 계속 끌어올렸습니다.

그리고 코드가 어느 정도 안정되었다고 판단되어 다른 영상 링크로 자막을 만들게 해봤습니다.

영상 길이: 19분

구간 별 소요 시간

구간	소요	내용
환경 준비	약 1분	로컬 전사 모델 설치 확인
영상 다운로드	약 10초	제목 조회와 다운로드
영어 받아쓰기	약 3분 30초	Whisper small.en 모델 사용
한국어 번역	약 6분	Claude 모델로 직접 번역(영문 → 한국어)
자막 생성 + 싱크 확인	약 1분	SRT/VTT 생성, 자막과 프레임 확인

이 과정을 통해 만들어진 자막의 품질은 놀라울 정도로 좋았습니다. 번역투 느낌도 들지 않고 자연스럽게 느껴지도록 번역이 되었습니다. 또한 화자가 말하는 시점과 번역된 자막이 화면에 뜨는 '싱크' 측면에서도 완벽했습니다.

4. Skill로 전환하기

프로그램이 잘 작동하게 된 이후로 적어도 하루에 하나의 영상은 꼭 자막을 번역해서 보게 되었습니다.

그런데 매번 Claude Code를 실행하고 프롬프트를 적어야 하는 불편함이 있었습니다. 이 대화 세션에서 어떤 작업을 해야 하는지, 어떤 스크립트가 어느 위치에 있는지 등을 매번 알려줘야 했던 것입니다.

이런 상황에 맞는 기능이 Skills입니다.

Skill은 Claude Code가 특정 작업을 할 때 따라야 할 절차를 미리 적어 둔 문서입니다. 폴더 하나에 SKILL.md 파일을 두고, 거기에 "이 Skill은 언제 쓰는지"와 "어떤 순서로 무엇을 하는지"를 적습니다. 필요하면 같은 폴더에 스크립트나 참고 문서를 함께 넣을 수도 있습니다.

youtube-subtitle/
  ├── SKILL.md      # 이름, 설명, 작업 절차
  └── scripts/      # 다운로드·전사 등에 쓰는 스크립트

그래서 youtube-subtitle 라는 신규 Skill을 만들었습니다. 이를 통해 매번 어떤 작업을 해야 하는지 지정해줘야 하는 불편함이 사라졌습니다. Claude Code를 실행하고 /youtube-subtitle 명령어와 함께 유튜브 링크만 제공하면 나머지는 SKILL.md 절차에 따라서 자막이 만들어지는 것입니다.

Skill로 관리하는 이점은 하나 더 있습니다. 직접 프롬프트를 입력할 때는 자막 파일만 만들고 '싱크' 확인을 누락하는 경우가 더러 있었습니다. 이 경우 영상을 볼 때, 조금씩 자막이 밀리거나 너무 앞에 배치되는 문제가 있습니다. 하지만 SKILL.md 파일에 명확하게 최종 단계에서 싱크 확인을 하게끔 명시한 이후로는 이러한 문제가 사라졌습니다. 즉, 최종 결과물의 품질이 균일해진 것입니다.

5. 자막이 만들어지는 과정

이제 이 Skill이 작동하는 절차에 대해 간단히 설명해보겠습니다.

/youtube-subtitle 명령어와 함께 유튜브 영상 링크 제공
환경 준비 (스크립트, 처음 한 번만): faster-whisper와 yt-dlp 설치
영상 다운로드 (스크립트): yt-dlp로 영상을 받아 영상 제목으로 된 폴더에 저장
음성 언어 확인 (Claude): 영상 중간 2분만 먼저 전사해 보고, 영어인지 판단해서 사용할 전사 모델 선택
영어 전사 (스크립트): faster-whisper로 음성을 영어 텍스트로 옮기고, 문장마다 시작·끝 시간을 기록
한국어 번역 (Claude): 전사본 전체를 읽고 문맥에 맞게 번역. 끊긴 문장을 이어서 번역하고, 잘못 들린 용어도 이 단계에서 바로 잡음
번역 검수 (Jev, 선택): 외부 검수 도구가 의심스러운 부분을 짚고, Claude가 그 부분을 확인해 수정
자막 파일 생성 (스크립트): 번역문에 원래 시간 정보를 붙여 SRT/VTT 파일 생성
싱크 확인 (Claude): 영상 몇 장면에 자막을 입혀 캡처한 뒤, 말하는 내용과 자막이 맞는지 직접 확인

4번, 6번, 7번, 9번 작업만 LLM이 개입하고 나머지는 전부 파이썬 스크립트로 동작합니다.

7번 단계 Jev로 번역을 검수하는 것은 선택 사항입니다. Jev는 TypeSafe가 공개한 모델로, 글을 생성하는 대신 정해진 형식의 판정만 돌려줍니다. 질문과 선택지를 보내면 그중 하나를 고르고, 그 판단이 맞을 확률(확신도)을 함께 알려 주는 식입니다. 텍스트를 생성하지 않아서 출력 토큰 비용이 없고, 입력 토큰도 10억 개당 42달러 수준이라 수백 번을 호출해도 비용 부담이 적습니다. 사용하려면 TypeSafe API 키가 필요하고, 키가 없으면 이 단계를 건너뛰고 바로 자막 파일을 만듭니다.

이 Skill에서 Jev는 영어 전사본과 한국어 번역문을 텍스트끼리 비교해서, 번역이 원문을 제대로 옮겼는지 판정합니다.

Jev를 사용하는 방식

자막을 3~12개 단위의 묶음으로 나누고, 앞뒤에 문맥용 자막을 2개씩 붙여서 보냅니다. Jev는 묶음마다 아래 다섯 가지 질문에 clear(문제 없음), issue(문제 있음), uncertain(판단 불가) 중 하나와 확신도를 돌려줍니다.

항목	타입	묻는 내용
누락	choice	원문의 중요한 의미가 빠졌는가 (“It's fast, but it costs three times more.” → "빠릅니다.")
추가	choice	원문에 없는 주장을 덧붙였는가 (“We moved to Postgres.” → "성능 문제 때문에 Postgres로 옮겼습니다.")
의미 변화	choice	부정, 조건, 인과, 수량, 행위자가 바뀌었는가 (“You don’t need to restart the server.” → "서버를 재시작해야 합니다.")
흐름	choice	이어지는 자막을 함께 읽을 때 문장이 자연스러운가 (한 문장을 두 자막으로 나눴는데 이어 읽으면 어순이 꼬여 뜻이 통하지 않는 경우)
용어	choice	전문 용어, 코드 식별자, 고유명사를 잘못 옮겼는가 (`printNums` → "숫자 출력 함수", 용어집의 "상태 유지형"을 "상태가 있는"으로 옮긴 경우)

빠르게 수백 번의 API를 호출하여 choice API(정해진 선택지 중 하나를 고르는 형식)를 통해 번역의 품질을 검수합니다. issue나 uncertain, 또는 확신도가 0.7 미만인 clear가 나오면 그 묶음이 "다시 볼 후보"가 됩니다. Jev는 번역을 고치지 않고, 고칠지는 Claude가 결정합니다.

6. Skills repository

요새는 이 정도 수준의 소프트웨어를 꽤나 쉽게 만들 수 있게 되었습니다. 그래서 본인에게 필요한 기능을 직접 구현하고 관리하는 것이 쉬워졌지만 그래도 이 Skill을 공개하면 필요한 분들이 사용해볼 수 있을 것 같다는 생각을 하게 되었습니다.

Matt Pocock의 Skills repository에 영감을 받아 저만의 개인 Skills repository를 만들어 공개합니다. 지금은 youtube-subtitle skill 하나만 있지만 추후에 제가 만들어서 개인적으로 사용 중인 skill들을 하나씩 추가해나갈 예정입니다.

Jinyoung's Skills: Skills repository

위 repository 링크를 열면 자세한 설치 방법이 안내되어 있으니 직접 사용해보실 분들은 한 번 살펴보시길 바랍니다.

Skill 테스트

참고로 이 Skill은 다음 환경에서 테스트되었습니다:

디바이스 1: iMac

iMac (Retina 5K, 27형, 2019) / 6코어 Intel Core i5 3.0GHz / 메모리 40GB / macOS 15.7
12분 길이 영상의 자막을 만드는 데 18분이 걸렸습니다. (모델: Sonnet 5.5, Effort: High)

디바이스 2: MacBook Pro

MacBook Pro 14 (M3 Pro)
20분 내외 영상의 자막을 만드는 데 12분이 걸린 경우도 있고 길게는 34분 걸린 경우도 있습니다. 이것은 영상의 길이보다는 전사문의 분량에 따라 소요시간이 좌우되는 듯 보입니다.
가장 긴 영상은 3시간 5분 길이였고, 99분이 걸렸습니다. (모델: Opus 5, Effort: High)

프롬프트로 출력 언어를 지정하면 해당 언어의 자막이 만들어지긴 하지만 그래도 현재의 Skill은 한국어에 특화되어 있습니다. 그래서 한국어가 아닌 다른 언어로 자막 파일을 만들었을 때 얼마나 매끄럽게 잘되는가, 사람이 읽을 때 한 번에 파악될 수 있도록 분량이 잘려서 배치되는가까지는 테스트하지 못했습니다.
분명히 언어별로 다른 점들이 있을 것입니다. 추후에 이 Skill을 사용하는 다른 언어권 사용자들이 각 언어에 알맞은 특화된 지시문을 추가하여 PR을 만들어주길 기대해봅니다. 😺

나만의 Agent skills ① — YouTube 자막 생성

1. 영상에 자막이 필요한 이유

2. 1차 시도 - 실패한 경험

3. 2차 시도 - Claude Code와 같이

4. Skill로 전환하기

5. 자막이 만들어지는 과정

Jev를 사용하는 방식

6. Skills repository

Skill 테스트

어떤 모델과 Effort를 선택하는 게 좋을까요?

주의할 점

7. 한국어 말고 다른 언어는?

개선할 점들