# reel

Adopt this skill: https://proskills.md/skills/other/bartimaeus-han-instagram-reel-skill

Page: https://proskills.md/skills/other/bartimaeus-han-instagram-reel-skill
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4295
sha: 46824e35a5c85543cd89ea3907bcc38839e0c945
upstream: https://github.com/bartimaeus-han/instagram-reel-skill/blob/HEAD/SKILL.md

````text
---
name: reel
description: Turn a Korean-language Instagram reel or post link into content an AI agent can read — caption, spoken words as text, and key frames as images. Use when the user shares an instagram.com/reel/, /reels/ or /p/ link, or asks to see, analyze or summarize an Instagram video (인스타 릴스, 릴스 분석, 릴스 내용).
argument-hint: <instagram link>
---

# Reel

An Instagram link can't be opened without login, and many agents can't take video or audio directly.
This skill converts a reel into things any agent can read: text (caption + transcript) and images (frames). The heavy lifting is done by `scripts/reel.py`;
your job is to make sure it can run on this machine, run it, and read what it produces.

Scope: Korean-language reels only. Speech recognition is fixed to Korean, so for a reel spoken in
another language the transcript will be nonsense — ignore it, rely on the caption and frames, and
tell the user the speech wasn't transcribed.

## 1. Check the environment (first run, or when something fails)

If `config.json` exists next to this file and the Python it points to still works, skip to step 2.

Otherwise, find out what this machine already has before installing anything:

- **Python 3.10–3.12** in an isolated environment. Look beyond PATH: conda/miniconda, venvs,
  the `py` launcher, uv. On Windows, `python` may be a Microsoft Store stub — verify it really runs.
- **ffmpeg** on PATH.
- In that environment: **yt-dlp** and **faster-whisper** (`pip install yt-dlp faster-whisper`).

Rules:
- Never install into, upgrade, or modify an existing environment the user already uses.
  Create a dedicated one (e.g. conda env or venv named `reel`).
- Pick install methods that fit this OS and what's already here (winget, brew, apt, conda, pip).
- Before installing, tell the user exactly what will be installed, from where, and roughly how big,
  and wait for a yes.
- When setup works, write `config.json` next to this file: `{"python": "<absolute path to the env's python>"}`.

## 2. Extract

Run:

```
<python from config.json> <this skill dir>/scripts/reel.py "<link>"
```

The script prints the output folder when it finishes. Options: `--every <seconds>` (frame interval,
default 1), `--model <tiny|base|small|medium>` (Whisper size, default small), `--out <dir>`.

- The first transcription downloads a Whisper model (small ≈ 500 MB). Tell the user before that happens.
- If the download fails because Instagram requires login, don't guess at cookies. Explain the
  situation and ask the user how they want to provide login cookies (e.g. a `cookies.txt` export,
  passed with `--cookies <file>`).

## 3. Read the result

The output folder contains:

- `caption.txt` — the full post text (the part under "more" included)
- `meta.json` — author, date, duration, original URL
- `transcript.txt` — spoken words with timestamps (empty if the reel has no speech)
- `frames/` — JPG frames named by timestamp, near-duplicates already removed (video posts)
- `images/` — the photos, in order (photo and carousel posts)
- `media/` — the original downloaded files (only needed to re-run with different options)

Read `caption.txt` first. The post text is often as important as the video: many creators put the
full explanation, steps, links or code in the caption and keep the video short. Treat it as primary
content, not metadata.

Then read `meta.json` and `transcript.txt`. The transcript is raw machine speech recognition: it often
mangles names, jargon, product names and English words inside the Korean speech
(e.g. "클로드다데디" for "CLAUDE.md"). Correct these yourself from context, the caption and
on-screen text — they are usually written by the creator and spelled right.

Then look at the frames or images. Near-identical frames were already dropped, so each frame is a
visual change worth seeing — view them all. If there are more than about 40, pick frames spread
across the video and where the transcript suggests something is shown on screen. Pay attention to
text on screen — tips reels often put the key point there.

