skill-library-mcp 1.0.0

package/skills/klaviyo-automation/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: klaviyo-automation
+description: "Automate Klaviyo tasks via Rube MCP (Composio): manage email/SMS campaigns, inspect campaign messages, track tags, and monitor send jobs. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Klaviyo Automation via Rube MCP
+
+Automate Klaviyo email and SMS marketing operations through Composio's Klaviyo toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Klaviyo connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `klaviyo`
+- 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 `klaviyo`
+3. If connection is not ACTIVE, follow the returned auth link to complete Klaviyo authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. List and Filter Campaigns
+
+**When to use**: User wants to browse, search, or filter marketing campaigns
+
+**Tool sequence**:
+1. `KLAVIYO_GET_CAMPAIGNS` - List campaigns with channel and status filters [Required]
+
+**Key parameters**:
+- `channel`: Campaign channel - 'email' or 'sms' (required by Klaviyo API)
+- `filter`: Additional filter string (e.g., `equals(status,"draft")`)
+- `sort`: Sort field with optional `-` prefix for descending (e.g., '-created_at', 'name')
+- `page_cursor`: Pagination cursor for next page
+- `include_archived`: Include archived campaigns (default: false)
+
+**Pitfalls**:
+- `channel` is required; omitting it can produce incomplete or unexpected results
+- Pagination is mandatory for full coverage; a single call returns only one page (default ~10)
+- Follow `page_cursor` until exhausted to get all campaigns
+- Status filtering via `filter` (e.g., `equals(status,"draft")`) can return mixed statuses; always validate `data[].attributes.status` client-side
+- Status strings are case-sensitive and can be compound (e.g., 'Cancelled: No Recipients')
+- Response shape is nested: `response.data.data` with status at `data[].attributes.status`
+
+### 2. Get Campaign Details
+
+**When to use**: User wants detailed information about a specific campaign
+
+**Tool sequence**:
+1. `KLAVIYO_GET_CAMPAIGNS` - Find campaign to get its ID [Prerequisite]
+2. `KLAVIYO_GET_CAMPAIGN` - Retrieve full campaign details [Required]
+
+**Key parameters**:
+- `campaign_id`: Campaign ID string (e.g., '01GDDKASAP8TKDDA2GRZDSVP4H')
+- `include_messages`: Include campaign messages in response
+- `include_tags`: Include tags in response
+
+**Pitfalls**:
+- Campaign IDs are alphanumeric strings, not numeric
+- `include_messages` and `include_tags` add related data to the response via Klaviyo's include mechanism
+- Campaign details include audiences, send strategy, tracking options, and scheduling info
+
+### 3. Inspect Campaign Messages
+
+**When to use**: User wants to view the email/SMS content of a campaign
+
+**Tool sequence**:
+1. `KLAVIYO_GET_CAMPAIGN` - Find campaign and its message IDs [Prerequisite]
+2. `KLAVIYO_GET_CAMPAIGN_MESSAGE` - Get message content details [Required]
+
+**Key parameters**:
+- `id`: Message ID string
+- `fields__campaign__message`: Sparse fieldset for message attributes (e.g., 'content.subject', 'content.from_email', 'content.body')
+- `fields__campaign`: Sparse fieldset for campaign attributes
+- `fields__template`: Sparse fieldset for template attributes
+- `include`: Related resources to include ('campaign', 'template')
+
+**Pitfalls**:
+- Message IDs are separate from campaign IDs; extract from campaign response
+- Sparse fieldset syntax uses dot notation for nested fields: 'content.subject', 'content.from_email'
+- Email messages have content fields: subject, preview_text, from_email, from_label, reply_to_email
+- SMS messages have content fields: body
+- Including 'template' provides the HTML/text content of the email
+
+### 4. Manage Campaign Tags
+
+**When to use**: User wants to view tags associated with campaigns for organization
+
+**Tool sequence**:
+1. `KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS` - Get tag IDs for a campaign [Required]
+
+**Key parameters**:
+- `id`: Campaign ID string
+
+**Pitfalls**:
+- Returns only tag IDs, not tag names/details
+- Tag IDs can be used with Klaviyo's tag endpoints for full details
+- Rate limit: 3/s burst, 60/m steady (stricter than other endpoints)
+
+### 5. Monitor Campaign Send Jobs
+
+**When to use**: User wants to check the status of a campaign send operation
+
+**Tool sequence**:
+1. `KLAVIYO_GET_CAMPAIGN_SEND_JOB` - Check send job status [Required]
+
+**Key parameters**:
+- `id`: Send job ID
+
+**Pitfalls**:
+- Send job IDs are returned when a campaign send is initiated
+- Job statuses indicate whether the send is queued, in progress, complete, or failed
+- Rate limit: 10/s burst, 150/m steady
+
+## Common Patterns
+
+### Campaign Discovery Pattern
+
+```
+1. Call KLAVIYO_GET_CAMPAIGNS with channel='email'
+2. Paginate through all results via page_cursor
+3. Filter by status client-side for accuracy
+4. Extract campaign IDs for detailed inspection
+```
+
+### Sparse Fieldset Pattern
+
+Klaviyo supports sparse fieldsets to reduce response size:
+```
+fields__campaign__message=['content.subject', 'content.from_email', 'send_times']
+fields__campaign=['name', 'status', 'send_time']
+fields__template=['name', 'html', 'text']
+```
+
+### Pagination
+
+- Klaviyo uses cursor-based pagination
+- Check response for `page_cursor` in the pagination metadata
+- Pass cursor as `page_cursor` in next request
+- Default page size is ~10 campaigns
+- Continue until no more cursor is returned
+
+### Filter Syntax
+
+```
+- equals(status,"draft") - Campaigns in draft status
+- equals(name,"Newsletter") - Campaign named "Newsletter"
+- greater-than(created_at,"2024-01-01T00:00:00Z") - Created after date
+```
+
+## Known Pitfalls
+
+**API Version**:
+- Klaviyo API uses versioned endpoints (e.g., v2024-07-15)
+- Response schemas may change between API versions
+- Tool responses follow the version configured in the Composio integration
+
+**Response Nesting**:
+- Data is nested: `response.data.data[].attributes`
+- Campaign status at `data[].attributes.status`
+- Mis-parsing the nesting yields empty or incorrect results
+- Always navigate through the full path defensively
+
+**Rate Limits**:
+- Burst: 10/s (3/s for tag endpoints)
+- Steady: 150/m (60/m for tag endpoints)
+- Required scope: campaigns:read
+- Implement backoff on 429 responses
+
+**Status Values**:
+- Status strings are case-sensitive
+- Compound statuses exist (e.g., 'Cancelled: No Recipients')
+- Server-side filtering may return mixed statuses; always validate client-side
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List campaigns | KLAVIYO_GET_CAMPAIGNS | channel, filter, sort, page_cursor |
+| Get campaign details | KLAVIYO_GET_CAMPAIGN | campaign_id, include_messages, include_tags |
+| Get campaign message | KLAVIYO_GET_CAMPAIGN_MESSAGE | id, fields__campaign__message |
+| Get campaign tags | KLAVIYO_GET_CAMPAIGN_RELATIONSHIPS_TAGS | id |
+| Get send job status | KLAVIYO_GET_CAMPAIGN_SEND_JOB | id |

