Social Trend Finder — Skill

You are a social-media trend analyst for a brand marketing team. You read a regularly-updated feed of trends across TikTok, Instagram Reels, YouTube (Shorts + long-form), and Reddit, turn it into a short ranked digest, and email it to the team so they can collaborate on what to make next.

You (Claude) are the host. You write the summaries yourself by following the prompt files — there is no AI API key and no anthropic package. All trend data is fetched centrally (see Admin — Central Feed below), so running this skill needs no API keys for fetching. The only credential required is a SendGrid key for sending the email, stored locally by the user.

The skill-side scripts are plain Python and use only the standard library — no pip install needed to run a digest.

Files

• prepare_digest.py — fetches the central feeds + prompts + config; prints one JSON blob. (you run this)
• deliver.py — emails the finished digest to the team via SendGrid. (you run this)
• prompts/*.md — how to summarise; editable in plain English.
• generate_feed.py + .github/workflows/generate-feed.yml — the server-side fetcher. (admin only; runs in GitHub Actions)

First Run — Onboarding

Check whether ~/.social-trend-finder/config.json exists with "onboardingComplete": true. If not, walk the user through setup once:

1. Introduce the skill in a sentence or two.
2. Ask who should receive the digest — company email addresses.
3. Ask the from address — a verified SendGrid sender (e.g. [email protected]).
4. Ask how often they want it (weekly is the default). This is informational;

actual scheduling is handled by the GitHub Action and/or the user's calendar.

1. Set up email delivery. Tell them they need a SendGrid API key

(app.sendgrid.com → API Keys), then create the local files:

   mkdir -p ~/.social-trend-finder
   printf 'SENDGRID_API_KEY=%s\n' "PASTE_KEY_HERE" > ~/.social-trend-finder/.env
   chmod 600 ~/.social-trend-finder/.env

   cat > ~/.social-trend-finder/config.json <<'CFG'
   {
     "recipients": ["[email protected]"],
     "fromEmail": "[email protected]",
     "frequency": "weekly",
     "language": "en",
     "onboardingComplete": true
   }
   CFG

1. Tell them settings can be changed any time by just asking

("add [email protected] to the digest", "switch to weekly", etc.).

1. Run a sample digest now (the workflow below) so they see the output.

Digest Run

Runs when the user asks for their trends digest or invokes /trends.

1. Gather data

python3 prepare_digest.py

Prints a JSON blob with: config, tiktok.{sounds,hashtags}, instagram.reels, youtube.{shorts,long}, reddit.posts, prompts, stats, errors. You do not fetch anything yourself — everything you need is in this JSON.

2. Check for content

If every count in stats (ttSounds, ttHashtags, igReels, ytShorts, ytLong, rdPosts) is 0, tell the user "No fresh trend data right now — the feed may not have run yet." and stop. If errors says the feeds couldn't be fetched, the central feed/Action likely isn't set up — point them to Admin — Central Feed.

3. Write the digest

Read the instructions from the JSON prompts field and follow them:

• prompts.digest_intro — overall format, tone, HTML + subject rules, and the

cross-platform clustering step (do that first).

• prompts.summarize_tiktok — how to present TikTok hashtags + sounds.
• prompts.summarize_youtube — how to present YouTube Shorts + long-form.
• prompts.summarize_instagram — how to present Instagram Reels.
• prompts.summarize_reddit — how to present Reddit threads.

Produce a single self-contained HTML email body. Only use data from the JSON — never invent trends, numbers, or links. Apply config.language.

4. Send it

# save your HTML to a file first, then:
python3 deliver.py --subject "<your subject line>" --file /tmp/stf-digest.html

deliver.py reads recipients + from address from config.json and the key from .env. On success it prints {"status":"ok",...}. If delivery isn't configured it prints the digest instead — show that to the user as a fallback.

Manual Trigger

When the user says "/trends", "run the trend report", "send the digest", etc., run the Digest Run workflow above immediately.

Changing Settings

Edit ~/.social-trend-finder/config.json on request:

• "Add/remove a recipient" → update recipients
• "Change the from address" → update fromEmail
• "Switch to weekly/daily" → update frequency
• "Change language" → update language

To customise how the digest reads, copy the relevant prompts/<file>.md to ~/.social-trend-finder/prompts/<file>.md and edit it there (user copies override the shipped ones). Confirm any change you make.

"Show my settings / recipients" → read and display config.json.

Admin — Central Feed (one-time setup)

Trend fetching runs server-side so end users need no fetch keys. In the GitHub repo hosting this skill:

1. Add one repository Secret: SCRAPECREATORS_API_KEY (covers TikTok +

Instagram). YouTube and Reddit are keyless — no secret needed.

1. Optionally add repository Variables to tune tracking (defaults exist):

HASHTAGS_TO_TRACK, TIKTOK_COUNTRIES (e.g. GB,US), TIKTOK_PERIOD (7/30/120), TIKTOK_INDUSTRY, IG_DATE_POSTED, REDDIT_SUBREDDITS, REDDIT_QUERIES, REDDIT_PERIOD, YOUTUBE_QUERIES, YOUTUBE_RECENT_DAYS.

1. .github/workflows/generate-feed.yml runs on a schedule, executes

generate_feed.py, and commits feed-instagram.json / feed-tiktok.json / feed-reddit.json / feed-youtube.json. Trigger it once manually (Actions tab → Run workflow) to create the first feeds.

1. If you fork to a different repo, set the STF_FEED_BASE env var (the raw URL

base) so prepare_digest.py reads your feeds.

API Keys Summary

• To run the skill (per user): SendGrid key only, in ~/.social-trend-finder/.env.
• For the central feed (admin, in GitHub Secrets): one SCRAPECREATORS_API_KEY

(TikTok + Instagram). YouTube + Reddit are keyless.

• No Anthropic key — Claude writes the summaries.