Buzz

Agent skills for community management and developer relations — monitoring social mentions, drafting replies, tracking metrics, and reporting sentiment.

These skills are built to run in an agent environment (e.g. Warp/Oz, or another harness that loads skills from .agents/skills/) and are brand-neutral: configure them for your own brand, repository, and Slack workspace via environment variables. Nothing brand-specific is hardcoded.

Prerequisites

• An agent/harness that loads skills from .agents/skills/ (e.g. Warp or Oz). The reward-triage skills additionally require Warp/Oz cloud-agent orchestration — see What each skill needs.
• Python 3 — most scripts use only the standard library. Chart generation (e.g. reaction-analytics) also needs matplotlib and numpy; see requirements.txt and Setup.
• Node.js 18+ — only for the Typefully CLI.
• Optional CLIs, used by some skills: gh (GitHub metrics/PRs), a Google Workspace CLI (gog or gws, for Sheets-backed skills), and gifsicle/ffmpeg/gifski (for optimize-gif; via Homebrew on macOS).

Setup

1. Configure environment. Copy the template and fill in your own values:

   cp .env.example .env

   Set the tokens, channel IDs, and repo owner/name for the skills you plan to use. .env is git-ignored and scripts auto-load it. You only need values for the skills you actually run (see What each skill needs).
2. Understand the layout. Skills live under .agents/skills/<skill-name>/. Each has a SKILL.md plus optional scripts/, references/, fixtures/, and evals/.
3. (Optional) Install chart dependencies. Only needed for chart-generating skills (e.g. reaction-analytics); every other script uses the Python standard library.

   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt

4. Install optional tooling only for the skills you need (see Prerequisites).

Usage

There is no build step — skills are Markdown instructions (SKILL.md) plus supporting scripts. There are two ways to use them:

• Through an agent (primary). Point an agent that supports the .agents/skills/ convention (e.g. Warp/Oz) at this repo. The agent loads a skill automatically when your request matches its description — for example, "give me a daily mentions recap" triggers daily-mentions-summary. You can also ask for a skill by name.
• Running scripts directly. Many skills ship runnable scripts you can call yourself; they read config from .env or the environment. For example:

  python3 .agents/skills/reaction-analytics/scripts/collect_data.py 14

Several skills are meant to run on a schedule (daily/weekly reports). Wire them to your own scheduler, or run them as Oz scheduled agents.

Conventions

Skill docs use placeholders so nothing is tied to a specific company. Replace them (or set the matching .env values) for your own setup:

• <BRAND> — your product/company name; @your-brand — its social handle
• your-org / your-repo — your GitHub org and repository
• <CLOUD_PRODUCT> — a sub-product or platform name, if you have one
• <COMPETITOR> / @competitor_a — competitors or adjacent tools
• <TEAMMATE> / <@SLACK_MEMBER_ID> — people and Slack owners for routing
• <PRODUCT_CATEGORY> — the market/category your product competes in
• <FEATURE>, <FEATURE_A>, <FEATURE_B> — example product features
• <TOPIC_AREA> — a focus topic area for content/AEO analysis
• <INTEGRATION_A> / <INTEGRATION_B> — example third-party tools/integrations

What each skill needs

Most skills need credentials for the services they touch. Grouped by setup effort (lightest first):

• No external accounts — run immediately: read-reddit-thread (public Reddit JSON), optimize-gif (local gifsicle/ffmpeg/gifski).
• One credential or CLI: repo-metrics and top-contributor-finder (gh CLI or a GitHub token); read-tweet (an X API key).
• A Slack app + bot token(s): most monitoring, triage, and reporting skills that read or post to Slack — e.g. reaction-analytics, triage-mention, triage-community-message, weekly-metrics, and review-reply-suggestion-feedback.
• A paid/third-party account: Octolens for mention monitoring (daily-mentions-summary, weekly-sentiment-summary); Peec for AI-search/AEO (peec-content-gap, refresh-peec-aeo-snapshot); Typefully for scheduling (typefully, open-source-roundup-thread); Luma (luma-events); Google Sheets (weekly-metrics, gift-card-triage).
• Warp/Oz cloud-agent orchestration + a data warehouse: the reward-triage skills referral-fraud-check, gift-card-triage, and swag-pending-approvals delegate warehouse queries to a Warp/Oz cloud agent (via run_agents), so they require that harness plus warehouse access. On other harnesses these specific skills won't run as written.

