feat(skills): Add social-automation collection (Facebook, Twitch)

- Facebook automation: Page management, posts, videos, Messenger - Twitch automation: Stream/channel operations via Rube MCP - Source: ComposioHQ via skill.fish - Reference material for future Composio integration - Updated SKILLS-INDEX.md Chronicler #73
2026-04-09 13:09:44 +00:00
parent 04ac8b3f04
commit c04cd86b82
4 changed files with 327 additions and 0 deletions
--- a/docs/skills/SKILLS-INDEX.md
+++ b/docs/skills/SKILLS-INDEX.md
@@ -190,6 +190,28 @@

 ---

+### social-automation (collection)
+**Location:** `docs/skills/social-automation/`  
+**Source:** skill.fish (ComposioHQ)  
+**Triggers:** Facebook automation, Twitch automation, Rube MCP, Composio, social media API
+
+**Purpose:** Platform automation via Rube MCP (Composio framework)
+
+**What It Covers:**
+- **facebook-automation.md** — Page management, posts, videos, Messenger
+- **twitch-automation.md** — Stream/channel operations
+
+**Prerequisites:**
+- Requires Rube MCP server at `https://rube.app/mcp`
+- Currently reference material (Firefrost doesn't use Rube MCP yet)
+
+**Read This When:**
+- Exploring social platform automation options
+- Considering Composio integration
+- Building automated cross-posting workflows
+
+---
+
 ### stripe-best-practices
 **Location:** `docs/skills/stripe-best-practices/SKILL.md`  
 **Source:** skill.fish (anthropics/claude-plugins-official)  
@@ -374,6 +396,10 @@ docs/skills/
 │   └── SKILL.md
 ├── postgres-patterns/
 │   └── SKILL.md
+├── social-automation/
+│   ├── README.md
+│   ├── facebook-automation.md
+│   └── twitch-automation.md
 ├── stripe-best-practices/
 │   └── SKILL.md
 └── discord-automation/          (skill collection)
--- a/docs/skills/social-automation/README.md
+++ b/docs/skills/social-automation/README.md
@@ -0,0 +1,46 @@
+# Social Automation Skills
+
+Platform automation skills using Rube MCP (Composio framework).
+
+**Requirement:** These skills require the Rube MCP server connected at `https://rube.app/mcp`
+
+---
+
+## Available Automations
+
+| Platform | File | Purpose |
+|----------|------|---------|
+| Facebook | `facebook-automation.md` | Page management, posts, videos, Messenger |
+| Twitch | `twitch-automation.md` | Stream/channel automation |
+
+---
+
+## How Rube MCP Works
+
+1. **Connect MCP server:** Add `https://rube.app/mcp` to your MCP client
+2. **Discover tools:** Call `RUBE_SEARCH_TOOLS` with your use case
+3. **Check connection:** Call `RUBE_MANAGE_CONNECTIONS` with the toolkit name
+4. **Execute:** Use `RUBE_MULTI_EXECUTE_TOOL` with discovered tool slugs
+
+---
+
+## Firefrost Use Cases
+
+### Facebook
+- Cross-post announcements to Facebook Page
+- Schedule launch posts
+- Manage community Messenger conversations
+
+### Twitch
+- Potential future streaming integration
+- Announce streams in Discord
+- Automated clip sharing
+
+---
+
+**Note:** These are reference materials. Firefrost doesn't currently use Rube MCP, but these skills document how platform automation could work if we add Composio integration.
+
+---
+
+**Source:** skill.fish (ComposioHQ)  
+**Added:** 2026-04-09 by Chronicler #73
--- a/docs/skills/social-automation/facebook-automation.md
+++ b/docs/skills/social-automation/facebook-automation.md
@@ -0,0 +1,164 @@
+---
+name: Facebook Automation
+description: "Automate Facebook Page management including post creation, scheduling, video uploads, Messenger conversations, and audience engagement via Composio"
+requires:
+  mcp:
+    - rube
+---
+
+# Facebook Automation
+
+Automate Facebook Page operations -- create and schedule posts, upload videos, manage Messenger conversations, retrieve page insights, and handle scheduled content -- all orchestrated through the Composio MCP integration.
+
+**Toolkit docs:** [composio.dev/toolkits/facebook](https://composio.dev/toolkits/facebook)
+
+---
+
+## Setup
+
+1. Connect your Facebook account through the Composio MCP server at `https://rube.app/mcp`
+2. The agent will prompt you with an authentication link if no active connection exists
+3. Once connected, all `FACEBOOK_*` tools become available for execution
+4. **Note:** This toolkit supports Facebook Pages only, not personal Facebook accounts
+
+---
+
+## Core Workflows
+
+### 1. Discover Managed Pages
+List all Facebook Pages you manage to get page IDs and access tokens for subsequent operations.
+
+**Tool:** `FACEBOOK_LIST_MANAGED_PAGES`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `fields` | string | No | Comma-separated fields (default: `id,name,access_token,category,tasks,about,link,picture`) |
+| `limit` | integer | No | Max pages per request (default: 25) |
+| `user_id` | string | No | User ID (default: `me`) |
+
+**Always run this first** to cache `page_id` values. Avoid repeating discovery calls -- cache the results.
+
+---
+
+### 2. Create & Schedule Posts
+Publish or schedule text posts with optional links on a Facebook Page.
+
+**Tool:** `FACEBOOK_CREATE_POST`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_id` | string | Yes | Numeric Page ID from managed pages |
+| `message` | string | Yes | Text content of the post |
+| `published` | boolean | No | `true` to publish immediately, `false` for draft/scheduled (default: true) |
+| `scheduled_publish_time` | integer | No | Unix UTC timestamp; must be at least 10 minutes in the future |
+| `link` | string | No | URL to include in the post |
+| `targeting` | object | No | Audience targeting specifications |
+
+**When scheduling:** Set `published=false` and provide `scheduled_publish_time` as a Unix UTC timestamp.
+
+---
+
+### 3. Create & Schedule Video Posts
+Upload and schedule video content on a Facebook Page.
+
+**Tool:** `FACEBOOK_CREATE_VIDEO_POST`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_id` | string | Yes | Numeric Page ID |
+| `file_url` | string | Conditional | URL of the video file (provide `file_url` or `video`) |
+| `video` | object | Conditional | Local file upload with `name`, `mimetype`, `s3key` |
+| `title` | string | No | Video title |
+| `description` | string | No | Video description |
+| `published` | boolean | No | Publish immediately (default: true) |
+| `scheduled_publish_time` | integer | No | Unix timestamp for scheduled publishing |
+
+---
+
+### 4. Manage Scheduled Posts
+Review, reschedule, update, or publish scheduled content.
+
+**Tools:**
+
+- **`FACEBOOK_GET_SCHEDULED_POSTS`** -- List scheduled/unpublished posts for a page
+  - `page_id` (required), `fields`, `limit` (max 100)
+- **`FACEBOOK_RESCHEDULE_POST`** -- Change the scheduled publish time
+- **`FACEBOOK_UPDATE_POST`** -- Edit caption/text on an existing post
+- **`FACEBOOK_PUBLISH_SCHEDULED_POST`** -- Publish a scheduled post immediately
+
+---
+
+### 5. Read Page Messenger Conversations
+Retrieve inbox conversations and message threads between users and your Page.
+
+**Tool:** `FACEBOOK_GET_PAGE_CONVERSATIONS`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_id` | string | Yes | The Facebook Page ID |
+| `fields` | string | No | Fields to return (default: `participants,updated_time,id`) |
+| `limit` | integer | No | Conversations to return, max 25 |
+
+Then retrieve full message threads:
+
+**Tool:** `FACEBOOK_GET_CONVERSATION_MESSAGES`
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `page_id` | string | Yes | Page ID that owns the conversation |
+| `conversation_id` | string | Yes | Conversation ID in `t_` format (e.g., `t_3638640842939952`) |
+| `fields` | string | No | Default: `id,created_time,from,to,message` |
+| `limit` | integer | No | Messages to return, max 25 |
+
+---
+
+### 6. Send Messages & Mark as Seen
+Respond to users via Messenger and mark messages as read.
+
+**Tools:**
+
+- **`FACEBOOK_SEND_MESSAGE`** -- Send a text message from the Page to a user via Messenger
+- **`FACEBOOK_MARK_MESSAGE_SEEN`** -- Mark a user's message as seen by the Page
+
+**Warning:** Both tools cause user-visible side effects. Only call after explicit confirmation.
+
+---
+
+## Known Pitfalls
+
+| Pitfall | Details |
+|---------|---------|
+| **Scheduling too close to now** | `FACEBOOK_CREATE_POST` with `scheduled_publish_time` less than ~10 minutes in the future returns HTTP 400 -- enforce a larger buffer for bulk runs |
+| **Unix UTC timestamps required** | `scheduled_publish_time` must be Unix UTC -- timezone conversion mistakes cause off-by-hours scheduling or validation failures |
+| **Cursor-based pagination** | `FACEBOOK_GET_SCHEDULED_POSTS` and `FACEBOOK_GET_PAGE_CONVERSATIONS` return subsets -- follow paging cursors to get complete data |
+| **Large conversation payloads** | Requesting embedded messages in conversations creates huge payloads -- use `FACEBOOK_GET_CONVERSATION_MESSAGES` for full threads instead |
+| **Video processing delays** | Uploaded videos may remain in processing state -- only schedule via `FACEBOOK_CREATE_VIDEO_POST` after the upload is usable |
+| **Cache page IDs** | Repeating `FACEBOOK_LIST_MANAGED_PAGES` calls adds latency -- cache `page_id` per workspace/run |
+| **Pages only** | This toolkit does not support personal Facebook accounts -- only Facebook Pages |
+| **Write operations need confirmation** | `FACEBOOK_SEND_MESSAGE` and `FACEBOOK_MARK_MESSAGE_SEEN` cause user-visible side effects -- only call after explicit user confirmation |
+
+---
+
+## Quick Reference
+
+| Tool Slug | Purpose |
+|-----------|---------|
+| `FACEBOOK_LIST_MANAGED_PAGES` | List Pages you manage with access tokens |
+| `FACEBOOK_GET_PAGE_DETAILS` | Get detailed info about a specific Page |
+| `FACEBOOK_CREATE_POST` | Create or schedule a text/link post |
+| `FACEBOOK_CREATE_VIDEO_POST` | Create or schedule a video post |
+| `FACEBOOK_GET_SCHEDULED_POSTS` | List scheduled/unpublished posts |
+| `FACEBOOK_RESCHEDULE_POST` | Change scheduled publish time |
+| `FACEBOOK_UPDATE_POST` | Edit an existing post |
+| `FACEBOOK_PUBLISH_SCHEDULED_POST` | Publish a scheduled post immediately |
+| `FACEBOOK_UPLOAD_VIDEO` | Upload a video file to a Page |
+| `FACEBOOK_GET_PAGE_CONVERSATIONS` | List Messenger inbox conversations |
+| `FACEBOOK_GET_CONVERSATION_MESSAGES` | Retrieve messages from a conversation |
+| `FACEBOOK_SEND_MESSAGE` | Send a Messenger message from the Page |
+| `FACEBOOK_MARK_MESSAGE_SEEN` | Mark a message as seen |
+| `FACEBOOK_GET_PAGE_POSTS` | Retrieve posts from a Page feed |
+| `FACEBOOK_GET_USER_PAGES` | List Pages with tasks and tokens |
+
+---
+
+*Powered by [Composio](https://composio.dev)*
--- a/docs/skills/social-automation/twitch-automation.md
+++ b/docs/skills/social-automation/twitch-automation.md
@@ -0,0 +1,91 @@
+---
+name: twitch-automation
+description: "Automate Twitch tasks via Rube MCP (Composio). Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Twitch Automation via Rube MCP
+
+Automate Twitch operations through Composio's Twitch toolkit via Rube MCP.
+
+**Toolkit docs**: [composio.dev/toolkits/twitch](https://composio.dev/toolkits/twitch)
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Twitch connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `twitch`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `twitch`
+3. If connection is not ACTIVE, follow the returned auth link to complete setup
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Tool Discovery
+
+Always discover available tools before executing workflows:
+
+```
+RUBE_SEARCH_TOOLS
+queries: [{use_case: "Twitch operations", known_fields: ""}]
+session: {generate_id: true}
+```
+
+This returns available tool slugs, input schemas, recommended execution plans, and known pitfalls.
+
+## Core Workflow Pattern
+
+### Step 1: Discover Available Tools
+
+```
+RUBE_SEARCH_TOOLS
+queries: [{use_case: "your specific Twitch task"}]
+session: {id: "existing_session_id"}
+```
+
+### Step 2: Check Connection
+
+```
+RUBE_MANAGE_CONNECTIONS
+toolkits: ["twitch"]
+session_id: "your_session_id"
+```
+
+### Step 3: Execute Tools
+
+```
+RUBE_MULTI_EXECUTE_TOOL
+tools: [{
+  tool_slug: "TOOL_SLUG_FROM_SEARCH",
+  arguments: {/* schema-compliant args from search results */}
+}]
+memory: {}
+session_id: "your_session_id"
+```
+
+## Known Pitfalls
+
+- **Always search first**: Tool schemas change. Never hardcode tool slugs or arguments without calling `RUBE_SEARCH_TOOLS`
+- **Check connection**: Verify `RUBE_MANAGE_CONNECTIONS` shows ACTIVE status before executing tools
+- **Schema compliance**: Use exact field names and types from the search results
+- **Memory parameter**: Always include `memory` in `RUBE_MULTI_EXECUTE_TOOL` calls, even if empty (`{}`)
+- **Session reuse**: Reuse session IDs within a workflow. Generate new ones for new workflows
+- **Pagination**: Check responses for pagination tokens and continue fetching until complete
+
+## Quick Reference
+
+| Operation | Approach |
+|-----------|----------|
+| Find tools | `RUBE_SEARCH_TOOLS` with Twitch-specific use case |
+| Connect | `RUBE_MANAGE_CONNECTIONS` with toolkit `twitch` |
+| Execute | `RUBE_MULTI_EXECUTE_TOOL` with discovered tool slugs |
+| Bulk ops | `RUBE_REMOTE_WORKBENCH` with `run_composio_tool()` |
+| Full schema | `RUBE_GET_TOOL_SCHEMAS` for tools with `schemaRef` |
+
+---
+*Powered by [Composio](https://composio.dev)*