Skip to content
Back to search

viraloop

OpenClaw AI agent skill for automated TikTok and Instagram carousel growth. Pass any website URL to analyze brand, competitors, colors, value proposition. Generates 6 visually coherent slides and auto-publishes with trending music via upload-post API. Built-in analytics and learning loop. Free tier, no credit card. Larry alternative.

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/upload-post--viraloop/badge.svg)](/listings/upload-post--viraloop)

HTML

<a href="/listings/upload-post--viraloop"><img src="/api/listings/upload-post--viraloop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Analyze website
node scripts/analyze-web.js https://your-product.com

# 2. Generate slides
GEMINI_API_KEY="..." bash scripts/generate-slides.sh

# 3. Publish
UPLOADPOST_TOKEN="..." bash scripts/publish-carousel.sh

# 4. Check analytics
UPLOADPOST_TOKEN="..." bash scripts/check-analytics.sh 7

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 · 340 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: viraloop
  3. description: OpenClaw AI agent skill for automated TikTok and Instagram carousel growth. Analyzes any website URL to extract brand, competitors, value proposition, then generates viral slides with auto-publishing and trending music via upload-post API. Built-in analytics feedback loop.
  4. metadata: {"clawdbot":{"emoji":"🔄","requires":{"env":["GEMINI_API_KEY","UPLOADPOST_TOKEN"],"bins":["node","jq","uv"]}}}
  5. ---
  6. # Viraloop
  7. Analyze any website and generate a 6-slide carousel for TikTok/Instagram with visual coherence. Posts directly to your feed (no drafts) with auto trending music. Both APIs (Gemini + upload-post.com) have free plans — no credit card needed to start.
  8. ## Philosophy: Daily Iteration Loop
  9. The key to growth is **consistency + learning**:
  10. 1. **Post 1 carousel per day** - Consistency beats virality
  11. 2. **Track everything** - Every post generates data
  12. 3. **Learn from data** - What hooks work? What times? What visuals?
  13. 4. **Iterate and improve** - Each carousel is better than the last
  14. ```
  15. Day 1: Post → Analyze → Learn
  16. Day 2: Post (improved) → Analyze → Learn
  17. Day 3: Post (better) → Analyze → Learn
  18. ...
  19. Day 30: You have 30 data points and a refined strategy
  20. ```
  21. The skill maintains a `learnings.json` that accumulates insights across all posts:
  22. - Best performing hooks
  23. - Optimal posting times
  24. - Visual styles that work
  25. - CTAs that convert
  26. **This is not a one-shot tool. It's a growth engine.**
  27. ## Quick Start
  28. ```bash
  29. # 1. Full business research
  30. node {baseDir}/scripts/analyze-web.js https://your-website.com
  31. # 2. Generate 3 hook variants (SHOCK, CURIOSITY, CONTRADICTION)
  32. GEMINI_API_KEY="your-key" bash {baseDir}/scripts/generate-hooks.sh
  33. # 3. Review hooks with vision, pick the best one
  34. # 4. Generate slides using selected hook type
  35. GEMINI_API_KEY="your-key" bash {baseDir}/scripts/generate-slides.sh [shock|curiosity|contradiction]
  36. # 5. Review slides (agent verifies text and quality)
  37. # Agent uses vision to check each slide
  38. # 6. Publish to TikTok + Instagram
  39. UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/publish-carousel.sh
  40. # 7. Check analytics (after 24-48h)
  41. UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/check-analytics.sh 7
  42. # 8. Learn from data for next carousels
  43. node {baseDir}/scripts/learn-from-analytics.js
  44. ```
  45. ## Hook Categories (Visual Novelty System)
  46. The key to breaking the 1000 views ceiling is **visual novelty in the first slide**. We generate 3 hook types:
  47. | Type | Goal | Visual Style |
  48. |------|------|--------------|
  49. | **SHOCK** | Stop the scroll with impossible/absurd | Surreal, chaotic, "wait what?" |
  50. | **CURIOSITY** | Create information gap | Mysterious, secrets being revealed |
  51. | **CONTRADICTION** | Show impossible combination | Relaxed + intense, "how is that possible?" |
  52. ### Anti-Stock Filter
  53. All hooks include anti-stock prompting to avoid:
  54. - Generic stock photo aesthetics
  55. - Shocked pretty girl trope
  56. - Typical influencer poses
  57. - Overused laptop-coffee setups
  58. - Corporate handshake scenes
  59. ### Hook Testing Workflow
  60. 1. Generate 3 variants with `generate-hooks.sh`
  61. 2. Review with vision, score each 1-5 on novelty
  62. 3. Kill anything that looks familiar
  63. 4. Use best hook for carousel
  64. 5. Track which hook TYPE performs best over time
  65. ## Image Model
  66. Uses **gemini-3.1-flash-image-preview** to generate slides.
  67. - Local script: `{baseDir}/scripts/generate_image.py`
  68. - Supports image-to-image for visual coherence between slides
  69. ## Step 1: Full Research (`analyze-web.js`)
  70. Performs COMPLETE business investigation:
  71. ### 1. Brand Analysis
  72. - Brand name (from domain or title)
  73. - Logo (URL or SVG)
  74. - CSS colors (background, primary, links, headings)
  75. - Typography (body font, heading font)
  76. - Favicon
  77. ### 2. Content Analysis
  78. - Headline and tagline
  79. - All headings (page structure)
  80. - Features/benefits (title + description)
  81. - Pricing/plans
  82. - Testimonials
  83. - Stats/metrics
  84. - CTAs
  85. - Meta tags (title, description, og:image)
  86. ### 3. Internal Pages
  87. - Navigates pricing, features, about, testimonials
  88. - Extracts additional content from each page
  89. ### 4. Competitor Detection
  90. - Searches for known competitor mentions in content
  91. - List of 20+ known SaaS competitors (Buffer, Hootsuite, Later, etc.)
  92. - Detects "vs", "alternative", "compare" sections
  93. - No external searches required - all from the website itself
  94. ### 5. Storytelling
  95. - Detects business type (SaaS, ecommerce, app)
  96. - Detects niche (social-media-tools, developer-tools, etc.)
  97. - Generates hooks based on customer pain points
  98. - Defines pain points from features
  99. - Creates transformation narrative (before → after)
  100. ### 6. Visual Context
  101. - Brand colors in CSS format
  102. - Color description for prompts
  103. - Typography for slides
  104. - Image themes based on niche
  105. - Style guide for coherence
  106. **Output:** `/tmp/carousel/analysis.json`
  107. ## Step 2: Generate Slides (`generate-slides.sh`)
  108. Generates 6 slides with visual coherence using image-to-image:
  109. | Slide | Type | Content |
  110. |-------|------|---------|
  111. | 1 | **HOOK** | Question/problem that hooks. Establishes ALL visual style. |
  112. | 2 | **Problem** | Agitate the pain. "You upload to TikTok... then Instagram..." |
  113. | 3 | **Agitation** | Competition advancing. Urgency. |
  114. | 4 | **Solution** | Present the product with its value proposition. |
  115. | 5 | **Feature** | Main benefit. |
  116. | 6 | **CTA** | "Link in bio 👆" + call to action. |
  117. ### Visual Coherence
  118. - Slide 1 generates the base style (colors, typography, mood)
  119. - Slides 2-6 use image-to-image with slide 1 as reference
  120. - Maintains same color palette, fonts, and aesthetic
  121. ### Prompts per Slide
  122. Each slide has:
  123. - **Text:** The main message
  124. - **Scene:** Detailed visual description for background
  125. - **Style:** Based on brand analysis
  126. **Output:**
  127. - `/tmp/carousel/slide-{1-6}.jpg`
  128. - `/tmp/carousel/caption.txt`
  129. ## Step 3: Review with Vision
  130. After generating, the agent MUST review each slide:
  131. - ✓ Text is legible and correct
  132. - ✓ Words are not cut off
  133. - ✓ Correct spelling
  134. - ✓ Visual coherence between slides
  135. - ✓ Acceptable image quality
  136. If there are errors, regenerate the specific slide.
  137. ## Image Format
  138. - **Resolution:** 768x1376 (9:16 vertical ratio)
  139. - **Format:** JPG (TikTok does NOT accept PNG)
  140. - **Text:** Large, bold, with shadow for readability
  141. - **Background:** Scene relevant to the business, not just solid colors
  142. ## Step 4: Publish to TikTok + Instagram (`publish-carousel.sh`)
  143. Publishes the carousel to TikTok and Instagram using Upload-Post API.
  144. ```bash
  145. UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/publish-carousel.sh
  146. ```
  147. **Endpoint:** `POST /api/upload_photos`
  148. - Docs: https://docs.upload-post.com/api/upload-photo
  149. **Parameters sent:**
  150. - `platform[]=tiktok` + `platform[]=instagram`
  151. - `auto_add_music=true` - Adds music on TikTok automatically
  152. - `tiktok_title` - Short title (max 90 chars) + hashtags
  153. - `title` - Full caption for Instagram
  154. - `privacy_level=PUBLIC_TO_EVERYONE`
  155. - `media_type=IMAGE` - Photo carousel on Instagram
  156. - `async_upload=true` - Process in background
  157. - `photos[]` - The 6 slides JPG
  158. **⚠️ IMPORTANT Instagram:**
  159. After publishing, user must go to Instagram and add viral music manually:
  160. 1. Open Instagram → Profile → The post
  161. 2. Edit → Add music
  162. 3. Search for trending/viral song
  163. **Output:** Saves `request_id` in `post-info.json` for tracking.
  164. ## Step 5: Analyze Performance (`check-analytics.sh`)
  165. Gets TikTok and Instagram analytics to see what works.
  166. ```bash
  167. UPLOADPOST_TOKEN="your-token" bash {baseDir}/scripts/check-analytics.sh 7
  168. ```
  169. **Endpoints used:**
  170. 1. **Profile analytics:**
  171. ```
  172. GET /api/analytics/{user}?platforms=tiktok
  173. ```
  174. → Followers, likes, comments, shares, impressions
  175. 2. **Total impressions:**
  176. ```
  177. GET /api/uploadposts/total-impressions/{user}?platform=tiktok&breakdown=true
  178. ```
  179. → Total views per day
  180. 3. **Per-post analytics:**
  181. ```
  182. GET /api/uploadposts/post-analytics/{request_id}
  183. ```
  184. → Views, likes, comments for the specific carousel (TikTok + Instagram)
  185. Docs: https://docs.upload-post.com/api/get-analytics
  186. ## Step 6: Learn and Improve (`learn-from-analytics.js`)
  187. Analyzes data and saves learnings for future carousels.
  188. ```bash
  189. node {baseDir}/scripts/learn-from-analytics.js
  190. ```
  191. **Generates:**
  192. - `learnings.json` - Accumulated knowledge base
  193. - Best hooks (those generating most views)
  194. - Optimal posting times
  195. - Recommendations for next carousel
  196. ## Full Flow
  197. ```bash
  198. # 1. Research business
  199. node {baseDir}/scripts/analyze-web.js https://my-product.com
  200. # 2. Generate slides
  201. GEMINI_API_KEY="..." bash {baseDir}/scripts/generate-slides.sh
  202. # 3. Review with vision (agent verifies text)
  203. # Agent checks each slide image
  204. # 4. Publish
  205. UPLOADPOST_TOKEN="..." UPLOADPOST_USER="myuser" bash {baseDir}/scripts/publish-carousel.sh
  206. # 5. (After a few hours/days) Analyze
  207. UPLOADPOST_TOKEN="..." UPLOADPOST_USER="myuser" bash {baseDir}/scripts/check-analytics.sh 7
  208. # 6. Learn for next carousels
  209. node {baseDir}/scripts/learn-from-analytics.js
  210. ```
  211. ## Files
  212. ```
  213. {baseDir}/
  214. ├── SKILL.md # This documentation
  215. └── scripts/
  216. ├── analyze-web.js # Full business research
  217. ├── generate-slides.sh # Generate 6 slides with coherence
  218. ├── generate_image.py # Gemini 3.1 flash image
  219. ├── review-slides.js # Prepare slides for review
  220. ├── publish-carousel.sh # Publish via Upload-Post API
  221. ├── check-analytics.sh # Get analytics (TikTok + Instagram)
  222. ├── learn-from-analytics.js # Learn from data
  223. └── search-competitors.js # Optional external search
  224. ```
  225. ## Environment Variables
  226. | Variable | Description |
  227. |----------|-------------|
  228. | `GEMINI_API_KEY` | Google API key for image generation |
  229. | `UPLOADPOST_TOKEN` | Upload-Post token for publishing and analytics |
  230. | `UPLOADPOST_USER` | Upload-Post username (required) |
  231. ## Hook Examples by Niche
  232. | Niche | Hook Example |
  233. |-------|--------------|
  234. | Social Media Tools | "Still posting to social media ONE BY ONE? 😩" |
  235. | SaaS General | "Still doing this MANUALLY?" |
  236. | Ecommerce | "The product TikTok won't stop recommending" |
  237. | App | "The app I wish I'd discovered sooner" |
  238. | Developer Tools | "The API that's going to change your code" |
  239. ## Why Viraloop?
  240. | | Viraloop | Other skills |
  241. |-|----------|-------|
  242. | Publishing | Direct to feed | Drafts only |
  243. | Music | Auto trending music | Manual |
  244. | Platforms | TikTok + Instagram | Single platform |
  245. | Research | Auto URL analysis | Manual description |
  246. | Image coherence | Image-to-image reference | Independent slides |
  247. | Image gen | Gemini (free tier) | Paid providers |
  248. | Posting | upload-post.com (free, no CC) | Paid or self-hosted |
  249. | Text overlay | AI-native (Gemini renders) | External scripts |
  250. | Prompts | Structured templates | Free-form |
  251. | Setup | 3 env vars | Complex multi-tool setup |
  252. ## Notes
  253. - Analysis extracts competitors from the website content itself (20+ known SaaS)
  254. - Image-to-image maintains coherence but takes ~20s per slide
  255. - Generated caption includes niche-relevant hashtags
  256. - Always review slide text - sometimes it gets cut off
  257. - `auto_add_music` on TikTok improves engagement
  258. - Check analytics after 24-48h for meaningful data
  259. - Learnings accumulate and improve with each published carousel
  260. - TikTok title max 90 characters (auto-truncated with hashtags)
