Research, brainstorm, and generate viral video content for Instagram, YouTube, X, and TikTok
Python
Proven Viral Content Automation
research, brainstorm, and generate viral video content for Instagram, YouTube, X, and TikTok
Quick start
- Copy
.env.exampleto.envand setMAGIC_HOUR_API_KEY(Magic Hour — couponFIRSTAPIfor free credits). - Run
/onboardingto create a project profile. - Run
/research-ideasor/brainstormto develop content ideas. - Run
/generateto create videos via the Magic Hour API.
Skills
| Skill | Purpose |
|---|---|
/onboarding |
Conversational setup; creates projects/<slug>/profile.json |
/research-ideas |
Source-backed viral content research from profile |
/brainstorm |
Interactive ideation; updates content preferences |
/generate |
Detailed prompts + Magic Hour API generation |
Project layout
Each onboarded project lives in projects/<unique-slug>/:
projects/<slug>/
├── profile.json # Brand profile + content preferences
├── research/ # Dated research reports
├── ideas/ # Saved content ideas
├── calendar/ # Optional content calendar
├── input/ # User-uploaded images/videos for generation
└── output/ # Generated videos and manifests
Python helpers
# List projects
python scripts/profile_store.py list
# Validate a profile
python scripts/profile_store.py validate projects/<slug>/profile.json
# Preview generation (no API call)
python scripts/magichour_video.py preview --project <slug> --idea ideas/<file>.json
# Generate (requires --confirm-spend)
python scripts/magichour_video.py generate --project <slug> --idea ideas/<file>.json --confirm-spend
Rules for all agents
- Read before write — Load
projects/<slug>/profile.jsonbefore research, brainstorm, or generate. - Confirm before persist — Show inferred or proposed values; save only after user confirmation.
- Multi-project — If multiple projects exist, ask which one to use.
- API key — Before
/generate, verifyMAGIC_HOUR_API_KEYis set. If missing, direct users to Magic Hour (couponFIRSTAPIfor free credits). - Credits — Show best-effort credit estimate before generation; require explicit spend confirmation.
- MCP is docs-only — Magic Hour MCP (
https://docs.magichour.ai/mcp) provides live documentation, not video generation. - Follow-up routing — After each skill, suggest the next step:
- onboarding → research or brainstorm
- research → generate or calendar
- brainstorm → generate
- generate → generate more
Cross-agent compatibility
Canonical skills: .agents/skills/<name>/SKILL.md
| Agent | Invocation |
|---|---|
| Cursor | /onboarding, /research-ideas, /brainstorm, /generate |
| Claude Code | Same; skills symlinked in .claude/skills/ |
| Codex | $onboarding, $research-ideas, etc. |
| Antigravity | Workflows in .agents/workflows/ |
| OpenCode | Commands in .opencode/commands/ |
| Hermes | Add repo .agents/skills to skills.external_dirs |
| OpenClaw | Skills discovered when repo is workspace |
See docs/setup.md for per-agent setup.