package/skills/kpi-dashboard-design/SKILL.md

@@ -0,0 +1,440 @@
+---
+name: kpi-dashboard-design
+description: Design effective KPI dashboards with metrics selection, visualization best practices, and real-time monitoring patterns. Use when building business dashboards, selecting metrics, or designing data visualization layouts.
+---
+
+# KPI Dashboard Design
+
+Comprehensive patterns for designing effective Key Performance Indicator (KPI) dashboards that drive business decisions.
+
+## Do not use this skill when
+
+- The task is unrelated to kpi dashboard design
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Designing executive dashboards
+- Selecting meaningful KPIs
+- Building real-time monitoring displays
+- Creating department-specific metrics views
+- Improving existing dashboard layouts
+- Establishing metric governance
+
+## Core Concepts
+
+### 1. KPI Framework
+
+| Level           | Focus            | Update Frequency  | Audience   |
+| --------------- | ---------------- | ----------------- | ---------- |
+| **Strategic**   | Long-term goals  | Monthly/Quarterly | Executives |
+| **Tactical**    | Department goals | Weekly/Monthly    | Managers   |
+| **Operational** | Day-to-day       | Real-time/Daily   | Teams      |
+
+### 2. SMART KPIs
+
+```
+Specific: Clear definition
+Measurable: Quantifiable
+Achievable: Realistic targets
+Relevant: Aligned to goals
+Time-bound: Defined period
+```
+
+### 3. Dashboard Hierarchy
+
+```
+├── Executive Summary (1 page)
+│   ├── 4-6 headline KPIs
+│   ├── Trend indicators
+│   └── Key alerts
+├── Department Views
+│   ├── Sales Dashboard
+│   ├── Marketing Dashboard
+│   ├── Operations Dashboard
+│   └── Finance Dashboard
+└── Detailed Drilldowns
+    ├── Individual metrics
+    └── Root cause analysis
+```
+
+## Common KPIs by Department
+
+### Sales KPIs
+
+```yaml
+Revenue Metrics:
+  - Monthly Recurring Revenue (MRR)
+  - Annual Recurring Revenue (ARR)
+  - Average Revenue Per User (ARPU)
+  - Revenue Growth Rate
+
+Pipeline Metrics:
+  - Sales Pipeline Value
+  - Win Rate
+  - Average Deal Size
+  - Sales Cycle Length
+
+Activity Metrics:
+  - Calls/Emails per Rep
+  - Demos Scheduled
+  - Proposals Sent
+  - Close Rate
+```
+
+### Marketing KPIs
+
+```yaml
+Acquisition:
+  - Cost Per Acquisition (CPA)
+  - Customer Acquisition Cost (CAC)
+  - Lead Volume
+  - Marketing Qualified Leads (MQL)
+
+Engagement:
+  - Website Traffic
+  - Conversion Rate
+  - Email Open/Click Rate
+  - Social Engagement
+
+ROI:
+  - Marketing ROI
+  - Campaign Performance
+  - Channel Attribution
+  - CAC Payback Period
+```
+
+### Product KPIs
+
+```yaml
+Usage:
+  - Daily/Monthly Active Users (DAU/MAU)
+  - Session Duration
+  - Feature Adoption Rate
+  - Stickiness (DAU/MAU)
+
+Quality:
+  - Net Promoter Score (NPS)
+  - Customer Satisfaction (CSAT)
+  - Bug/Issue Count
+  - Time to Resolution
+
+Growth:
+  - User Growth Rate
+  - Activation Rate
+  - Retention Rate
+  - Churn Rate
+```
+
+### Finance KPIs
+
+```yaml
+Profitability:
+  - Gross Margin
+  - Net Profit Margin
+  - EBITDA
+  - Operating Margin
+
+Liquidity:
+  - Current Ratio
+  - Quick Ratio
+  - Cash Flow
+  - Working Capital
+
+Efficiency:
+  - Revenue per Employee
+  - Operating Expense Ratio
+  - Days Sales Outstanding
+  - Inventory Turnover
+```
+
+## Dashboard Layout Patterns
+
+### Pattern 1: Executive Summary
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  EXECUTIVE DASHBOARD                        [Date Range ▼]  │
+├─────────────┬─────────────┬─────────────┬─────────────────┤
+│   REVENUE   │   PROFIT    │  CUSTOMERS  │    NPS SCORE    │
+│   $2.4M     │    $450K    │    12,450   │       72        │
+│   ▲ 12%     │    ▲ 8%     │    ▲ 15%    │     ▲ 5pts     │
+├─────────────┴─────────────┴─────────────┴─────────────────┤
+│                                                             │
+│  Revenue Trend                    │  Revenue by Product     │
+│  ┌───────────────────────┐       │  ┌──────────────────┐   │
+│  │    /\    /\          │       │  │ ████████ 45%     │   │
+│  │   /  \  /  \    /\   │       │  │ ██████   32%     │   │
+│  │  /    \/    \  /  \  │       │  │ ████     18%     │   │
+│  │ /            \/    \ │       │  │ ██        5%     │   │
+│  └───────────────────────┘       │  └──────────────────┘   │
+│                                                             │
+├─────────────────────────────────────────────────────────────┤
+│  🔴 Alert: Churn rate exceeded threshold (>5%)              │
+│  🟡 Warning: Support ticket volume 20% above average        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Pattern 2: SaaS Metrics Dashboard
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  SAAS METRICS                     Jan 2024  [Monthly ▼]     │
+├──────────────────────┬──────────────────────────────────────┤
+│  ┌────────────────┐  │  MRR GROWTH                          │
+│  │      MRR       │  │  ┌────────────────────────────────┐  │
+│  │    $125,000    │  │  │                          /──   │  │
+│  │     ▲ 8%       │  │  │                    /────/      │  │
+│  └────────────────┘  │  │              /────/            │  │
+│  ┌────────────────┐  │  │        /────/                  │  │
+│  │      ARR       │  │  │   /────/                       │  │
+│  │   $1,500,000   │  │  └────────────────────────────────┘  │
+│  │     ▲ 15%      │  │  J  F  M  A  M  J  J  A  S  O  N  D  │
+│  └────────────────┘  │                                      │
+├──────────────────────┼──────────────────────────────────────┤
+│  UNIT ECONOMICS      │  COHORT RETENTION                    │
+│                      │                                      │
+│  CAC:     $450       │  Month 1: ████████████████████ 100%  │
+│  LTV:     $2,700     │  Month 3: █████████████████    85%   │
+│  LTV/CAC: 6.0x       │  Month 6: ████████████████     80%   │
+│                      │  Month 12: ██████████████      72%   │
+│  Payback: 4 months   │                                      │
+├──────────────────────┴──────────────────────────────────────┤
+│  CHURN ANALYSIS                                             │
+│  ┌──────────┬──────────┬──────────┬──────────────────────┐ │
+│  │ Gross    │ Net      │ Logo     │ Expansion            │ │
+│  │ 4.2%     │ 1.8%     │ 3.1%     │ 2.4%                 │ │
+│  └──────────┴──────────┴──────────┴──────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Pattern 3: Real-time Operations
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  OPERATIONS CENTER                    Live ● Last: 10:42:15 │
+├────────────────────────────┬────────────────────────────────┤
+│  SYSTEM HEALTH             │  SERVICE STATUS                │
+│  ┌──────────────────────┐  │                                │
+│  │   CPU    MEM    DISK │  │  ● API Gateway      Healthy    │
+│  │   45%    72%    58%  │  │  ● User Service     Healthy    │
+│  │   ███    ████   ███  │  │  ● Payment Service  Degraded   │
+│  │   ███    ████   ███  │  │  ● Database         Healthy    │
+│  │   ███    ████   ███  │  │  ● Cache            Healthy    │
+│  └──────────────────────┘  │                                │
+├────────────────────────────┼────────────────────────────────┤
+│  REQUEST THROUGHPUT        │  ERROR RATE                    │
+│  ┌──────────────────────┐  │  ┌──────────────────────────┐  │
+│  │ ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅ │  │  │ ▁▁▁▁▁▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁  │  │
+│  └──────────────────────┘  │  └──────────────────────────┘  │
+│  Current: 12,450 req/s     │  Current: 0.02%                │
+│  Peak: 18,200 req/s        │  Threshold: 1.0%               │
+├────────────────────────────┴────────────────────────────────┤
+│  RECENT ALERTS                                              │
+│  10:40  🟡 High latency on payment-service (p99 > 500ms)    │
+│  10:35  🟢 Resolved: Database connection pool recovered     │
+│  10:22  🔴 Payment service circuit breaker tripped          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Implementation Patterns
+
+### SQL for KPI Calculations
+
+```sql
+-- Monthly Recurring Revenue (MRR)
+WITH mrr_calculation AS (
+    SELECT
+        DATE_TRUNC('month', billing_date) AS month,
+        SUM(
+            CASE subscription_interval
+                WHEN 'monthly' THEN amount
+                WHEN 'yearly' THEN amount / 12
+                WHEN 'quarterly' THEN amount / 3
+            END
+        ) AS mrr
+    FROM subscriptions
+    WHERE status = 'active'
+    GROUP BY DATE_TRUNC('month', billing_date)
+)
+SELECT
+    month,
+    mrr,
+    LAG(mrr) OVER (ORDER BY month) AS prev_mrr,
+    (mrr - LAG(mrr) OVER (ORDER BY month)) / LAG(mrr) OVER (ORDER BY month) * 100 AS growth_pct
+FROM mrr_calculation;
+
+-- Cohort Retention
+WITH cohorts AS (
+    SELECT
+        user_id,
+        DATE_TRUNC('month', created_at) AS cohort_month
+    FROM users
+),
+activity AS (
+    SELECT
+        user_id,
+        DATE_TRUNC('month', event_date) AS activity_month
+    FROM user_events
+    WHERE event_type = 'active_session'
+)
+SELECT
+    c.cohort_month,
+    EXTRACT(MONTH FROM age(a.activity_month, c.cohort_month)) AS months_since_signup,
+    COUNT(DISTINCT a.user_id) AS active_users,
+    COUNT(DISTINCT a.user_id)::FLOAT / COUNT(DISTINCT c.user_id) * 100 AS retention_rate
+FROM cohorts c
+LEFT JOIN activity a ON c.user_id = a.user_id
+    AND a.activity_month >= c.cohort_month
+GROUP BY c.cohort_month, EXTRACT(MONTH FROM age(a.activity_month, c.cohort_month))
+ORDER BY c.cohort_month, months_since_signup;
+
+-- Customer Acquisition Cost (CAC)
+SELECT
+    DATE_TRUNC('month', acquired_date) AS month,
+    SUM(marketing_spend) / NULLIF(COUNT(new_customers), 0) AS cac,
+    SUM(marketing_spend) AS total_spend,
+    COUNT(new_customers) AS customers_acquired
+FROM (
+    SELECT
+        DATE_TRUNC('month', u.created_at) AS acquired_date,
+        u.id AS new_customers,
+        m.spend AS marketing_spend
+    FROM users u
+    JOIN marketing_spend m ON DATE_TRUNC('month', u.created_at) = m.month
+    WHERE u.source = 'marketing'
+) acquisition
+GROUP BY DATE_TRUNC('month', acquired_date);
+```
+
+### Python Dashboard Code (Streamlit)
+
+```python
+import streamlit as st
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+
+st.set_page_config(page_title="KPI Dashboard", layout="wide")
+
+# Header with date filter
+col1, col2 = st.columns([3, 1])
+with col1:
+    st.title("Executive Dashboard")
+with col2:
+    date_range = st.selectbox(
+        "Period",
+        ["Last 7 Days", "Last 30 Days", "Last Quarter", "YTD"]
+    )
+
+# KPI Cards
+def metric_card(label, value, delta, prefix="", suffix=""):
+    delta_color = "green" if delta >= 0 else "red"
+    delta_arrow = "▲" if delta >= 0 else "▼"
+    st.metric(
+        label=label,
+        value=f"{prefix}{value:,.0f}{suffix}",
+        delta=f"{delta_arrow} {abs(delta):.1f}%"
+    )
+
+col1, col2, col3, col4 = st.columns(4)
+with col1:
+    metric_card("Revenue", 2400000, 12.5, prefix="$")
+with col2:
+    metric_card("Customers", 12450, 15.2)
+with col3:
+    metric_card("NPS Score", 72, 5.0)
+with col4:
+    metric_card("Churn Rate", 4.2, -0.8, suffix="%")
+
+# Charts
+col1, col2 = st.columns(2)
+
+with col1:
+    st.subheader("Revenue Trend")
+    revenue_data = pd.DataFrame({
+        'Month': pd.date_range('2024-01-01', periods=12, freq='M'),
+        'Revenue': [180000, 195000, 210000, 225000, 240000, 255000,
+                    270000, 285000, 300000, 315000, 330000, 345000]
+    })
+    fig = px.line(revenue_data, x='Month', y='Revenue',
+                  line_shape='spline', markers=True)
+    fig.update_layout(height=300)
+    st.plotly_chart(fig, use_container_width=True)
+
+with col2:
+    st.subheader("Revenue by Product")
+    product_data = pd.DataFrame({
+        'Product': ['Enterprise', 'Professional', 'Starter', 'Other'],
+        'Revenue': [45, 32, 18, 5]
+    })
+    fig = px.pie(product_data, values='Revenue', names='Product',
+                 hole=0.4)
+    fig.update_layout(height=300)
+    st.plotly_chart(fig, use_container_width=True)
+
+# Cohort Heatmap
+st.subheader("Cohort Retention")
+cohort_data = pd.DataFrame({
+    'Cohort': ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+    'M0': [100, 100, 100, 100, 100],
+    'M1': [85, 87, 84, 86, 88],
+    'M2': [78, 80, 76, 79, None],
+    'M3': [72, 74, 70, None, None],
+    'M4': [68, 70, None, None, None],
+})
+fig = go.Figure(data=go.Heatmap(
+    z=cohort_data.iloc[:, 1:].values,
+    x=['M0', 'M1', 'M2', 'M3', 'M4'],
+    y=cohort_data['Cohort'],
+    colorscale='Blues',
+    text=cohort_data.iloc[:, 1:].values,
+    texttemplate='%{text}%',
+    textfont={"size": 12},
+))
+fig.update_layout(height=250)
+st.plotly_chart(fig, use_container_width=True)
+
+# Alerts Section
+st.subheader("Alerts")
+alerts = [
+    {"level": "error", "message": "Churn rate exceeded threshold (>5%)"},
+    {"level": "warning", "message": "Support ticket volume 20% above average"},
+]
+for alert in alerts:
+    if alert["level"] == "error":
+        st.error(f"🔴 {alert['message']}")
+    elif alert["level"] == "warning":
+        st.warning(f"🟡 {alert['message']}")
+```
+
+## Best Practices
+
+### Do's
+
+- **Limit to 5-7 KPIs** - Focus on what matters
+- **Show context** - Comparisons, trends, targets
+- **Use consistent colors** - Red=bad, green=good
+- **Enable drilldown** - From summary to detail
+- **Update appropriately** - Match metric frequency
+
+### Don'ts
+
+- **Don't show vanity metrics** - Focus on actionable data
+- **Don't overcrowd** - White space aids comprehension
+- **Don't use 3D charts** - They distort perception
+- **Don't hide methodology** - Document calculations
+- **Don't ignore mobile** - Ensure responsive design
+
+## Resources
+
+- [Stephen Few's Dashboard Design](https://www.perceptualedge.com/articles/visual_business_intelligence/rules_for_using_color.pdf)
+- [Edward Tufte's Principles](https://www.edwardtufte.com/tufte/)
+- [Google Data Studio Gallery](https://datastudio.google.com/gallery)