README.md · README · 127 lines

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

  1. # Viraloop 🔄
  2. Generate viral TikTok/Instagram carousel slides from any website automatically.
  3. ## Philosophy: Daily Iteration
  4. **Post 1 carousel per day. Learn. Iterate. Grow.**
  5. ```
  6. Day 1: Post → Analyze → Learn
  7. Day 7: 7 data points, patterns emerging
  8. Day 30: Refined strategy, proven hooks, optimal timing
  9. ```
  10. The skill accumulates insights across ALL your posts in `learnings.json`.
  11. ## Features
  12. - 🔍 **Full Business Research** - Analyzes brand, features, competitors from any URL
  13. - 🎨 **AI Image Generation** - Creates 6 visually coherent slides with Gemini (free plan available, no credit card)
  14. - 📱 **Direct Publishing** - Posts straight to your TikTok feed with auto trending music + Instagram simultaneously. No drafts, no manual steps
  15. - 💰 **100% Free to Start** - Both APIs (Gemini and [upload-post.com](https://upload-post.com)) have free plans, no credit card required
  16. - 📊 **Analytics Tracking** - Monitors performance across all posts
  17. - 🔄 **Learning Loop** - Accumulates insights: best hooks, times, days, styles
  18. ## Quick Start
  19. ```bash
  20. # 1. Analyze website
  21. node scripts/analyze-web.js https://your-product.com
  22. # 2. Generate slides
  23. GEMINI_API_KEY="..." bash scripts/generate-slides.sh
  24. # 3. Publish
  25. UPLOADPOST_TOKEN="..." bash scripts/publish-carousel.sh
  26. # 4. Check analytics
  27. UPLOADPOST_TOKEN="..." bash scripts/check-analytics.sh 7
  28. ```
  29. ## Requirements
  30. - Node.js 18+
  31. - Playwright (`npm install playwright && npx playwright install chromium`)
  32. - uv (Python package runner)
  33. - jq
  34. ## Environment Variables
  35. | Variable | Description |
  36. |----------|-------------|
  37. | `GEMINI_API_KEY` | Google API key for Gemini image generation |
  38. | `UPLOADPOST_TOKEN` | Upload-Post API token |
  39. | `UPLOADPOST_USER` | Upload-Post username |
  40. ## Slide Structure
  41. 1. **Hook** - Attention-grabbing question/problem
  42. 2. **Problem** - Agitate the pain point
  43. 3. **Agitation** - Show competition advancing
  44. 4. **Solution** - Reveal your product
  45. 5. **Feature** - Key benefit
  46. 6. **CTA** - Call to action (Link in bio)
  47. ## Credentials & Security
  48. ### Required Credentials
  49. | Credential | Type | Where to Get |
  50. |------------|------|--------------|
  51. | `GEMINI_API_KEY` | Environment variable | [Google AI Studio](https://aistudio.google.com/app/apikey) |
  52. | `UPLOADPOST_TOKEN` | Environment variable | [upload-post.com](https://upload-post.com) → Dashboard → API Keys |
  53. ### Optional
  54. | Credential | Type | Description |
  55. |------------|------|-------------|
  56. | `UPLOADPOST_USER` | Environment variable | Upload-Post username (not sensitive) |
  57. ### Security Notes
  58. - ✅ All credentials are read from environment variables, not stored in files
  59. - ✅ No API keys are hardcoded in any scripts
  60. - ✅ Website analysis only reads public web pages (no authentication scraping)
  61. - ✅ All generated data stays local in `/tmp/carousel/`
  62. ### Data Flow
  63. 1. **Website URL** → Analyzed by Playwright (local browser) → `analysis.json`
  64. 2. **Analysis** → Sent to Gemini API → Returns generated images
  65. 3. **Images + Caption** → Sent to Upload-Post API → Published to TikTok/Instagram
  66. 4. **Analytics** → Fetched from Upload-Post API → Stored locally in `learnings.json`
  67. ### External Services Used
  68. | Service | Purpose | Data Sent |
  69. |---------|---------|-----------|
  70. | Gemini API | Image generation | Text prompts describing slides |
  71. | Upload-Post API | Publishing + analytics | Images, captions, profile username |
  72. No sensitive user data is transmitted. Only the content you're publishing.
  73. ## Why Viraloop?
  74. Most carousel automation skills post to drafts and require manual publishing. Viraloop is different:
  75. | Feature | Viraloop | Other skills |
  76. |---------|----------|-------|
  77. | Publishing | **Direct to feed** — posts go live instantly | Drafts only — you publish manually |
  78. | Music | **Auto trending music** via `auto_add_music` | Manual — you add it yourself |
  79. | Platforms | **TikTok + Instagram in one call** | Single platform, manual cross-post |
  80. | Research | **Auto-analyzes any URL** — brand, competitors, pricing, features | Manual — you describe your product |
  81. | Image coherence | **Image-to-image** — slides 2-6 reference slide 1 | Each slide generated independently |
  82. | Image gen | **Gemini** (free tier available) | Paid image providers required |
  83. | Posting service | **upload-post.com** — free plan, no credit card | Paid or self-hosted alternatives |
  84. | Text on images | **AI-native** — text rendered directly | External scripts for text overlay |
  85. | Prompt quality | **Structured templates** — explicit fields for consistency | Free-form prompts |
  86. | Setup | **3 env vars** and you're posting | Complex multi-tool setup |
  87. ## Documentation
  88. See [SKILL.md](./SKILL.md) for full documentation.
  89. ## License
  90. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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