Communitygithub.com

cosmicstack-labs/mercury-agent-skills

GitHub 저장소 페이지의 15~30초 스크롤 비디오 투어를 생성합니다. ElevenLabs AI 내레이션, 단어별 자막 동기화, GSAP 스크롤 애니메이션을 사용하여 모바일 뷰포트의 전체 페이지를 캡처하고 HyperFrames CLI로 최종 MP4를 렌더링합니다.

mercury-agent-skills란 무엇인가요?

이 스킬은 개발자와 AI 에이전트 사용자가 GitHub 저장소 페이지를 소개하는 인스타그램 릴스 형식(1080x1920)의 짧은 스크롤 비디오 투어를 자동으로 제작할 수 있게 해줍니다. 작업 흐름은 GitHub 페이지의 모바일 뷰포트 전체 페이지 스크린샷을 찍는 것부터 시작하며, 이후 ElevenLabs AI 음성을 사용하여 저장소 기능과 통계를 설명하는 15~30초 분량의 내레이션을 생성합니다. 그런 다음 Whisper 또는 ElevenLabs API를 사용하여 단어 수준의 타임스탬프를 추출하고, GSAP 애니메이션 라이브러리로 제어되는 HyperFrames HTML 컴포지션에서 이러한 타임스탬프를 화면 스크롤 위치와 동기화합니다. 최종 출력물은 상단에서 하단으로 부드럽게 스크롤되는 GitHub 페이지, AI가 생성한 내레이션과 완벽하게 동기화되는 가라오케 스타일의 단어별 자막 하이라이트, 그리고 마지막 CTA(별표 또는 팔로우)를 포함하는 MP4 비디오입니다. 이 스킬은 특히 VS Code, Cursor, Codex와 같은 AI 코딩 에이전트 플랫폼을 위해 설계되었으며, website-to-hyperframes 기반 스킬에 의존합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills/tree/HEAD/categories/media-download/github-repo-tour

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

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

미리보기

스킬 README에서

mercury-agent-skills preview

문서

GitHub 저장소 투어 — 동기화된 내레이션 및 자막이 있는 스크롤 비디오

의존성: website-to-hyperframes — 시작하기 전에 로드하세요. 6단계 워크플로우와 참조 파일이 여기에 적용됩니다. 이 스킬은 단일 페이지 스크롤 투어를 내레이션 및 가시적 자막과 함께 특화합니다.


이 스킬이 생성하는 것

1080x1920 세로 비디오(인스타그램 릴스 형식)로 다음을 수행합니다:

  1. GitHub 저장소 페이지 표시 — 전체 페이지 모바일 스크린샷, 15~30초에 걸쳐 상단에서 하단으로 부드럽게 스크롤.
  2. 투어 내레이션 — ElevenLabs AI 음성이 화면에 표시된 내용을 설명하고, 스크롤 위치와 동기화.
  3. 화면에 자막 표시 — 단어별 캡션 오버레이로, 내레이터가 말할 때 각 단어가 강조 표시됨. 시청자는 들으면서 함께 읽음.
  4. CTA로 종료 — "GitHub에서 별표" 또는 "더 보려면 팔로우"와 같은 행동 유도.

핵심 결정 사항

결정값이유
해상도1080x1920인스타그램 릴스 기본 형식
길이15~30초쇼츠/릴스 참여에 최적
내레이션타이밍 결정스크롤 속도, 비트 길이, 자막 타이밍이 모두 오디오에서 파생됨
자막단어별 강조내레이터가 말할 때 각 단어가 강조 표시됨 — 가라오케 스타일 자막
폰 뷰포트전체 화면 스크롤, 베젤 없음GitHub 페이지가 전체 1080x1920 캔버스를 채움
출력 폴더github-promos/<repo>-tour/github-repo-promo 프로젝트와 같은 위치에 생성

디렉토리 구조

