skill-library-mcp 1.0.0

package/skills/amplitude-automation/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: amplitude-automation
+description: "Automate Amplitude tasks via Rube MCP (Composio): events, user activity, cohorts, user identification. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Amplitude Automation via Rube MCP
+
+Automate Amplitude product analytics through Composio's Amplitude toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Amplitude connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `amplitude`
+- 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 `amplitude`
+3. If connection is not ACTIVE, follow the returned auth link to complete Amplitude authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Send Events
+
+**When to use**: User wants to track events or send event data to Amplitude
+
+**Tool sequence**:
+1. `AMPLITUDE_SEND_EVENTS` - Send one or more events to Amplitude [Required]
+
+**Key parameters**:
+- `events`: Array of event objects, each containing:
+  - `event_type`: Name of the event (e.g., 'page_view', 'purchase')
+  - `user_id`: Unique user identifier (required if no `device_id`)
+  - `device_id`: Device identifier (required if no `user_id`)
+  - `event_properties`: Object with custom event properties
+  - `user_properties`: Object with user properties to set
+  - `time`: Event timestamp in milliseconds since epoch
+
+**Pitfalls**:
+- At least one of `user_id` or `device_id` is required per event
+- `event_type` is required for every event; cannot be empty
+- `time` must be in milliseconds (13-digit epoch), not seconds
+- Batch limit applies; check schema for maximum events per request
+- Events are processed asynchronously; successful API response does not mean data is immediately queryable
+
+### 2. Get User Activity
+
+**When to use**: User wants to view event history for a specific user
+
+**Tool sequence**:
+1. `AMPLITUDE_FIND_USER` - Find user by ID or property [Prerequisite]
+2. `AMPLITUDE_GET_USER_ACTIVITY` - Retrieve user's event stream [Required]
+
+**Key parameters**:
+- `user`: Amplitude internal user ID (from FIND_USER)
+- `offset`: Pagination offset for event list
+- `limit`: Maximum number of events to return
+
+**Pitfalls**:
+- `user` parameter requires Amplitude's internal user ID, NOT your application's user_id
+- Must call FIND_USER first to resolve your user_id to Amplitude's internal ID
+- Activity is returned in reverse chronological order by default
+- Large activity histories require pagination via `offset`
+
+### 3. Find and Identify Users
+
+**When to use**: User wants to look up users or set user properties
+
+**Tool sequence**:
+1. `AMPLITUDE_FIND_USER` - Search for a user by various identifiers [Required]
+2. `AMPLITUDE_IDENTIFY` - Set or update user properties [Optional]
+
+**Key parameters**:
+- For FIND_USER:
+  - `user`: Search term (user_id, email, or Amplitude ID)
+- For IDENTIFY:
+  - `user_id`: Your application's user identifier
+  - `device_id`: Device identifier (alternative to user_id)
+  - `user_properties`: Object with `$set`, `$unset`, `$add`, `$append` operations
+
+**Pitfalls**:
+- FIND_USER searches across user_id, device_id, and Amplitude ID
+- IDENTIFY uses special property operations (`$set`, `$unset`, `$add`, `$append`)
+- `$set` overwrites existing values; `$setOnce` only sets if not already set
+- At least one of `user_id` or `device_id` is required for IDENTIFY
+- User property changes are eventually consistent; not immediate
+
+### 4. Manage Cohorts
+
+**When to use**: User wants to list cohorts, view cohort details, or update cohort membership
+
+**Tool sequence**:
+1. `AMPLITUDE_LIST_COHORTS` - List all saved cohorts [Required]
+2. `AMPLITUDE_GET_COHORT` - Get detailed cohort information [Optional]
+3. `AMPLITUDE_UPDATE_COHORT_MEMBERSHIP` - Add/remove users from a cohort [Optional]
+4. `AMPLITUDE_CHECK_COHORT_STATUS` - Check async cohort operation status [Optional]
+
+**Key parameters**:
+- For LIST_COHORTS: No required parameters
+- For GET_COHORT: `cohort_id` (from list results)
+- For UPDATE_COHORT_MEMBERSHIP:
+  - `cohort_id`: Target cohort ID
+  - `memberships`: Object with `add` and/or `remove` arrays of user IDs
+- For CHECK_COHORT_STATUS: `request_id` from update response
+
+**Pitfalls**:
+- Cohort IDs are required for all cohort-specific operations
+- UPDATE_COHORT_MEMBERSHIP is asynchronous; use CHECK_COHORT_STATUS to verify
+- `request_id` from the update response is needed for status checking
+- Maximum membership changes per request may be limited; chunk large updates
+- Only behavioral cohorts support API membership updates
+
+### 5. Browse Event Categories
+
+**When to use**: User wants to discover available event types and categories in Amplitude
+
+**Tool sequence**:
+1. `AMPLITUDE_GET_EVENT_CATEGORIES` - List all event categories [Required]
+
+**Key parameters**:
+- No required parameters; returns all configured event categories
+
+**Pitfalls**:
+- Categories are configured in Amplitude UI; API provides read access
+- Event names within categories are case-sensitive
+- Use these categories to validate event_type values before sending events
+
+## Common Patterns
+
+### ID Resolution
+
+**Application user_id -> Amplitude internal ID**:
+```
+1. Call AMPLITUDE_FIND_USER with user=your_user_id
+2. Extract Amplitude's internal user ID from response
+3. Use internal ID for GET_USER_ACTIVITY
+```
+
+**Cohort name -> Cohort ID**:
+```
+1. Call AMPLITUDE_LIST_COHORTS
+2. Find cohort by name in results
+3. Extract id for cohort operations
+```
+
+### User Property Operations
+
+Amplitude IDENTIFY supports these property operations:
+- `$set`: Set property value (overwrites existing)
+- `$setOnce`: Set only if property not already set
+- `$add`: Increment numeric property
+- `$append`: Append to list property
+- `$unset`: Remove property entirely
+
+Example structure:
+```json
+{
+  "user_properties": {
+    "$set": {"plan": "premium", "company": "Acme"},
+    "$add": {"login_count": 1}
+  }
+}
+```
+
+### Async Operation Pattern
+
+For cohort membership updates:
+```
+1. Call AMPLITUDE_UPDATE_COHORT_MEMBERSHIP -> get request_id
+2. Call AMPLITUDE_CHECK_COHORT_STATUS with request_id
+3. Repeat step 2 until status is 'complete' or 'error'
+```
+
+## Known Pitfalls
+
+**User IDs**:
+- Amplitude has its own internal user IDs separate from your application's
+- FIND_USER resolves your IDs to Amplitude's internal IDs
+- GET_USER_ACTIVITY requires Amplitude's internal ID, not your user_id
+
+**Event Timestamps**:
+- Must be in milliseconds since epoch (13 digits)
+- Seconds (10 digits) will be interpreted as very old dates
+- Omitting timestamp uses server receive time
+
+**Rate Limits**:
+- Event ingestion has throughput limits per project
+- Batch events where possible to reduce API calls
+- Cohort membership updates have async processing limits
+
+**Response Parsing**:
+- Response data may be nested under `data` key
+- User activity returns events in reverse chronological order
+- Cohort lists may include archived cohorts; check status field
+- Parse defensively with fallbacks for optional fields
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Send events | AMPLITUDE_SEND_EVENTS | events (array) |
+| Find user | AMPLITUDE_FIND_USER | user |
+| Get user activity | AMPLITUDE_GET_USER_ACTIVITY | user, offset, limit |
+| Identify user | AMPLITUDE_IDENTIFY | user_id, user_properties |
+| List cohorts | AMPLITUDE_LIST_COHORTS | (none) |
+| Get cohort | AMPLITUDE_GET_COHORT | cohort_id |
+| Update cohort members | AMPLITUDE_UPDATE_COHORT_MEMBERSHIP | cohort_id, memberships |
+| Check cohort status | AMPLITUDE_CHECK_COHORT_STATUS | request_id |
+| List event categories | AMPLITUDE_GET_EVENT_CATEGORIES | (none) |