Drafting skills (e.g. draft-brand-reply, draft-brand-tweet) mainly rely on the agent itself and need external accounts only when you publish the result.

Skills

Monitoring & reporting

• daily-mentions-summary — End-of-day recap of social mentions with sentiment score, highlights, and lowlights.
• weekly-sentiment-summary — Week-over-week sentiment report with highlights, lowlights, patterns, and competitor context.
• weekly-metrics — Computes weekly community/reach metrics from platform analytics exports (Slack, X, LinkedIn, YouTube, Reddit).
• reaction-analytics — Analytics on feed-mention reactions and responder activity: distribution, top responders, daily breakdowns, trends.
• repo-metrics — GitHub repo metrics (stars, traffic, contributors, PRs, issues) for a configured repository.

OSS/community analysis

• top-contributor-finder — Finds and ranks top external OSS contributors from GitHub PR activity, with open-PR concern summaries and outreach guidance.

Engagement

• draft-brand-reply — Drafts community replies to mentions on X, Reddit, and other platforms.
• draft-brand-tweet — Drafts brand-account tweets.
• discover-viral-posts — Surfaces trending posts worth engaging with.
• triage-mention — Triggered by a mentions webhook. Gathers thread context, triages, and posts to the feed-mentions channel with the result inline.
• triage-community-message — Scans community Slack channels, filters unanswered relevant messages, drafts suggested replies, and posts cards.
• changelog-social-swarm — Scans merged PRs for changelog entries and drafts a weekly content plan.

Learning & feedback loops

• reply-learning — Extracts patterns from reply feedback and codifies them into draft-brand-reply.
• review-reply-suggestion-feedback — Reviews mention feedback and opens a PR to improve draft-brand-reply if patterns emerge.

Rewards / reward-ops (optional, require extra config)

• referral-fraud-check, gift-card-triage, swag-pending-approvals — Reward-approval triage backed by a data warehouse. These require warehouse and reward-platform configuration; see each SKILL.md.

Customer channels (optional)

• customer-channel-analysis, customer-channel-share-recommendations — Analyze shared/customer Slack channels and recommend content to share.

Utilities

• read-tweet — Reads a public X/Twitter post and its reply chain via the X API.
• read-reddit-thread — Fetches a Reddit post and its full comment tree.
• recent-content-inventory — Inventories recent brand content from configured sources (YouTube, blog, changelog, docs, X).

Integrations

• Octolens — brand mention monitoring (MCP server)
• Slack — posting summaries, DMs, and reply suggestions (BUZZ_SLACK_TOKEN); reading community/customer Slack (COMMUNITY_SLACK_TOKEN)
• X API — reading posts (X_API_KEY)
• Typefully — scheduling social posts (TYPEFULLY_API_KEY)

All channel IDs, tokens, repo names, brand handles, and infrastructure IDs are configured via .env — see .env.example for the full list.

AEO snapshots

aeo-snapshots/docs/example-topic/ stores normalized signals for a scheduled docs cross-link audit, scoped to one <TOPIC_AREA>. Generate snapshots with scripts/generate_peec_aeo_snapshot.py after collecting Peec MCP data in an OAuth-capable local agent session. The committed snapshot is a synthetic sample.

Data & reports

data/ and reports/ contain synthetic sample files only. Do not commit real exports, analytics, or generated reports — they may contain sensitive or confidential data.

Contributing & security

See CONTRIBUTING.md and SECURITY.md. Licensed under MIT; vendored third-party code is noted in THIRD_PARTY_NOTICES.md.