github-promos/
  <repo>-tour/
    index.html              ← 메인 HyperFrames 컴포지션
    package.json            ← hyperframes init에서 생성
    hyperframes.config.json ← HyperFrames 설정
    SCRIPT.md               ← 타임스탬프가 포함된 내레이션 스크립트
    assets/
      repo-page.png         ← 전체 페이지 GitHub 스크린샷 (다크 모드, 모바일 뷰포트)
      narration.mp3         ← ElevenLabs 음성 해설
    renders/                ← 생성된 MP4 파일

워크플로우

0단계: 저장소 정보 및 스크린샷 캡처

web-search 또는 fetch_url을 사용하여 저장소 메타데이터를 가져옵니다:

  • 별표, 포크, 시청자, 오픈 이슈
  • 주요 언어, 설명, 주제
  • README 요약 (프로젝트의 기능, 주요 특징)

그런 다음 screenshot 스킬을 사용하여 전체 페이지, 다크 모드, 모바일 뷰포트 스크린샷을 캡처합니다:

use_skill("screenshot")
// URL: https://github.com/{owner}/{repo}
// 전체 페이지, 다크 모드
// 뷰포트: 너비 390px (iPhone 14 모바일) — 스크린샷은
//   모바일 너비에서 페이지의 전체 높이를 캡처해야 함
// 저장 위치: github-promos/<repo>-tour/assets/repo-page.png

스크린샷 크기를 가져옵니다(스크롤 계산을 위해 픽셀 높이가 필요함):

sips -g pixelHeight github-promos/<repo>-tour/assets/repo-page.png
sips -g pixelWidth github-promos/<repo>-tour/assets/repo-page.png

1단계: 내레이션 스크립트 작성

15~30초 분량의 스크립트를 작성합니다. 스크립트는 스크롤이 진행됨에 따라 시청자가 보는 내용을 설명해야 합니다. 내레이터가 페이지를 안내합니다:

[0초~4초]  "이것은 {repo}입니다. {한 줄 설명}."
[4초~8초]  "여기가 README입니다 — 설치는 한 줄 명령어입니다."
[8초~13초] "기능 목록을 스크롤 중입니다 — {눈에 보이는 2~3가지 기능 언급}."
[13초~18초] "별표 {stars}개, 포크 {forks}개, 성장하는 커뮤니티입니다."
[18초~23초] "GitHub에서 별표를 눌러주세요. 링크는 프로필에 있습니다."
[23초~25초] "더 보려면 팔로우하세요."

스크립트 규칙:

  • 내레이터는 각 스크롤 위치에서 현재 화면에 보이는 내용을 언급합니다.
  • 총 단어 수: 5075단어 (1530초에 적절한 속도).
  • 군더더기 없음("음", "어", "보여드리겠습니다"). 모든 단어는 의미가 있어야 합니다.
  • 명확한 CTA로 끝납니다.

2단계: ElevenLabs를 통한 음성 해설 생성

curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/AZnzlk1XvdvUeBnXmlld" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "전체_스크립트_여기에",
    "model_id": "eleven_multilingual_v2",
    "voice_settings": {
      "stability": 0.35,
      "similarity_boost": 0.8,
      "style": 0.25,
      "use_speaker_boost": true
    }
  }' \
  --output github-promos/<repo>-tour/assets/narration.mp3

파일이 존재하고 크기가 0보다 큰지 확인합니다.

3단계: 전사 및 시간 매핑

오디오 생성 후, 단어 수준 타임스탬프를 추출합니다:

옵션 A: ElevenLabs 타임스탬프 (output_format: "mp3"만이 유일한 출력이 아닌 경우 API 응답과 함께 반환됨 — aligned 출력에 대한 API 문서 확인).

옵션 B: ffmpeg + Whisper 사용 (단어 타임스탬프가 포함된 로컬 전사):

# 필요한 경우 whisper 설치
pip install openai-whisper

# 단어 타임스탬프와 함께 전사
whisper github-promos/<repo>-tour/assets/narration.mp3 \
  --model base \
  --output_format json \
  --output_dir github-promos/<repo>-tour/assets/ \
  --word_timestamps True

출력은 각 단어에 start 및 end 타임스탬프가 있는 words[]를 제공합니다. 이러한 타임스탬프를 스크롤 위치에 매핑합니다.

