Bilingual Codex skill for Instagram Reels analysis, evidence-based viral content research, script auditing, and content strategy.
codex-reels-viral turns Codex into a short-form content strategist. It finds
statistically unusual Reels, explains why they outperformed, maps saturated and
underused points of view, audits scripts before filming, and produces testable
content briefs without inventing live metrics.
Most "viral content" prompts rank posts by raw views. That favors large accounts and confuses popularity with outperformance. This skill uses multiple signals:
- views relative to followers;
- views relative to the author's recent median;
- engagement quality and view velocity when available;
- sample freshness, completeness, and confidence;
- repeated patterns across creators instead of one lucky post.
The workflow distinguishes verified facts, calculated metrics, observations, hypotheses, and recommendations. If live data is unavailable, it asks for CSV/JSON input or clearly labels a qualitative analysis.
- Instagram Reels outlier discovery and ranking
- Viral coefficient and confidence scoring
- Script audit across hook, retention, proof, clarity, novelty, and CTA
- Competitor POV clustering and white-space discovery
- Hook and CTA variant generation
- 7/14/30-day content plans with experiment hypotheses
- Evidence ledger with source URLs and collection dates
- English and Russian output
- Meta Graph API bridge plus CSV/JSON fallback
- Dependency-free Python CLI
- Automated tests and GitHub Actions validation
git clone https://github.com/Rag-hubk/codex-reels-viral.git
mkdir -p ~/.agents/skills
ln -s "$PWD/codex-reels-viral/skills/reels-viral-strategist" \
~/.agents/skills/reels-viral-strategistCodex follows symlinked skill folders. You can copy the folder instead.
mkdir -p .agents/skills
cp -R /path/to/codex-reels-viral/skills/reels-viral-strategist \
.agents/skills/reels-viral-strategistThe repository is also packaged as a skills-only Codex plugin through
.codex-plugin/plugin.json.
Invoke explicitly:
$reels-viral-strategist
Find evidence-backed outlier Reels in the AI automation niche from July 13
through July 27, 2026. Exclude crypto and income claims. Reply in English.
Or ask naturally:
Audit this Russian Reel script against the attached competitor dataset.
Give me three stronger hooks and preserve my direct, expert tone.
The skill responds in the user's language unless a language is requested.
python3 skills/reels-viral-strategist/scripts/reels_viral.py rank \
skills/reels-viral-strategist/assets/sample-reels.csv \
--top 10 \
--format markdownSupported inputs are CSV and JSON. See the
data schema.
python3 skills/reels-viral-strategist/scripts/reels_viral.py audit \
skills/reels-viral-strategist/assets/sample-script.txt \
--language en \
--format markdownThe deterministic audit is a structural baseline, not a claim about current trends. Codex adds trend context only when evidence is available.
export META_ACCESS_TOKEN="..."
python3 skills/reels-viral-strategist/scripts/meta_graph_bridge.py \
--url 'https://graph.threads.net/v1.0/your-authorized-endpoint?fields=...' \
--output reels.csv \
--raw-output raw-response.jsonThe bridge accepts only official Meta Graph API hosts, reads the token from an environment variable, preserves raw provenance when requested, and normalizes common media fields. Supply an endpoint and fields that your app is authorized to access.
There is no single public "Meta.ai API" that provides unrestricted competitor content from Instagram, Threads, and Facebook. Meta exposes separate Graph API products, permissions, account types, review requirements, and versioned endpoints. Public discovery is narrower than many prompt templates imply.
This project therefore uses a source-adapter workflow:
- Use an authorized official Meta API endpoint when it supports the requested account and metric.
- Use browser research only where permitted and cite every item.
- Import licensed exports, first-party insights, or user-provided CSV/JSON.
- Never fabricate unavailable follower counts, medians, views, or dates.
API compatibility notes were verified on July 27, 2026. Always re-check official Meta documentation at execution time.
Every research report includes:
- Scope and collection timestamp
- Source coverage and limitations
- Ranked outlier table
- Pattern clusters and counterexamples
- Trend shift or "insufficient evidence"
- Three differentiated content concepts
- Test plan, success metric, and stop condition
- Evidence ledger
An outlier is a Reel that materially exceeds a relevant baseline, such as views relative to followers or the creator's recent median. Raw views alone are not enough.
No. It ranks evidence, identifies patterns, and designs experiments. It does not guarantee or promise virality.
Yes, when you provide lawful public evidence, authorized API data, or a licensed/user-provided export. Missing metrics remain missing.
No. The project does not bypass access controls or include an unauthorized scraper. It processes authorized API responses, public evidence, and imported datasets.
Yes. The skill and documentation support Russian and English, and the CLI automatically detects Cyrillic scripts for the structural audit.
.
├── .codex-plugin/plugin.json
├── skills/reels-viral-strategist/
│ ├── SKILL.md
│ ├── agents/openai.yaml
│ ├── assets/
│ ├── references/
│ └── scripts/
└── tests/
Respect platform terms, privacy, copyright, rate limits, and regional advertising rules. Do not collect private data, evade access controls, impersonate creators, or make unsupported health, finance, or income claims.
MIT