/content-ideas

name: content-ideas
version: "2.2.0"
description: >
  Your For You page for content creators. Scrapes tracked competitors across
  social media platforms, scores what's performing, and turns it into actionable, differentiated content ideas backed
  by real engagement data. Use this whenever the user wants competitor/creator
  research, a content feed or "for you" page, trending-topic ideas in their
  niche, to see what's working on social, to track what creators are posting,
  or to generate video/post briefs from what's performing — even if they don't
  say "find ideas." First run walks through setup.
argument-hint: "[topic filter]"
user-invocable: true
allowed-tools: Bash, Read, Write, AskUserQuestion
metadata:
  requires:
    env:
      - SCRAPECREATORS_API_KEY
    bins:
      - python3

content-ideas

Your For You page. Scrapes every platform where your tracked creators publish, scores what's performing, and turns it into content ideas you can act on. Designed to run daily — each run creates a dated feed under `$CONTENT_HOME/research/`.

The output is a single self-contained HTML page (two tabs: **Posts** — one sortable, filterable feed merging tracked-account posts and discovered niche outliers — and **Ideas**) that you can open in a browser, react to, and keep. Reactions are captured for future personalization.

Resolve the skill directory

Everything this skill runs lives under its own folder. The skill installs the same way on Claude Code and Codex, so resolve `SKILL_DIR` against both plugin caches (and a plain repo checkout) once, before anything else:

# 1) Codex plugin cache, or a repo cloned into ~/.codex/skills/ (latest wins on upgrade).
SKILL_DIR="$(ls -d "$HOME/.codex/plugins/cache/"*/content-ideas/*/skills/content-ideas/ "$HOME/.codex/skills/"*/skills/content-ideas/ 2>/dev/null | sort -V | tail -1)"
SKILL_DIR="${SKILL_DIR%/}"

# 2) Claude Code plugin cache.
if [ -z "$SKILL_DIR" ] || [ ! -f "$SKILL_DIR/scripts/scrape.py" ]; then
  CLAUDE_ROOT="$(ls -d "$HOME/.claude/plugins/cache/content-ideas/content-ideas/"*/ 2>/dev/null | sort -V | tail -1)"
  CLAUDE_ROOT="${CLAUDE_ROOT%/}"
  [ -n "$CLAUDE_ROOT" ] && [ -f "$CLAUDE_ROOT/skills/content-ideas/scripts/scrape.py" ] && SKILL_DIR="$CLAUDE_ROOT/skills/content-ideas"
fi

# 3) Plugin root passed by the host, or a repo checkout / local dev.
if [ -z "$SKILL_DIR" ] || [ ! -f "$SKILL_DIR/scripts/scrape.py" ]; then
  for dir in "${CLAUDE_PLUGIN_ROOT:-}/skills/content-ideas" "${CLAUDE_PLUGIN_ROOT:-}" "${GEMINI_EXTENSION_DIR:-}/skills/content-ideas" "./skills/content-ideas" "."; do
    [ -n "$dir" ] && [ -f "$dir/scripts/scrape.py" ] && SKILL_DIR="$dir" && break
  done
fi

echo "$SKILL_DIR"

If you can already see this file's path, just use its directory. The two scripts you'll call are `$SKILL_DIR/scripts/scrape.py` and `$SKILL_DIR/scripts/generate_feed.py`. The renderer template is `$SKILL_DIR/assets/for-you-template.html` (the generator finds it automatically).

Resolve the content home

All persistent files this skill reads and writes — the `brand/` profile and the dated `research/` runs — live under one stable base, **never** the current working directory. The skill runs daily and is invoked from anywhere, so the base must be the same every time or it loses the profile and the run history. Resolve it once and capture the concrete path:

CONTENT_HOME="${CONTENT_HOME:-$HOME/Documents/Content}"
mkdir -p "$CONTENT_HOME/brand" "$CONTENT_HOME/research"
echo "$CONTENT_HOME"

Throughout this guide every `brand/...` and `research/...` path is relative to `$CONTENT_HOME` (so `brand/profile.md` means `$CONTENT_HOME/brand/profile.md`). **Use the printed absolute path for every Read/Write of those files** — the file tools don't expand shell variables, so writing a bare `brand/profile.md` would land it in the wrong directory. (Credentials stay separate, in `~/.config/content/.env`.) The scrape/generate scripts read `CONTENT_HOME` themselves, so a relative `research/{today}` passed to them resolves here too.

---

Step 0: First-run setup

**Run this before anything else, even if the user gave a topic.** Detect first run by checking whether `~/.config/content/.env` exists and contains `SETUP_COMPLETE=true`. Check silently. If it's already set up, skip to Step 1.

0a. Welcome + API key

Setup has three quick parts: an API key, **your** profile (built from your own channels), and the competitors you want to track. Only the key is required — the rest the skill bootstraps for you and you can refine any time. Nothing to install; one ScrapeCreators API key covers all four platforms — X, Instagram, TikTok, and YouTube (including transcripts).

Show this as a normal message, then call `AskUserQuestion` (don't repeat the welcome inside the modal):

> I turn your social presence into a daily For You feed: I build a profile from > your own channels, track the competitors you pick, and surface what's > performing as content ideas backed by real engagement. I just need a > ScrapeCreators API key (one key covers all four platforms; 100 free calls, no > card).

`AskUserQuestion` — "Add your ScrapeCreators API key?"

• Open scrapecreators.com to grab a free key
• I'll paste a key now
• Skip for now

If they pick "Open scrapecreators.com", run `open https://scrapecreators.com`, then ask them to paste the key. When the user pastes a key, write `~/.config/content/.env` (create dirs; append, don't clobber other keys):

SCRAPECREATORS_API_KEY={key}
SETUP_COMPLETE=true

If they skip, write only `SETUP_COMPLETE=true`.

0b. Manual alternative

If they'd rather configure by hand, tell them to add those two lines to `~/.config/content/.env`. Offer to write the file if they paste the key here.

0c. Build your brand profile

This is what personalizes everything: ideas get framed against *your* niche, pillars, and goal, and checked against what you've already posted. Build it from the user's own presence rather tha