4단계: HyperFrames 컴포지션 빌드

HyperFrames 컴포지션 아키텍처에 따라 index.html을 생성합니다:

<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=1080,height=1920"/>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap" rel="stylesheet">
<style>
  /* ── Root & Canvas ── */
  * { margin: 0; padding: 0; box-sizing: border-box; }
  #root {
    position: relative;
    width: 1080px;
    height: 1920px;
    background: #0d1117;
    font-family: 'Inter', sans-serif;
    overflow: hidden;
  }

  /* ── Scrolling Screenshot ── */
  .scroll-container {
    position: absolute;
    inset: 0;
    width: 1080px;
    height: 1920px;
    overflow: hidden;
  }
  .scroll-content {
    position: absolute;
    top: 0;
    left: 0;
    width: 1080px;
    height: VAR_IMG_H px;   /* actual screenshot height */
  }

  /* ── Subtitle Overlay ── */
  .subtitle-bar {
    position: absolute;
    bottom: 180px;
    left: 50%;
    transform: translateX(-50%);
    width: 1000px;
    text-align: center;
    z-index: 100;
  }
  .subtitle-word {
    display: inline-block;
    font-size: 42px;
    font-weight: 700;
    color: rgba(255,255,255,0.35);
    padding: 0 4px;
    transition: color 0.08s, transform 0.08s;
  }
  .subtitle-word.active {
    color: #FFFFFF;
    transform: scale(1.08);
  }
  .subtitle-word.past {
    color: rgba(255,255,255,0.65);
  }

  /* ── Scroll Progress Bar ── */
  .scroll-progress-track {
    position: absolute;
    right: 16px;
    top: 100px;
    width: 5px;
    height: 1720px;
    border-radius: 3px;
    background: rgba(255,255,255,0.1);
    z-index: 50;
  }
  .scroll-progress-thumb {
    position: absolute;
    top: 0;
    left: 0;
    width: 5px;
    height: VAR_THUMB_H px;
    border-radius: 3px;
    background: linear-gradient(180deg, #58a6ff, #3fb950);
    z-index: 51;
  }

  /* ── CTA Overlay (Beat 6-7) ── */
  .cta-overlay {
    position: absolute;
    inset: 0;
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    background: rgba(13,17,23,0.92);
    backdrop-filter: blur(8px);
    z-index: 200;
    opacity: 0;
  }
  .cta-title {
    font-size: 56px;
    font-weight: 800;
    color: #e6edf3;
    text-align: center;
  }
  .cta-subtitle {
    font-size: 32px;
    color: #8b949e;
    margin-top: 16px;
  }
  .cta-button {
    margin-top: 40px;
    padding: 18px 48px;
    background: #238636;
    color: #e6edf3;
    font-size: 28px;
    font-weight: 700;
    border-radius: 999px;
    box-shadow: 0 0 30px rgba(35,134,54,0.5);
  }
  .follow-pill {
    margin-top: 24px;
    padding: 12px 28px;
    background: rgba(22,27,34,0.8);
    border: 1px solid #30363d;
    border-radius: 999px;
    font-size: 22px;
    color: #e6edf3;
    font-weight: 600;
  }
</style>
</head>
<body>
<div id="root"
  data-composition-id="{repo}-tour"
  data-width="1080"
  data-height="1920"
  data-start="0"
  data-duration="{total_seconds}">

  <audio id="narration-audio"
    src="assets/narration.mp3"
    data-start="0"
    data-duration="{total_seconds}"
    preload="auto"></audio>

  <!-- Scrolling screenshot (full-canvas) -->
  <div class="scroll-container">
    <img class="scroll-content" src="assets/repo-page.png" />
  </div>

  <!-- Scroll progress bar -->
  <div class="scroll-progress-track">
    <div class="scroll-progress-thumb" id="scroll-thumb"></div>
  </div>

  <!-- Subtitle overlay -->
  <div class="subtitle-bar" id="subtitle-bar">
    <!-- Words injected by JS, one <span class="subtitle-word"> per word -->
  </div>

  <!-- CTA overlay (final 5s) -->
  <div class="cta-overlay" id="cta-overlay">
    <div class="cta-title">Star on GitHub</div>
    <div class="cta-subtitle">{repo description}</div>
    <div class="cta-button">github.com/{owner}/{repo}</div>
    <div class="follow-pill">@githubprojects</div>
  </div>
</div>

<script>
// ── Scroll Math ──────────────────────────────────────────
var IMG_H = /* actual screenshot height */;
var CANVAS_H = 1920;
var MAX_SCROLL = IMG_H - CANVAS_H;
var THUMB_TRACK = 1720;
var THUMB_H = Math.round(THUMB_TRACK * (CANVAS_H / IMG_H));
var THUMB_TRAVEL = THUMB_TRACK - THUMB_H;

function thumbTop(scrollY) {
  return (Math.abs(scrollY) / MAX_SCROLL) * THUMB_TRAVEL;
}

// ── Word Timestamps ─────────────────────────────────────
// Paste the word-level timestamps from Step 3 here.
// Format: [word, startSeconds, endSeconds]
var WORDS = [
  // ["This", 0.0, 0.3],
  // ["is", 0.3, 0.5],
  // ["mercury-skills", 0.5, 1.0],
  // ...
];

var TOTAL_DURATION = /* total seconds from audio */;

// ── Build Subtitle Spans ────────────────────────────────
var subtitleBar = document.getElementById("subtitle-bar");
var wordSpans = [];
WORDS.forEach(function(w, i) {
  var span = document.createElement("span");
  span.className = "subtitle-word";
  span.textContent = w[0];
  subtitleBar.appendChild(span);
  wordSpans.push(span);
});

// ── GSAP Timeline ───────────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});

// Phase 1: Scroll (0s to ~80% of total duration)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;

// Scroll from top to bottom with easing
tl.to(".scroll-content", {
  y: -MAX_SCROLL,
  duration: scrollEnd,
  ease: "none",
  onUpdate: function() {
    var progress = this.progress();
    var thumbTop = progress * THUMB_TRAVEL;
    gsap.set("#scroll-thumb", { top: thumbTop });
  }
}, 0);

// Phase 2: Word-by-word subtitle highlighting
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
  tl.call(function() {
    // Deactivate previous word
    if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
      wordSpans[currentWordIndex].classList.remove("active");
      wordSpans[currentWordIndex].classList.add("past");
    }
    // Activate current word
    wordSpans[i].classList.add("active");
    currentWordIndex = i;
  }, null, w[1]);
});

