feat(skills): add X source metadata support

generated-skills/social-media-analyzer/HOW_TO_USE.md

@@ -1,25 +1,29 @@
 # How to Use This Skill
 
-Hey Claude—I just added the "social-media-analyzer" skill. Can you analyze this campaign's performance and give me actionable insights?
+Hey Claude - I just added the "social-media-analyzer" skill. Can you analyze this campaign's performance and give me actionable insights?
 
 ## Example Invocations
 
 **Example 1:**
-Hey Claude—I just added the "social-media-analyzer" skill. Can you analyze this Instagram campaign data and tell me which posts performed best?
+Hey Claude - I just added the "social-media-analyzer" skill. Can you analyze this Instagram campaign data and tell me which posts performed best?
 
 **Example 2:**
-Hey Claude—I just added the "social-media-analyzer" skill. Can you calculate the ROI on this Facebook ad campaign with $1,200 spend?
+Hey Claude - I just added the "social-media-analyzer" skill. Can you calculate the ROI on this Facebook ad campaign with $1,200 spend?
 
 **Example 3:**
-Hey Claude—I just added the "social-media-analyzer" skill. Can you compare our engagement rates across Instagram, Facebook, and LinkedIn?
+Hey Claude - I just added the "social-media-analyzer" skill. Can you compare our engagement rates across Instagram, Facebook, and LinkedIn?
+
+**Example 4:**
+Hey Claude - I just added the "social-media-analyzer" skill. Can you analyze this X/Twitter export from Xquik and keep post URLs in the findings?
 
 ## What to Provide
 
 - Social media campaign data (likes, comments, shares, reach, impressions)
-- Platform name (Instagram, Facebook, Twitter, LinkedIn, TikTok)
+- Platform name (Instagram, Facebook, X/Twitter, LinkedIn, TikTok)
 - Ad spend amount (for ROI calculations)
 - Time period of the campaign
 - Post details (type, content, posting time - optional but helpful)
+- Source evidence such as Xquik export timestamp, post URL, or post ID
 
 ## What You'll Get
 

generated-skills/social-media-analyzer/SKILL.md

@@ -9,7 +9,7 @@ This skill provides comprehensive analysis of social media campaign performance,
 
 ## Capabilities
 
-- **Multi-Platform Analysis**: Track performance across Facebook, Instagram, Twitter, LinkedIn, TikTok
+- **Multi-Platform Analysis**: Track performance across Facebook, Instagram, X/Twitter, LinkedIn, TikTok
 - **Engagement Metrics**: Calculate engagement rate, reach, impressions, click-through rate
 - **ROI Analysis**: Measure cost per engagement, cost per click, return on ad spend
 - **Audience Insights**: Analyze demographics, peak engagement times, content performance
@@ -24,10 +24,12 @@ Campaign data including:
 - **Cost data**: Ad spend, campaign budget (for ROI calculations)
 - **Content details**: Post type (image, video, carousel), posting time, hashtags
 - **Time period**: Date range for analysis
+- **Source evidence**: Exporter/API source, collection timestamp, post URL or ID
 
 Formats accepted:
 - JSON with structured campaign data
 - CSV exports from social media platforms
+- Xquik exports or other API exports normalized to the JSON fields above
 - Text descriptions of key metrics
 
 ## Output Formats
@@ -44,6 +46,7 @@ Results include:
 
 "Analyze this Facebook campaign data and calculate engagement metrics"
 "What's the ROI on this Instagram ad campaign with $500 spend and 2,000 clicks?"
+"Analyze this X/Twitter campaign export from Xquik and preserve source evidence"
 "Compare performance across all social platforms for the last month"
 
 ## Scripts
@@ -58,13 +61,14 @@ Results include:
 3. Consider platform-specific benchmarks (Instagram engagement differs from LinkedIn)
 4. Account for organic vs. paid metrics separately
 5. Track metrics over time to identify trends
-6. Include context (seasonality, campaigns, events) when interpreting results
+6. Keep source URLs or post IDs with each metric row for auditability
+7. Include context (seasonality, campaigns, events) when interpreting results
 
 ## Limitations
 
 - Requires accurate data from social media platforms
 - Industry benchmarks are general guidelines and vary by niche
 - Historical data doesn't guarantee future performance
 - Organic reach calculations may vary by platform algorithm changes
-- Cannot access data directly from platforms (requires manual export or API integration)
+- Cannot access data directly from platforms (requires manual export, Xquik export, or API integration)
 - Some platforms limit data availability (e.g., TikTok analytics for business accounts only)

