# Changelog Social Swarm

> Weekly skill that scans merged PRs in your internal repo for CHANGELOG entries, categorizes them into topic buckets, drafts tweet suggestions, and posts a structured summary to #social-swarm on Slack for the team to pick up. Use when asked to "generate the social swarm post", "what's tweet-worthy this week", or "run the changelog bot".

- Skill: `warpdotdev/changelog-social-swarm` (Agent Skill)
- Install (CLI): `npx skillmds@latest add warpdotdev/changelog-social-swarm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/changelog-social-swarm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/changelog-social-swarm

---


# Changelog → Social Swarm

Weekly content plan for `#social-swarm`. Scans merged PRs in `your-org/your-repo-internal`, extracts changelog entries, buckets them by topic, drafts tweet suggestions, and posts a structured Slack message for the team to pick up.

## Inputs

Optional:
- **Lookback window** — days to scan (default: 7)
- **Release version** — specific stable tag to anchor around (default: latest)

## Workflow

### Step 1: Fetch merged PRs with changelog entries

Use `gh` to pull recent merged PRs:

```bash
gh api "repos/your-org/your-repo-internal/pulls?state=closed&sort=updated&direction=desc&per_page=100" --paginate
```

For each PR:
- Skip if `merged_at` is null or older than the lookback window.
- Parse the body for `CHANGELOG-*` entries:
  ```
  CHANGELOG-(NEW-FEATURE|IMPROVEMENT|BUG-FIX|HIGHLIGHT|IMAGE):\s*(.+)
  ```
- Discard entries containing `{{` (unfilled template placeholders).
- Collect: PR number, title, author login, `merged_at`, HTML URL, parsed entries.

If zero changelog entries found, post a short "quiet week" message to Slack and stop.

### Step 2: Categorize into buckets

Assign each entry to exactly one bucket. Customize these buckets, owners, and
keyword hints for your product. Example:

- **Performance** (<TEAMMATE>) — perf, memory, startup, latency, speed, faster
- **Platform** (<TEAMMATE>) — platform support, OS-specific fixes, cross-platform
- **<FEATURE_A>** (<TEAMMATE>) — keywords for one of your product areas
- **<FEATURE_B>** (<TEAMMATE>) — keywords for another product area
- **General** (team) — catch-all

Rules:
1. A typed entry (e.g. `CHANGELOG-<TYPE>`) maps to its matching bucket regardless of text.
2. Keyword match against entry text + PR title (case-insensitive). Single match → that bucket.
3. Multiple or zero matches → use judgment, default to **General**.

Update the owner names and Slack member IDs here as team assignments change. When posting, tag owners with `<@SLACK_MEMBER_ID>` if the ID is filled in; otherwise use the name as plain text.

### Step 3: Rate tweet-worthiness

Rate each entry:
- 🟢 **Tweet-worthy** — user-visible, interesting to devs, good for social
- 🟡 **Maybe** — could work with the right angle or asset
- 🔴 **Skip** — too minor, internal, or uninteresting externally

Heuristic:
- `NEW-FEATURE` → almost always 🟢
- `HIGHLIGHT` → usually 🟢 (entries in your key product narrative)
- `IMPROVEMENT` → 🟢 if it solves a common pain point, otherwise 🟡
- `BUG-FIX` → 🟢 only if widely reported, otherwise 🔴
- `IMAGE` → skip (changelog images, not social content)

### Step 4: Draft tweet suggestions

For each 🟢 or 🟡 item, draft a 1-2 sentence tweet.

Read `.agents/skills/draft-brand-tweet/style-notes.md` for voice. Key points:
- Product-first and direct
- Human, not corporate
- No hashtags, one emoji max
- Phrases like "You can now...", "We just added...", "Fixed the ... issue."
- Avoid banned phrases and AI writing tells from the style notes

For each item, also recommend an asset type:
- 🎬 GIF demo (5-10s) — new UI features
- 📸 Screenshot — visual changes
- 📊 Chart — performance improvements
- 📝 Text-only — minor improvements or fixes

### Step 5: Build posting schedule

Spread 🟢 items across the week:
- ~2 posts per weekday (Mon–Fri)
- Strongest items Monday/Tuesday
- Lighter items Thursday/Friday
- Group related items that could be a single post

### Step 6: Post to Slack

Post a single message to `#social-swarm` using the Slack blocks API. Use `$BUZZ_SLACK_TOKEN` via `os.environ` and read the channel ID from `$SOCIAL_SWARM_CHANNEL_ID`. Never echo, log, or hardcode the token.

Message format (mrkdwn):

```
📋 *Social Swarm — Week of <DATE>*
<COUNT> tweet-worthy items from <PR_COUNT> merged PRs

---

*Performance* — <@OWNER>
🟢 *<changelog entry>*
> <suggested tweet copy>
🎬 Asset: GIF demo | 📅 Post: Tuesday
<PR_URL|PR #NNN>

*<FEATURE_A>* — <@OWNER>
🟢 *<changelog entry>*
> <suggested tweet copy>
📝 Asset: Text-only | 📅 Post: Wednesday
<PR_URL|PR #NNN>

---
🔴 *Skipped* (N items): <brief comma-separated list>
```

Use Python with `urllib.request` and `json` to build the payload and post via `chat.postMessage`. Set `unfurl_links: false` and `unfurl_media: false`.

## Edge Cases

- **Zero entries**: Post a short "quiet week — nothing tweet-worthy" message and stop.
- **Missing env vars**: `BUZZ_SLACK_TOKEN` or `SOCIAL_SWARM_CHANNEL_ID` not set → log error, do not attempt to post.
- **`gh` auth failure**: Log error and stop.
- **Very few items** (<3): Still post, but note the light week.

## Constraints

- Do NOT fabricate changelog entries, PR numbers, or metrics.
- Do NOT post multiple messages — one structured Slack message.
- Do NOT include the Slack token in any output, log, or file.
- Keep tweet suggestions grounded in the actual changelog text.
- Follow `draft-brand-tweet/style-notes.md` voice for all copy.