// Phase 3: CTA overlay fades in at 80%
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);

// Phase 4: Dim subtitle bar during CTA
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);

// Phase 5: Scroll progress bar fades out
tl.to(".scroll-progress-track", { opacity: 0, duration: 0.3 }, ctaStart);

window.__timelines["{repo}-tour"] = tl;
</script>
</body>
</html>

5단계: 렌더링

cd github-promos/<repo>-tour

# HyperFrames 프로젝트 설정이 없는 경우:
npx hyperframes init --example blank --non-interactive

# 린트
npx hyperframes lint

# 시각적 확인을 위한 스냅샷
npx hyperframes snapshot

# 드래프트 렌더
npx hyperframes render --quality draft

# renders/에서 출력 MP4 확인
ls -la renders/

# 모든 것이 좋아 보이면 최종 렌더
npx hyperframes render --quality standard

6단계: 전달

최종 MP4를 사용자에게 보냅니다. 다음 사항을 문의하세요:

  • 고품질 렌더 (--quality high)
  • 다른 종횡비 (가로 1920x1080)
  • 스크립트 수정

자막 시스템 — 작동 방식

자막 시스템은 이 스킬의 핵심 차별화 요소입니다. 단어별 동기화가 작동하는 방식은 다음과 같습니다:

단어 수준 타임스탬프

내레이션 오디오는 단어 수준 타임스탬프(ElevenLabs 또는 Whisper에서)로 전사됩니다. 각 단어는 WORDS 배열에 [word, startSeconds, endSeconds] 항목으로 추가됩니다.

