Skip to content
Back to search

instagram-thread-carousel

SkillGitHubIncomplete

Claude Code skill: Turn text threads into Instagram carousel slides styled as tweet/X post screenshots

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samin12--instagram-thread-carousel/badge.svg)](/listings/samin12--instagram-thread-carousel)

HTML

<a href="/listings/samin12--instagram-thread-carousel"><img src="/api/listings/samin12--instagram-thread-carousel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 391 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: instagram-thread-carousel
  3. description: Use when the user wants to turn a text thread into an Instagram carousel that looks like tweet/X post screenshots. Generates slide images with profile pic, name, verified badge, handle, and tweet text. Supports embedded images and combining short tweets on one slide.
  4. ---
  5. # Thread-to-Carousel Generator
  6. Convert a text thread into Instagram carousel slides styled as tweet/X post mockups. Each slide renders a clean tweet card with profile picture, display name, verified badge, handle, and the tweet text. Optionally embed images in tweets and combine short tweets 2-per-slide.
  7. ---
  8. ## Process
  9. ### Step 1: Gather the Thread
  10. Get the thread content from the user. They may:
  11. - Paste a thread of text directly
  12. - Provide a topic and ask you to write the thread
  13. - Share screenshots or existing tweets to recreate
  14. If writing the thread, use the voice and tone from `CLAUDE.md`. Each tweet in the thread should be a self-contained thought that flows into the next.
  15. ### Step 2: Gather Profile Info
  16. Ask for anything not already known:
  17. 1. **Display name** - the bold name shown on each tweet
  18. 2. **Handle** - e.g., `@itstylergermain`
  19. 3. **Verified** - show the blue checkmark? (default: true)
  20. 4. **Headshot** - path to profile photo. List available files with `ls .claude/skills/instagram-thread-carousel/headshots/` and let the user pick, or use the first one found.
  21. If `CLAUDE.md` has been personalized (audit has been run), pull the name and handle from there.
  22. ### Step 3: Break the Thread into Slides
  23. Rules for slide layout:
  24. **One tweet per slide (default):**
  25. - Any tweet with an embedded image gets its own slide
  26. - Tweets longer than ~200 characters get their own slide
  27. - The first tweet (hook) always gets its own slide
  28. - **The title slide (slide 1) should ALWAYS have an image.** A strong image on the first slide is critical for stopping the scroll.
  29. **Two tweets per slide:**
  30. - Combine consecutive short tweets (under ~150 characters each, no images) onto one slide
  31. - This keeps the carousel compact and scannable
  32. - A light gray divider line separates the two tweets
  33. Walk through the thread and decide the slide breakdown. Present it to the user before generating:
  34. ```
  35. Slide 1: Tweet 1 (hook) - own slide
  36. Slide 2: Tweet 2 + Tweet 3 - combined (both short)
  37. Slide 3: Tweet 4 - own slide (has image)
  38. Slide 4: Tweet 5 + Tweet 6 - combined (both short)
  39. Slide 5: Tweet 7 (CTA) - own slide
  40. ```
  41. ### Step 4: Handle Images
  42. Images make carousels significantly more engaging. For each tweet that could benefit from a visual, determine how to source the image:
  43. **User-provided images:**
  44. - The user provides file paths or URLs directly
  45. - If they provide URLs, download the images to the carousel's `ref/` subfolder first
  46. **Search for images with Tavily:**
  47. If the user doesn't provide images (or asks you to find them), use the Tavily image search script to find relevant visuals:
  48. ```bash
  49. python3 .claude/skills/instagram-thread-carousel/scripts/tavily-image-search.py "search query" workspace/<date>/<title>/ref --count 5
  50. ```
  51. This downloads images and creates a manifest JSON. Review the downloaded images and pick the best ones for each tweet. Good search queries are specific - e.g., "YouTube thumbnail example tech channel" not just "thumbnail".
  52. Requires `TAVILY_API_KEY` in `.env`. If not set, skip image search and proceed with text-only slides.
  53. **Search for GIFs with Giphy:**
  54. When the carousel calls for animated content (reaction GIFs, demonstrations, etc.):
  55. ```bash
  56. python3 .claude/skills/instagram-thread-carousel/scripts/giphy-search.py "search query" workspace/<date>/<title>/ref --count 5
  57. ```
  58. Downloads GIFs and creates a manifest JSON. The thread-to-carousel script automatically handles animated GIFs by outputting both an MP4 (for Instagram) and a PNG (static preview).
  59. Requires `GIPHY_API_KEY` in `.env`.
  60. **Website screenshots:**
  61. When the carousel is about a website, product, or tool, take a fresh screenshot instead of relying on Tavily (which often returns outdated images):
  62. ```bash
  63. python3 .claude/skills/instagram-thread-carousel/scripts/website-screenshot.py "https://example.com" workspace/<date>/<title>/ref/homepage.png --width 1280 --height 800
  64. ```
  65. Options: `--width` and `--height` set the viewport, `--full-page` captures the entire scrollable page. Requires `playwright` (`pip install playwright && playwright install chromium`).
  66. Always prefer a live screenshot over a Tavily image search result when the carousel is about a specific website or product.
  67. **Website recordings with Steel:**
  68. When you need a video recording of browsing a website (for animated carousel slides or reference), use the Steel browser:
  69. ```bash
  70. python3 .claude/skills/instagram-thread-carousel/scripts/steel-browse.py browse-plan.json workspace/<date>/<title>/ref
  71. ```
  72. Create a `browse-plan.json` with a list of actions:
  73. ```json
  74. {
  75. "viewport": { "width": 1920, "height": 1080 },
  76. "actions": [
  77. { "action": "navigate", "url": "https://example.com", "label": "Open homepage", "wait": 2000 },
  78. { "action": "click", "selector": "button.cta", "label": "Click CTA", "wait": 1500 },
  79. { "action": "click_at", "x": 960, "y": 540, "label": "Click center", "wait": 1000 },
  80. { "action": "scroll", "y": 500, "label": "Scroll down", "wait": 1000 },
  81. { "action": "hover", "selector": ".card", "label": "Hover card", "wait": 1000 },
  82. { "action": "type", "selector": "input.search", "text": "query", "label": "Type search", "wait": 1000 },
  83. { "action": "keyboard_type", "text": "hello world", "label": "Type text", "wait": 1000 },
  84. { "action": "keyboard_press", "key": "Enter", "label": "Press Enter", "wait": 1000 }
  85. ]
  86. }
  87. ```
  88. Outputs `recording.mp4` and `moments.json` to the output directory. Requires `STEEL_API_KEY` in `.env` and `pip install steel-sdk playwright`.
  89. **Image rules:**
  90. - Images appear below the tweet text with rounded corners
  91. - Tweets with images always get their own slide (the image needs the space)
  92. - Prefer landscape or square images - very tall images eat too much slide space
  93. - Screenshots, product shots, and UI mockups work best for this format
  94. ### Step 5: Generate the Config
  95. Each carousel gets its own folder under `workspace/` organized by date and title. Pick a short, descriptive name based on the topic (e.g., `thumbnail-generator`, `claude-youtube`, `ai-agents-101`).
  96. Folder structure:
  97. ```
  98. workspace/<date>/<title>/
  99. ├── config.json # Slide config
  100. ├── ref/ # Reference images used in slides
  101. │ ├── screenshot.png
  102. │ └── ...
  103. ├── slide-01.png # Generated slides
  104. ├── slide-02.png
  105. └── ...
  106. ```
  107. Create the config file at `workspace/<date>/<title>/config.json`:
  108. ```json
  109. {
  110. "profile": {
  111. "name": "Display Name",
  112. "handle": "@handle",
  113. "verified": true,
  114. "headshot": ".claude/skills/instagram-thread-carousel/headshots/tyler-headshot.png"
  115. },
  116. "theme": "light",
  117. "slides": [
  118. {
  119. "tweets": [
  120. {
  121. "text": "This is the first tweet.\n\nIt can have multiple paragraphs.\n\nUse \\n for line breaks.",
  122. "image": null
  123. }
  124. ]
  125. },
  126. {
  127. "video": "workspace/<date>/<title>/ref/demo.mp4"
  128. },
  129. {
  130. "tweets": [
  131. { "text": "Short tweet one.", "image": null },
  132. { "text": "Short tweet two.", "image": null }
  133. ]
  134. },
  135. {
  136. "tweets": [
  137. {
  138. "text": "Tweet with an image below it.",
  139. "image": "workspace/<date>/<title>/ref/screenshot.jpg"
  140. }
  141. ]
  142. }
  143. ]
  144. }
  145. ```
  146. **Config options:**
  147. - `theme` - `"light"` (white background, dark text) or `"dark"` (black background, light text). Default: `"light"`.
  148. **Video slides:**
  149. - Use `"video": "path/to/video.mp4"` at the slide level (no `tweets` needed)
  150. - The script copies the MP4 to the output as `slide-XX.mp4` and extracts a `slide-XX.png` preview
  151. - Instagram carousels support mixing images and videos - use video slides for screen recordings, demos, or animated content
  152. - Use the screen-demo skill or Steel browser recordings to create polished demo videos, then reference the output MP4 in the carousel config
  153. - Video slides do NOT render tweet-style cards - they're raw video files for Instagram
  154. **Text formatting tips:**
  155. - Use `\n` for line breaks within a tweet
  156. - Use `\n\n` for paragraph breaks (adds extra spacing)
  157. - Arrow bullets work: `→ Point one\n→ Point two`
  158. - Emoji and special characters are supported (font-dependent)
  159. ### Step 6: Run the Script
  160. ```bash
  161. python3 .claude/skills/instagram-thread-carousel/scripts/thread-to-carousel.py workspace/<date>/<title>/config.json workspace/<date>/<title>
  162. ```
  163. This generates numbered PNG files: `slide-01.png`, `slide-02.png`, etc. inside the carousel folder.
  164. ### Step 7: Present the Results
  165. Show the user:
  166. 1. How many slides were generated
  167. 2. The folder path where everything is saved
  168. 3. Offer to adjust - re-run with different text, different slide breakdown, or different images
  169. Read and display the generated slide images so the user can see them inline.
  170. **Animated slides:** When a slide contains an animated GIF, the script outputs both an `.mp4` (full-color video for Instagram) and a `.png` (a static preview of the first frame). **Always display the `.png` preview** - never try to read the `.mp4` file directly. Tell the user the MP4 version is saved alongside it for posting.
  171. ---
  172. ## Text Style Guide
  173. When writing threads for the user, follow these patterns from high-performing tweet-style carousels:
  174. ### Hook Tweet (Slide 1) - The Most Important Slide
  175. The hook makes or breaks the entire carousel. A bad hook means zero impressions; a great hook stops the scroll. The thread hook must work as a **standalone tweet** - if it wouldn't perform on its own, it won't perform as a carousel opener either.
  176. **Core principles:**
  177. - The hook must **stop someone from scrolling**. If it doesn't interrupt, nothing else matters.
  178. - The first line and second line must **connect logically**. A disconnected transition kills the hook.
  179. - **Match market awareness.** Audiences are desensitized - "I make $10K/month" or "I'm a millionaire" doesn't stop anyone anymore. The claim has to be genuinely surprising for the current landscape.
  180. - **Cast a wide net AND deliver on it.** A broad hook only works if the content actually applies to the wide audience you promised.
  181. **Proven hook frameworks (master these first, then experiment):**
  182. 1. **Borrowed Authority** - Open with a well-known person's name, then follow with a surprising claim or hot take. The name grabs attention; the claim holds it.
  183. - "Chris Williamson is undergoing massive toxin-induced mental health issues"
  184. - "You can copy Donald Trump.\nYou can copy Barack Obama.\nYou can copy Bill Clinton."
  185. 2. **Surprising Statistic** - Lead with a specific, hard-to-ignore number. Stats create instant credibility and curiosity.
  186. - "99% of lottery winners go broke within 5 years."
  187. - "20+ years of business in a nutshell:"
  188. 3. **Direct Listicle** - State exactly what the list is about. No cleverness needed - the format itself stops the scroll. Listicles and how-tos are the two highest-performing written content formats on the internet.
  189. - "Signs of high vibration:"
  190. - "7 supplements I'm getting my aging parents to take:"
  191. 4. **High-TAM "Everyone" Hook** - Cast the widest possible net, but ONLY if the content genuinely delivers for that audience. A bad "everyone" hook claims breadth but delivers niche content.
  192. - GOOD: "Everyone on the planet should read this book" - recommends a universally applicable book
  193. - GOOD: "Everyone needs to hear this" - shares a universal life lesson
  194. - BAD: "Everyone's teaching you tactics" - pivots to niche entrepreneur advice
  195. 5. **Numbers Up Front** - Start the hook with a number. Specific numbers outperform vague claims.
  196. - "20+ years of business in a nutshell:"
  197. - "7 supplements I'm getting my aging parents to take:"
  198. 6. **Direct "You" Address** - Point directly at the reader. Make them feel personally called out.
  199. - "You have the exact same tax code as Donald Trump."
  200. - "You can copy Barack Obama."
  201. **What kills a hook:**
  202. - **Desensitized claims** - "I'm a millionaire" doesn't stand out anymore. If using a flex, it has to be genuinely extraordinary for the platform.
  203. - **Disconnected lines** - The first and second lines must flow. "I'm a millionaire. If you suddenly become rich overnight..." doesn't connect.
  204. - **Cliches** - "Playing checkers while a small group is playing chess" means nothing. Everyone can say it.
  205. - **Wide net, narrow delivery** - Don't say "everyone" if the content only applies to a niche audience.
  206. - **Unlikely scenarios** - "If you suddenly become rich overnight" is more likely to get dunked on than to get authentic engagement.
  207. ### Body Tweets
  208. - One idea per tweet
  209. - Use arrow bullets (→) for lists
  210. - Break up dense info across multiple tweets
  211. - Numbers and dollar amounts grab attention
  212. - Short paragraphs with line breaks between them
  213. - **Waterfall structure for lists:** Order list items from shortest to longest sentence length. This creates a staircase/waterfall visual that's aesthetically pleasing and makes people stop to read.
  214. ```
  215. → People stare at you
  216. → Kids like you
  217. → Animals feel safe around you
  218. → Strangers tell you their life story
  219. → You walk into a room and the energy shifts
  220. ```
  221. - **Contrasting pairs work well for frameworks:** Alternate between two categories to create rhythm.
  222. ```
  223. Chess: manage their energy
  224. Checkers: manage their time
  225. Chess: optimize their psychology
  226. Checkers: optimize their funnel
  227. ```
  228. - **7 is the sweet spot for listicles.** Not too short, not too long - scans well on a carousel.
  229. ### CTA Tweet (Last Slide)
  230. - Clear call to action: follow, save, share, comment
  231. - Can summarize the key takeaway
  232. - Keep it short - the carousel already delivered the value
  233. ---
  234. ## Layout Reference
  235. Each slide is 1080x1350px (Instagram 4:5 portrait).
  236. **Single tweet slide:**
  237. - White background (light theme) or black background (dark theme)
  238. - Circular profile pic (80px) - top left
  239. - Bold name + blue verified badge + gray handle - next to pic
  240. - Tweet text - large, clean sans-serif, generous line spacing
  241. - Optional image - full width, rounded corners, below text
  242. - Content vertically centered on the slide
  243. **Two-tweet slide:**
  244. - Same layout, two tweets stacked
  245. - Light gray divider line between them
  246. - Both vertically centered together
  247. ---
  248. ## Generating Images for Slides
  249. If the user doesn't have enough screenshots or reference images to fill out a carousel, generate them with Gemini. The script produces **16:9 landscape images** designed to embed inside carousel slides below the tweet text. It has a built-in style guide that ensures dark, moody, cinematic results matching the carousel aesthetic.
  250. ```bash
  251. python3 .claude/skills/instagram-thread-carousel/scripts/generate_carousel_image.py \
  252. --prompt "description of the image you need" \
  253. --output workspace/<date>/<title>/ref/generated-image.png
  254. ```
  255. **Options:**
  256. - `--reference path/to/screenshot.png` - Pass existing images for context (e.g., a raw screenshot to stylize into a mockup)
  257. - `--headshot .claude/skills/instagram-thread-carousel/headshots/tyler-headshot.png` - Include a person in the generated image
  258. - `--examples path/to/style-ref.png` - Style inspiration images
  259. Then reference the generated image in the slide config:
  260. ```json
  261. {"text": "slide text here", "image": "workspace/<date>/<title>/ref/generated-image.png"}
  262. ```
  263. ### Good prompts for carousel images:
  264. - **Product mockups:** "A sleek MacBook screen showing [product UI] floating on a dark cinematic background with subtle blue glow accents"
  265. - **Concept illustrations:** "A dark moody illustration showing a terminal prompt on the left with a glowing arrow pointing to a finished YouTube thumbnail on the right"
  266. - **Before/after:** "Split image: left side shows a messy manual process, right side shows clean automated output - dark tech aesthetic with cyan accents"
  267. - **Process diagrams:** "Three connected nodes on a dark background showing: raw data → AI processing → polished output, with subtle neon connecting lines"
  268. - **Styled screenshots:** Pass the raw screenshot as `--reference` and prompt: "Render this UI screenshot on an elegant floating device mockup with dramatic dark lighting and subtle shadow"
  269. **Requires `GEMINI_API_KEY` in `.env`.**
  270. ---
  271. ## Troubleshooting
  272. **Fonts look wrong:** The script tries SF Pro → Helvetica → Arial → DejaVu Sans. If none are found, it falls back to Pillow's default. Install a clean sans-serif font for best results.
  273. **Text overflows the slide:** Break long tweets into multiple shorter ones. The script wraps text automatically, but very long tweets with images may push content off the bottom.
  274. **Images look stretched:** Images maintain their aspect ratio. Very tall images will take up a lot of slide space - crop them to landscape or square before using.
  275. **Profile pic not found:** Check the path in the config. Headshots should be in `.claude/skills/instagram-thread-carousel/headshots/`. The script draws a gray circle as a placeholder if no headshot is found.
  276. **Animated slides look wrong or crash the session:** The script outputs `.mp4` (via ffmpeg) for animated slides instead of GIF, preserving full color. A `.png` preview is also saved for chat display. If ffmpeg is not installed, it falls back to GIF (which has color limitations). Install ffmpeg with `brew install ffmpeg`.
  277. **Emoji rendering:** The script uses `pilmoji` with `AppleEmojiSource` for native Apple emoji rendering. If `pilmoji` is not installed (`pip3 install pilmoji`), emoji will render as blank squares. The emoji vertical alignment is corrected with `emoji_position_offset=(0, -6)` in the script.
  278. ---
  279. ## Image Fitting Rules
  280. When a slide has both text AND an embedded image, the text must be short enough that the image isn't cut off or shrunk too small. Follow these rules:
  281. **Slides with images should have SHORT text:**
  282. - 1-3 short lines max when an image is present
  283. - If the content needs more text, split it across two slides: one image slide with a brief label, and one text-only slide with the detail
  284. **When the user provides their own images:**
  285. - Always use the user's real screenshots/images over generated ones
  286. - Check the image dimensions - landscape images fit best below tweet text
  287. - If an image is getting cut off, shorten the text first before resizing the image
  288. **Splitting content for image slides:**
  289. Instead of cramming a long explanation + image onto one slide, do this:
  290. - **Slide A (image slide):** Short punchy text (1-2 lines) + the image
  291. - **Slide B (detail slide):** The longer explanation, text-only
  292. This keeps image slides clean and readable at carousel-swiping speed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.