Then give the user a short account of what the reel says and shows, and ask what they want to do
with it. Don't summarize, save, or act on the content beyond that unless asked.
````

## File: README.md
size: 4604
sha: b0654bc159f839e6d078401e22ccd3487a65127c
upstream: https://github.com/bartimaeus-han/instagram-reel-skill/blob/HEAD/README.md

````text
# instagram-reel-skill

인스타그램 릴스 링크를 AI 에이전트가 읽을 수 있는 **텍스트와 이미지**로 바꿔주는 [Agent Skill](https://agentskills.io)입니다.
Claude Code, Antigravity(Gemini) 등 `SKILL.md`를 지원하는 에이전트에서 쓸 수 있습니다.

```
나: https://www.instagram.com/reel/ABC123/
AI: (캡션, 음성, 화면을 읽고) 이 릴스는 ○○에 대한 내용이에요. 뭘 해볼까요?
```

AI는 인스타 링크를 열지 못하고(로그인 필요), 대부분 영상과 소리를 직접 받지 못합니다.
이 스킬은 릴스를 내려받아 다음 세 가지로 바꿔서 AI에게 넘겨줍니다.

| 원본 | 변환 결과 |
|---|---|
| 게시글 | `caption.txt` — "더보기"까지 포함한 전문 |
| 음성 | `transcript.txt` — 시간별 텍스트 (`[00:03] ...`) |
| 영상 | `frames/` — 1초마다 캡처한 장면, 거의 같은 장면은 제외 |

**요약, 저장, 프로젝트 적용 같은 후속 작업은 하지 않습니다.** 내용을 받은 뒤 대화로 요청하세요.

> **한국어 릴스 전용입니다.** 음성 인식을 한국어로 고정했습니다. 다른 언어 릴스는 캡션과 화면만 전달됩니다.

## 설치

스킬 폴더에 이 저장소를 받으면 끝입니다.

**Claude Code**
```bash
# macOS / Linux / Git Bash
git clone https://github.com/Bartimaeus-han/instagram-reel-skill ~/.claude/skills/reel
```
```powershell
# Windows PowerShell
git clone https://github.com/Bartimaeus-han/instagram-reel-skill "$HOME\.claude\skills\reel"
```

**Antigravity**
```bash
# macOS / Linux / Git Bash
git clone https://github.com/Bartimaeus-han/instagram-reel-skill ~/.gemini/config/skills/reel
```
```powershell
# Windows PowerShell
git clone https://github.com/Bartimaeus-han/instagram-reel-skill "$HOME\.gemini\config\skills\reel"
```

업데이트는 설치한 폴더에서 `git pull`을 실행하면 됩니다.

### 필요한 것

- Python 3.10–3.12
- [ffmpeg](https://ffmpeg.org)
- Python 패키지: `yt-dlp`, `faster-whisper`

**직접 설치하지 않아도 됩니다.** 처음 릴스 링크를 주면 AI가 PC를 확인하고,
없는 것만 골라 설치 방법을 제안합니다. 설치는 항상 사용자 승인을 받은 뒤 진행하며,
이미 쓰고 있는 Python 환경은 건드리지 않고 전용 환경(`reel`)을 새로 만듭니다.

첫 음성 변환 때 Whisper `small` 모델(약 500MB)을 내려받습니다.

## 사용법

에이전트에게 릴스 링크를 붙여넣으면 됩니다. Claude Code에서는 직접 부를 수도 있습니다.

```
/reel https://www.instagram.com/reel/ABC123/
```

옵션은 말로 요청해도 됩니다.

| 옵션 | 기본값 | 예시 요청 |
|---|---|---|
| `--every <초>` | 1 | "2초 간격으로 봐줘" |
| `--model <tiny\|base\|small\|medium>` | small | "음성을 더 정확하게" |
| `--out <폴더>` | `~/reels/<게시물코드>` | "결과를 ○○에 저장해줘" |
| `--cookies <파일>` | 없음 | 로그인이 필요한 게시물일 때 |

### 결과 폴더

```
~/reels/<게시물코드>/
├── caption.txt      게시글 전문
├── meta.json        작성자, 날짜, 길이, 링크
├── transcript.txt   시간별 음성 텍스트
├── frames/          장면 이미지 (0015s.jpg = 15초)
├── images/          사진·캐러셀 게시물의 사진
└── media/           원본 파일
```

스크립트만 따로 실행할 수도 있습니다.

```bash
python scripts/reel.py "https://www.instagram.com/reel/ABC123/"
```

## 알려진 한계

- **한국어 외 언어**는 음성 텍스트를 만들지 않습니다.
- **음성 인식 오류**가 있습니다. 특히 한국어 말 속의 영어 단어(예: "CLAUDE.md" → "클로드다데디").
  AI가 캡션과 화면 글자를 보고 교정하도록 `SKILL.md`에 지시해 두었습니다.
- **로그인이 필요한 게시물**은 쿠키 파일(`cookies.txt`)을 직접 준비해 `--cookies`로 넘겨야 합니다.
  AI가 브라우저 쿠키를 임의로 가져오지 않도록 설계했습니다.
- **사진만 있는 게시물**은 yt-dlp가 내려받지 못할 수 있습니다.
- 결과 폴더(`~/reels/`)는 자동으로 지워지지 않습니다.

## 주의

인스타그램 콘텐츠의 저작권은 각 크리에이터에게 있습니다.
이 스킬은 **개인적인 참고와 학습 용도**로 만들었습니다. 내려받은 영상이나 텍스트를
재게시하거나 배포하지 마세요. 인스타그램 이용약관을 확인하고 책임 있게 사용해 주세요.

## 라이선스

[MIT](LICENSE)
````

## File: scripts/reel.py
size: 5701
sha: 1d136ff5e61fb3743492df97944dd361bb065a87
upstream: https://github.com/bartimaeus-han/instagram-reel-skill/blob/HEAD/scripts/reel.py

```text
"""Turn an Instagram reel or post into files Claude can read.

Output folder (default ~/reels/<shortcode>):
  caption.txt     full post text
  meta.json       author, date, duration, url
  transcript.txt  spoken words, one line per segment: [mm:ss] text
  frames/         one JPG every N seconds, named by timestamp (video posts)
  images/         photos in order (photo / carousel posts)
  media/          the original downloaded files
"""

import argparse
import json
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path

# Hugging Face (where the Whisper model comes from) warns about login and Windows symlinks.
# Both are harmless here; hide them so real errors stand out. Must be set before importing.
os.environ.setdefault("HF_HUB_DISABLE_SYMLINKS_WARNING", "1")
os.environ.setdefault("HF_HUB_VERBOSITY", "error")

import av
import yt_dlp
from faster_whisper import WhisperModel

VIDEO_EXTS = {".mp4", ".mov", ".webm", ".mkv"}
IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".heic"}

def log(msg):
    print(msg, file=sys.stderr, flush=True)

def shortcode(url):
    m = re.search(r"instagram\.com/(?:[^/]+/)?(?:reels?|p|tv)/([^/?#]+)", url)
    return m.group(1) if m else "post"

def download(url, media_dir, cookies):
    opts = {
        "outtmpl": str(media_dir / "%(autonumber)02d.%(ext)s"),
        "quiet": True,
        "no_warnings": True,
        "noprogress": True,
    }
    if cookies:
        opts["cookiefile"] = cookies
    with yt_dlp.YoutubeDL(opts) as ydl:
        return ydl.sanitize_info(ydl.extract_info(url, download=True))

def seconds(video):
    with av.open(str(video)) as f:
        return round(f.duration / av.time_base, 1) if f.duration else None

def extract_frames(video, frames_dir, every, prefix):
    # fps: one frame every N seconds. mpdecimate: drop frames that barely differ from the
    # previous kept one, so a static slide becomes one image instead of dozens.
    # -frame_pts names each file by its timestamp in N-second units, which survives the drops.
    subprocess.run(
        ["ffmpeg", "-loglevel", "error", "-i", str(video),
         "-vf", f"fps=1/{every},mpdecimate,scale='min(720,iw)':-2",
         "-fps_mode", "vfr", "-frame_pts", "1", "-q:v", "3",
         str(frames_dir / f"{prefix}tmp_%d.jpg")],
        check=True,
    )
    for f in frames_dir.glob(f"{prefix}tmp_*.jpg"):
        t = int(f.stem.rsplit("_", 1)[1]) * every
        f.rename(frames_dir / f"{prefix}{t:04d}s.jpg")

def transcribe(model, video):
    segments, _ = model.transcribe(str(video), language="ko", vad_filter=True)
    return [f"[{int(s.start) // 60:02d}:{int(s.start) % 60:02d}] {s.text.strip()}" for s in segments]

def main():
    sys.stdout.reconfigure(encoding="utf-8")
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("url")
    p.add_argument("--every", type=int, default=1, help="seconds between frames (default 1)")
    p.add_argument("--model", default="small", help="Whisper model: tiny, base, small, medium (default small)")
    p.add_argument("--out", type=Path, help="output folder (default ~/reels/<shortcode>)")
    p.add_argument("--cookies", help="Netscape cookies.txt for posts that need login")
    args = p.parse_args()

    out = args.out or Path.home() / "reels" / shortcode(args.url)
    media, frames, images = out / "media", out / "frames", out / "images"
    for d in (media, frames, images):
        shutil.rmtree(d, ignore_errors=True)
    media.mkdir(parents=True)

    log("Downloading...")
    try:
        info = download(args.url, media, args.cookies)
    except yt_dlp.utils.DownloadError as e:
        log(f"Download failed: {e}")
        log("If this post needs login, rerun with --cookies <cookies.txt>.")
        sys.exit(1)

    entries = [e for e in (info.get("entries") or [info]) if e]
    first = entries[0]

    caption = info.get("description") or first.get("description") or ""
    (out / "caption.txt").write_text(caption, encoding="utf-8")

    files = sorted(media.iterdir())
    videos = [f for f in files if f.suffix.lower() in VIDEO_EXTS]
    photos = [f for f in files if f.suffix.lower() in IMAGE_EXTS]

    meta = {
        "url": args.url,
        "author": first.get("uploader") or first.get("channel"),
        "author_id": first.get("uploader_id"),
        "date": first.get("upload_date"),
        "duration": sum(seconds(v) or 0 for v in videos) or None,
        "videos": len(videos),
        "images": len(photos),
    }
    (out / "meta.json").write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")

    if photos:
        images.mkdir()
        for i, f in enumerate(photos, 1):
            shutil.copy(f, images / f"{i:02d}{f.suffix.lower()}")

    lines = []
    if videos:
        frames.mkdir()
        log(f"Loading Whisper model '{args.model}' (the first run downloads it)...")
        model = WhisperModel(args.model, device="cpu", compute_type="int8")
        for n, video in enumerate(videos, 1):
            prefix = f"v{n}_" if len(videos) > 1 else ""
            log(f"Video {n}/{len(videos)}: extracting frames...")
            extract_frames(video, frames, args.every, prefix)
            log(f"Video {n}/{len(videos)}: transcribing...")
            if len(videos) > 1:
                lines.append(f"--- video {n} ---")
            try:
                lines += transcribe(model, video)
            except Exception as e:  # e.g. a video with no audio track
                log(f"  no transcript: {e}")
    (out / "transcript.txt").write_text("\n".join(lines), encoding="utf-8")

    print(out)

if __name__ == "__main__":
    main()
```

## File: .gitignore
size: 129
sha: b6b176ca93e764f95989832d23d4f4ae0160a610
upstream: https://github.com/bartimaeus-han/instagram-reel-skill/blob/HEAD/.gitignore

```text
# Machine-specific: written by the agent on first run, points to this PC's Python
config.json

# Python cache
__pycache__/
*.pyc
```

## File: LICENSE
size: 1071
sha: e678ce98ce0590311c5eb7744504bc79e983e2fd
upstream: https://github.com/bartimaeus-han/instagram-reel-skill/blob/HEAD/LICENSE

```text
MIT License

Copyright (c) 2026 Bartimaeus-han

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