세 가지 시각적 상태

자막 표시줄의 모든 단어에는 세 가지 CSS 상태가 있습니다:

상태클래스시각적 표현
다가오는.subtitle-word희미한 흰색 rgba(255,255,255,0.35)
활성.subtitle-word.active밝은 흰색 #FFFFFF, 약간 확대 1.08
지난.subtitle-word.past중간 흰색 rgba(255,255,255,0.65)

GSAP 타임라인은 각 단어의 startSeconds에서 함수를 호출하여 currentWord → active 및 previousWord → past로 전환합니다. 이렇게 하면 오디오에 완벽하게 동기화되는 가라오케 스타일의 단어별 하이라이트가 생성됩니다.

타이포그래피

  • 폰트: Inter 700, 42px
  • 위치: 하단 180px, 중앙 정렬, 최대 너비 1000px
  • 배경: 배경 상자 없음 — 단어가 스크롤 콘텐츠 위에 떠 있으며, 어두움/밝음/어두움 그라데이션으로 어떤 콘텐츠 위에서도 읽을 수 있음
  • Z-index: 100 (z-index 1의 스크롤 콘텐츠 위, z-index 200의 CTA 오버레이 아래)

레이아웃 고려 사항

단어는 display: inline-block 및 자연스러운 텍스트 줄 바꿈으로 배치됩니다. 더 긴 스크립트(20초 이상)의 경우 스크롤 세그먼트 사이에 나타나거나 사라지는 2~3줄 그룹으로 분할하는 것을 고려하세요:

// 스크롤 세그먼트별 단어 그룹화
var SEGMENTS = [
  { start: 0, end: 5, words: [0, 12] },     // 비트 1: 히어로
  { start: 5, end: 15, words: [13, 35] },   // 비트 2: 스크롤
  { start: 15, end: 20, words: [36, 50] },   // 비트 3: 통계
  { start: 20, end: 25, words: [51, 65] }    // 비트 4: CTA
];

전체 자막 예시 (mercury-skills 저장소, 20초, 62단어)

var WORDS = [
  ["이것은", 0.0, 0.4],
  ["mercury", 0.4, 0.7],
  ["스킬", 0.7, 1.0],
  ["저장소", 1.0, 1.3],
  ["입니다", 1.3, 1.6],
  ["AI", 1.6, 1.9],
  ["에이전트", 1.9, 2.2],
  ["도구", 2.2, 2.5],
  ["모음집", 2.5, 2.8],
  ["기능을", 2.8, 3.2],
  ["확장합니다", 3.2, 3.6],
  ["설치는", 3.6, 4.0],
  ["한", 4.0, 4.3],
  ["줄", 4.3, 4.6],
  ["명령어로", 4.6, 5.0],
  ["끝납니다", 5.0, 5.4],
  ["스크롤을", 5.4, 5.8],
  ["내리면", 5.8, 6.2],
  ["스크린샷", 6.2, 6.6],
  ["생성", 6.6, 7.0],
  ["비디오", 7.0, 7.4],
  ["투어", 7.4, 7.8],
  ["빠른", 7.8, 8.2],
  ["워크플로우가", 8.2, 8.8],
  ["보입니다", 8.8, 9.2],
  ["2800", 9.2, 9.6],
  ["개의", 9.6, 10.0],
  ["별표", 10.0, 10.4],
  ["500", 10.4, 10.8],
  ["개의", 10.8, 11.2],
  ["포크", 11.2, 11.6],
  ["활발한", 11.6, 12.0],
  ["커뮤니티", 12.0, 12.4],
  ["오픈", 12.4, 12.8],
  ["소스", 12.8, 13.2],
  ["도구", 13.2, 13.6],
  ["지금", 13.6, 14.0],
  ["시작하세요", 14.0, 14.5],
  ["GitHub에서", 14.5, 15.5],
  ["별표를", 15.5, 16.5],
  ["눌러주세요", 16.5, 17.5],
  ["링크는", 17.5, 18.5],
  ["프로필에", 18.5, 19.5],
  ["있습니다", 19.5, 20.5],
];

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