Social Autopilot

SKILL.md

# Social Autopilot — Full Auto Social Media Engine

You are a social media automation agent. You manage the user's social media presence across X (Twitter), Instagram, YouTube, and Meta (Facebook/Threads) — completely autonomously.

## What You Do

1. **Content Generation** — Generate platform-optimized posts from a content database (CSV). Rotate through content formats: insights, hot takes, myth busters, questions, quizzes, struggle posts.
2. **X Threads** — Generate data-driven threads (4-6 tweets) from dataset analysis. Each thread backed by real data with proof examples. Auto-rotate through 7 themes daily.
3. **Video Reels** — Generate short-form video (9:16, 1080x1920) for Instagram Reels and YouTube Shorts using HTML-to-video rendering. Multiple color themes, dynamic content per video.
4. **Smart Scheduling** — Post at configurable time slots via GitHub Actions cron or manual trigger.
5. **Hashtag Strategy** — 1-2 relevant hashtags per X post, rotated by topic. Full hashtag sets for Instagram.
6. **Answer in Comments** — Post answers/reveals as comments (not in main post) to drive engagement.
7. **Platform-Specific Formatting** — Respect character limits (X: 280), aspect ratios (IG: 9:16), and best practices per platform.

## Required Environment Variables

All credentials are read from environment variables. No keys are hardcoded.

### X (Twitter)
```
X_API_KEY=<your X/Twitter API key>
X_API_SECRET=<your X/Twitter API secret>
X_ACCESS_TOKEN=<your X/Twitter access token>
X_ACCESS_TOKEN_SECRET=<your X/Twitter access token secret>
```

### Instagram
```
INSTAGRAM_USER_ID=<your Instagram user ID>
INSTAGRAM_ACCESS_TOKEN=<your Instagram Graph API access token>
INSTAGRAM_APP_SECRET=<your Instagram app secret for webhook verification>
```

### Meta (Facebook/Threads)
```
META_PAGE_ACCESS_TOKEN=<your Meta page access token>
META_PAGE_ID=<your Meta page ID>
```

### YouTube
YouTube posting uses OAuth2 credentials stored in a `client_secrets.json` file. Authentication is handled via browser OAuth flow on first run.

### Cloudflare R2 (for Instagram reel hosting)
Instagram requires a public URL for reel uploads. R2 is used as the video host.
```
R2_ENDPOINT=<your Cloudflare R2 endpoint>
R2_ACCESS_KEY=<your R2 access key>
R2_SECRET_KEY=<your R2 secret key>
R2_BUCKET=<your R2 bucket name>
R2_PUBLIC_URL=<your R2 public URL>
```

### Optional (auto-detected)
```
CI=true                 # Set automatically by GitHub Actions
GITHUB_ACTIONS=true     # Set automatically by GitHub Actions
```

## Required Files
- `data/questions.csv` — Your content database (CSV with columns: question, option1, option2, option3, option4, correctIndex, explanation, subject, year)

## Required Python Packages
```
tweepy
requests
moviepy
numpy
Pillow
html2image
boto3
google-api-python-client
google-auth-oauthlib
```

## Scripts Included

| Script | Purpose |
|--------|---------|
| `formatter.py` | Content generation — post pools, hashtags, platform formatting |
| `x_poster.py` | X/Twitter posting + thread posting via tweepy |
| `x_thread_generator.py` | Data-driven thread generation from CSV analysis |
| `instagram_main.py` | Instagram reel posting orchestrator |
| `ig_reel_poster.py` | Instagram Graph API reel upload + answer comments |
| `ig_config.py` | Instagram captions, hashtags, output paths |
| `youtube_main.py` | YouTube Shorts posting orchestrator |
| `yt_shorts_poster.py` | YouTube Data API upload |
| `yt_config.py` | YouTube titles, descriptions, tags |
| `meta_poster.py` | Meta/Facebook/Threads posting |
| `html_video_generator.py` | HTML→PNG→MP4 video generation (8 color themes) |
| `video_generator.py` | PIL-based fallback video generator |
| `image_generator.py` | Static image generation for posts |
| `csv_manager.py` | Content database reader + tracking |
| `r2_uploader.py` | Cloudflare R2 video upload (for Instagram reel hosting) |
| `yt_auth.py` | YouTube OAuth2 authentication handler |

## Commands

- **"Post now"** — Immediately post to all configured platforms
- **"Post to X"** — Post single tweet + thread
- **"Post reel"** — Generate and post Instagram reel
- **"Generate video"** — Create a reel/short without posting
- **"Show schedule"** — Display current posting schedule

## Customization (IMPORTANT)

Before using this skill, customize these files for your niche:

1. **Branding:** Search and replace `{BRAND_URL}` and `{BRAND_NAME}` in all scripts with your own brand name and website URL. These appear as watermarks and CTAs in generated videos and captions.
2. **Content pools:** `formatter.py` contains pre-written post templates for an education/exam niche (UPSC). Replace the text in `INSIGHT_POSTS`, `HOT_TAKE_POSTS`, `QUESTION_POSTS`, `MYTH_BUST_POSTS`, `STRUGGLE_POSTS`, and `QUIZ_HOOKS` lists with content relevant to YOUR niche.
3. **Data:** Replace `data/questions.csv` with your own content database.

## Security Notes

- All API credentials are read from environment variables — never hardcoded
- Data is only sent to platforms you explicitly configure (X, Instagram, YouTube, Meta) and Cloudflare R2 (for video hosting, required by Instagram)
- CI/GITHUB_ACTIONS env vars are only used to detect runtime environment (headless Chrome flags)
- Content database stays local — never uploaded anywhere