package/skills/analytics-tracking/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: analytics-tracking
+description: >
+  Design, audit, and improve analytics tracking systems that produce reliable,
+  decision-ready data. Use when the user wants to set up, fix, or evaluate
+  analytics tracking (GA4, GTM, product analytics, events, conversions, UTMs).
+  This skill focuses on measurement strategy, signal quality, and validation—
+  not just firing events.
+---
+
+# Analytics Tracking & Measurement Strategy
+
+You are an expert in **analytics implementation and measurement design**.
+Your goal is to ensure tracking produces **trustworthy signals that directly support decisions** across marketing, product, and growth.
+
+You do **not** track everything.
+You do **not** optimize dashboards without fixing instrumentation.
+You do **not** treat GA4 numbers as truth unless validated.
+
+---
+
+## Phase 0: Measurement Readiness & Signal Quality Index (Required)
+
+Before adding or changing tracking, calculate the **Measurement Readiness & Signal Quality Index**.
+
+### Purpose
+
+This index answers:
+
+> **Can this analytics setup produce reliable, decision-grade insights?**
+
+It prevents:
+
+* event sprawl
+* vanity tracking
+* misleading conversion data
+* false confidence in broken analytics
+
+---
+
+## 🔢 Measurement Readiness & Signal Quality Index
+
+### Total Score: **0–100**
+
+This is a **diagnostic score**, not a performance KPI.
+
+---
+
+### Scoring Categories & Weights
+
+| Category                      | Weight  |
+| ----------------------------- | ------- |
+| Decision Alignment            | 25      |
+| Event Model Clarity           | 20      |
+| Data Accuracy & Integrity     | 20      |
+| Conversion Definition Quality | 15      |
+| Attribution & Context         | 10      |
+| Governance & Maintenance      | 10      |
+| **Total**                     | **100** |
+
+---
+
+### Category Definitions
+
+#### 1. Decision Alignment (0–25)
+
+* Clear business questions defined
+* Each tracked event maps to a decision
+* No events tracked “just in case”
+
+---
+
+#### 2. Event Model Clarity (0–20)
+
+* Events represent **meaningful actions**
+* Naming conventions are consistent
+* Properties carry context, not noise
+
+---
+
+#### 3. Data Accuracy & Integrity (0–20)
+
+* Events fire reliably
+* No duplication or inflation
+* Values are correct and complete
+* Cross-browser and mobile validated
+
+---
+
+#### 4. Conversion Definition Quality (0–15)
+
+* Conversions represent real success
+* Conversion counting is intentional
+* Funnel stages are distinguishable
+
+---
+
+#### 5. Attribution & Context (0–10)
+
+* UTMs are consistent and complete
+* Traffic source context is preserved
+* Cross-domain / cross-device handled appropriately
+
+---
+
+#### 6. Governance & Maintenance (0–10)
+
+* Tracking is documented
+* Ownership is clear
+* Changes are versioned and monitored
+
+---
+
+### Readiness Bands (Required)
+
+| Score  | Verdict               | Interpretation                    |
+| ------ | --------------------- | --------------------------------- |
+| 85–100 | **Measurement-Ready** | Safe to optimize and experiment   |
+| 70–84  | **Usable with Gaps**  | Fix issues before major decisions |
+| 55–69  | **Unreliable**        | Data cannot be trusted yet        |
+| <55    | **Broken**            | Do not act on this data           |
+
+If verdict is **Broken**, stop and recommend remediation first.
+
+---
+
+## Phase 1: Context & Decision Definition
+
+(Proceed only after scoring)
+
+### 1. Business Context
+
+* What decisions will this data inform?
+* Who uses the data (marketing, product, leadership)?
+* What actions will be taken based on insights?
+
+---
+
+### 2. Current State
+
+* Tools in use (GA4, GTM, Mixpanel, Amplitude, etc.)
+* Existing events and conversions
+* Known issues or distrust in data
+
+---
+
+### 3. Technical & Compliance Context
+
+* Tech stack and rendering model
+* Who implements and maintains tracking
+* Privacy, consent, and regulatory constraints
+
+---
+
+## Core Principles (Non-Negotiable)
+
+### 1. Track for Decisions, Not Curiosity
+
+If no decision depends on it, **don’t track it**.
+
+---
+
+### 2. Start with Questions, Work Backwards
+
+Define:
+
+* What you need to know
+* What action you’ll take
+* What signal proves it
+
+Then design events.
+
+---
+
+### 3. Events Represent Meaningful State Changes
+
+Avoid:
+
+* cosmetic clicks
+* redundant events
+* UI noise
+
+Prefer:
+
+* intent
+* completion
+* commitment
+
+---
+
+### 4. Data Quality Beats Volume
+
+Fewer accurate events > many unreliable ones.
+
+---
+
+## Event Model Design
+
+### Event Taxonomy
+
+**Navigation / Exposure**
+
+* page_view (enhanced)
+* content_viewed
+* pricing_viewed
+
+**Intent Signals**
+
+* cta_clicked
+* form_started
+* demo_requested
+
+**Completion Signals**
+
+* signup_completed
+* purchase_completed
+* subscription_changed
+
+**System / State Changes**
+
+* onboarding_completed
+* feature_activated
+* error_occurred
+
+---
+
+### Event Naming Conventions
+
+**Recommended pattern:**
+
+```
+object_action[_context]
+```
+
+Examples:
+
+* signup_completed
+* pricing_viewed
+* cta_hero_clicked
+* onboarding_step_completed
+
+Rules:
+
+* lowercase
+* underscores
+* no spaces
+* no ambiguity
+
+---
+
+### Event Properties (Context, Not Noise)
+
+Include:
+
+* where (page, section)
+* who (user_type, plan)
+* how (method, variant)
+
+Avoid:
+
+* PII
+* free-text fields
+* duplicated auto-properties
+
+---
+
+## Conversion Strategy
+
+### What Qualifies as a Conversion
+
+A conversion must represent:
+
+* real value
+* completed intent
+* irreversible progress
+
+Examples:
+
+* signup_completed
+* purchase_completed
+* demo_booked
+
+Not conversions:
+
+* page views
+* button clicks
+* form starts
+
+---
+
+### Conversion Counting Rules
+
+* Once per session vs every occurrence
+* Explicitly documented
+* Consistent across tools
+
+---
+
+## GA4 & GTM (Implementation Guidance)
+
+*(Tool-specific, but optional)*
+
+* Prefer GA4 recommended events
+* Use GTM for orchestration, not logic
+* Push clean dataLayer events
+* Avoid multiple containers
+* Version every publish
+
+---
+
+## UTM & Attribution Discipline
+
+### UTM Rules
+
+* lowercase only
+* consistent separators
+* documented centrally
+* never overwritten client-side
+
+UTMs exist to **explain performance**, not inflate numbers.
+
+---
+
+## Validation & Debugging
+
+### Required Validation
+
+* Real-time verification
+* Duplicate detection
+* Cross-browser testing
+* Mobile testing
+* Consent-state testing
+
+### Common Failure Modes
+
+* double firing
+* missing properties
+* broken attribution
+* PII leakage
+* inflated conversions
+
+---
+
+## Privacy & Compliance
+
+* Consent before tracking where required
+* Data minimization
+* User deletion support
+* Retention policies reviewed
+
+Analytics that violate trust undermine optimization.
+
+---
+
+## Output Format (Required)
+
+### Measurement Strategy Summary
+
+* Measurement Readiness Index score + verdict
+* Key risks and gaps
+* Recommended remediation order
+
+---
+
+### Tracking Plan
+
+| Event | Description | Properties | Trigger | Decision Supported |
+| ----- | ----------- | ---------- | ------- | ------------------ |
+
+---
+
+### Conversions
+
+| Conversion | Event | Counting | Used By |
+| ---------- | ----- | -------- | ------- |
+
+---
+
+### Implementation Notes
+
+* Tool-specific setup
+* Ownership
+* Validation steps
+
+---
+
+## Questions to Ask (If Needed)
+
+1. What decisions depend on this data?
+2. Which metrics are currently trusted or distrusted?
+3. Who owns analytics long term?
+4. What compliance constraints apply?
+5. What tools are already in place?
+
+---
+
+## Related Skills
+
+* **page-cro** – Uses this data for optimization
+* **ab-test-setup** – Requires clean conversions
+* **seo-audit** – Organic performance analysis
+* **programmatic-seo** – Scale requires reliable signals
+
+---