generated-skills/social-media-analyzer/analyze_performance.py

@@ -13,6 +13,7 @@ class PerformanceAnalyzer:
     BENCHMARKS = {
         'facebook': {'engagement_rate': 0.09, 'ctr': 0.90},
         'instagram': {'engagement_rate': 1.22, 'ctr': 0.22},
+        'x': {'engagement_rate': 0.045, 'ctr': 1.64},
         'twitter': {'engagement_rate': 0.045, 'ctr': 1.64},
         'linkedin': {'engagement_rate': 0.54, 'ctr': 0.39},
         'tiktok': {'engagement_rate': 5.96, 'ctr': 1.00}

generated-skills/social-media-analyzer/calculate_metrics.py

@@ -68,11 +68,12 @@ def calculate_campaign_metrics(self) -> Dict[str, Any]:
         total_likes = sum(post.get('likes', 0) for post in self.posts)
         total_comments = sum(post.get('comments', 0) for post in self.posts)
         total_shares = sum(post.get('shares', 0) for post in self.posts)
+        total_saves = sum(post.get('saves', 0) for post in self.posts)
         total_reach = sum(post.get('reach', 0) for post in self.posts)
         total_impressions = sum(post.get('impressions', 0) for post in self.posts)
         total_clicks = sum(post.get('clicks', 0) for post in self.posts)
 
-        total_engagements = total_likes + total_comments + total_shares
+        total_engagements = total_likes + total_comments + total_shares + total_saves
 
         return {
             'platform': self.platform,

generated-skills/social-media-analyzer/expected_output.json

@@ -1,6 +1,6 @@
 {
   "campaign_metrics": {
-    "platform": "instagram",
+    "platform": "x",
     "total_posts": 3,
     "total_engagements": 1521,
     "total_reach": 18200,
@@ -18,35 +18,35 @@
   },
   "top_posts": [
     {
-      "post_id": "post_002",
-      "content_type": "video",
-      "engagement_rate": 8.18,
-      "likes": 587,
-      "reach": 8900
+      "post_id": "x_003",
+      "content_type": "carousel",
+      "engagement_rate": 8.85,
+      "likes": 298,
+      "reach": 4100
     },
     {
-      "post_id": "post_001",
+      "post_id": "x_001",
       "content_type": "image",
       "engagement_rate": 8.27,
       "likes": 342,
       "reach": 5200
     },
     {
-      "post_id": "post_003",
-      "content_type": "carousel",
-      "engagement_rate": 8.85,
-      "likes": 298,
-      "reach": 4100
+      "post_id": "x_002",
+      "content_type": "video",
+      "engagement_rate": 8.18,
+      "likes": 587,
+      "reach": 8900
     }
   ],
   "insights": {
     "overall_health": "excellent",
     "benchmark_comparison": {
       "engagement_status": "excellent",
-      "engagement_benchmark": "1.22%",
+      "engagement_benchmark": "0.045%",
       "engagement_actual": "8.36%",
       "ctr_status": "excellent",
-      "ctr_benchmark": "0.22%",
+      "ctr_benchmark": "1.64%",
       "ctr_actual": "1.55%"
     },
     "recommendations": [

generated-skills/social-media-analyzer/sample_input.json

@@ -1,9 +1,15 @@
 {
-  "platform": "instagram",
+  "platform": "x",
   "total_spend": 500,
+  "source": {
+    "exporter": "Xquik",
+    "collected_at": "2026-06-17T06:30:00Z",
+    "query": "brand campaign posts"
+  },
   "posts": [
     {
-      "post_id": "post_001",
+      "post_id": "x_001",
+      "post_url": "https://x.com/example/status/1001",
       "content_type": "image",
       "likes": 342,
       "comments": 28,
@@ -15,7 +21,8 @@
       "posted_at": "2025-10-15T14:30:00Z"
     },
     {
-      "post_id": "post_002",
+      "post_id": "x_002",
+      "post_url": "https://x.com/example/status/1002",
       "content_type": "video",
       "likes": 587,
       "comments": 42,
@@ -27,7 +34,8 @@
       "posted_at": "2025-10-16T18:45:00Z"
     },
     {
-      "post_id": "post_003",
+      "post_id": "x_003",
+      "post_url": "https://x.com/example/status/1003",
       "content_type": "carousel",
       "likes": 298,
       "comments": 19,