Agent-Skills.md

Agent Skills: Twitter to Reel Converter

Convert Twitter/X posts into Instagram Reels format. Screenshots tweets, crops to show username/caption/media, creates a 9:16 vertical canvas with matching background color, and overlays downloaded video content. Works alongside twitter-media-downloader skill. Use when user wants to repurpose Twitter content for Instagram, TikTok, or other vertical video platforms.

UncategorizedID: bossjones/boss-skills/twitter-to-reel

Repository

bossjones/boss-skills
bossjonesLicense: MIT

Install this agent skill to your local

pnpm dlx add-skill https://github.com/bossjones/boss-skills/tree/HEAD/plugins/social-media/twitter-tools/skills/twitter-to-reel

Skill Files

Browse the full folder contents for twitter-to-reel.

Download Skill

Loading file tree…

plugins/social-media/twitter-tools/skills/twitter-to-reel/SKILL.md

Skill Metadata

Name
twitter-to-reel
Description
Convert Twitter/X posts into Instagram Reels format. Screenshots tweets, crops to show username/caption/media, creates a 9:16 vertical canvas with matching background color, and overlays downloaded video content. Works alongside twitter-media-downloader skill. Use when user wants to repurpose Twitter content for Instagram, TikTok, or other vertical video platforms.

Twitter to Reel Converter

Convert Twitter/X posts into Instagram Reels format (9:16 vertical video).

Dependencies

Python dependencies are installed automatically via PEP 723 inline metadata when using uv run.

Playwright and FFmpeg must be installed separately:

# Install Playwright globally via uv tool
uv tool install playwright

# Install Chromium browser for Playwright
playwright install chromium

# FFmpeg - Ubuntu/Debian
apt-get install ffmpeg

# FFmpeg - macOS
brew install ffmpeg

Note: Using uv tool install playwright makes the playwright CLI available globally, which is required for installing browser binaries.

Quick Start

Create a reel from a tweet URL (video auto-downloaded):

uv run scripts/create_reel.py "https://x.com/user/status/123" -o output.mp4

Or provide a video file explicitly:

uv run scripts/create_reel.py "https://x.com/user/status/123" video.mp4 -o output.mp4

Workflow

  1. Download (auto): If no video provided, downloads from tweet using twitter-media-downloader
  2. Screenshot: Captures the tweet using a headless browser
  3. Detect Theme: Identifies light/dark mode for background matching
  4. Canvas: Creates 1080x1920 vertical canvas with matching background
  5. Compose: Places tweet at top, overlays video in media area
  6. Export: Outputs Instagram Reels-ready MP4

Scripts

create_reel.py (Main Script)

Full pipeline from tweet URL to finished reel:

uv run scripts/create_reel.py "TWEET_URL" [VIDEO_FILE] [options]

Options: | Option | Description | |--------|-------------| | -o, --output | Output file path (default: reel_output.mp4) | | --theme | Force theme: light, dark, or auto (default: auto) | | --position | Tweet position: top, center, bottom (default: top) | | --padding | Padding around tweet in pixels (default: 40) | | --no-cleanup | Keep intermediate files | | --cookies | Path to cookies.txt for auth | | --browser | Browser to extract cookies from (recommended: firefox) | | --no-auto-download | Disable automatic video download (require explicit video path) | | --debug | Enable verbose debug output for troubleshooting |

Note: Using --browser firefox is recommended as it automatically extracts cookies from your browser session. This applies to both tweet screenshots and video downloads.

screenshot_tweet.py (Standalone)

Screenshot a tweet without video overlay:

uv run scripts/screenshot_tweet.py "TWEET_URL" -o screenshot.png

Options: | Option | Description | |--------|-------------| | -o, --output | Output file path | | --theme | Force light or dark theme | | --width | Browser viewport width (default: 550) | | --full | Capture full tweet thread | | --cookies | Cookies file for protected tweets |

compose_video.py (Standalone)

Compose video onto an existing screenshot:

uv run scripts/compose_video.py screenshot.png video.mp4 -o reel.mp4

Examples

Auto-Download (Recommended)

Simply provide the tweet URL - video is downloaded automatically:

uv run scripts/create_reel.py "https://x.com/NASA/status/123456" -o nasa_reel.mp4

With authentication for protected tweets:

uv run scripts/create_reel.py "https://x.com/user/status/123" --browser firefox -o reel.mp4

Manual Download (Advanced)

If you want more control, download separately first:

# First download the video
uv run python ../twitter-media-downloader/scripts/download.py "https://x.com/user/status/123" -o ./downloads

# Then create the reel
uv run scripts/create_reel.py "https://x.com/user/status/123" ./downloads/*.mp4 -o reel.mp4

Or provide a video file directly:

uv run scripts/create_reel.py "https://x.com/NASA/status/123456" my_video.mp4 -o reel.mp4

Customization

Dark theme with bottom positioning:

uv run scripts/create_reel.py "https://x.com/user/status/123" \
  --theme dark --position bottom -o my_reel.mp4

Screenshot Only (No Video)

uv run scripts/screenshot_tweet.py "https://x.com/user/status/123" -o tweet.png

Output Specifications

  • Resolution: 1080x1920 (Instagram Reels standard)
  • Aspect Ratio: 9:16 vertical
  • Format: MP4 (H.264 video, AAC audio)
  • Background: Matches tweet theme (white/black)

Troubleshooting

  • Tweet not loading: Use --browser firefox (recommended) or --cookies for protected accounts
  • Wrong colors: Force theme with --theme light or --theme dark
  • Video too long: Trim video before processing or use --duration
  • Playwright errors: Run uv tool install playwright && playwright install chromium
  • Debug mode: Use --debug flag for verbose output to diagnose issues