fix(skill): restructure social-media-analyzer with proper organization (#77) (#147)

- Reorganize file structure:
  - Move Python scripts to scripts/
  - Move example files to assets/
  - Create references/ with platform-benchmarks.md
- Create platform-benchmarks.md with engagement, CTR, CPC benchmarks
- Rewrite SKILL.md with:
  - 10 trigger phrases for discoverability
  - Table of Contents
  - Numbered analysis workflow with validation
  - Data validation checklist
  - ROI calculation workflow
  - Example input/output with interpretation
- Remove verbose marketing copy
- Reference example files properly

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

marketing-skill/social-media-analyzer/SKILL.md

@@ -1,70 +1,280 @@
 ---
 name: social-media-analyzer
-description: Analyzes social media campaign performance across platforms with engagement metrics, ROI calculations, and audience insights for data-driven marketing decisions
+description: Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards.
+triggers:
+  - analyze social media
+  - calculate engagement rate
+  - social media ROI
+  - campaign performance
+  - compare platforms
+  - benchmark engagement
+  - Instagram analytics
+  - Facebook metrics
+  - TikTok performance
+  - LinkedIn engagement
 ---
 
-# Social Media Campaign Analyzer
+# Social Media Analyzer
 
-This skill provides comprehensive analysis of social media campaign performance, helping marketing agencies deliver actionable insights to clients.
+Campaign performance analysis with engagement metrics, ROI calculations, and platform benchmarks.
 
-## Capabilities
+---
 
-- **Multi-Platform Analysis**: Track performance across Facebook, Instagram, 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
-- **Trend Detection**: Identify high-performing content types and posting patterns
-- **Competitive Benchmarking**: Compare performance against industry standards
+## Table of Contents
 
-## Input Requirements
+- [Analysis Workflow](#analysis-workflow)
+- [Engagement Metrics](#engagement-metrics)
+- [ROI Calculation](#roi-calculation)
+- [Platform Benchmarks](#platform-benchmarks)
+- [Tools](#tools)
+- [Examples](#examples)
 
-Campaign data including:
-- **Platform metrics**: Likes, comments, shares, saves, clicks
-- **Reach data**: Impressions, unique reach, follower growth
-- **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
+---
 
-Formats accepted:
-- JSON with structured campaign data
-- CSV exports from social media platforms
-- Text descriptions of key metrics
+## Analysis Workflow
 
-## Output Formats
+Analyze social media campaign performance:
 
-Results include:
-- **Performance dashboard**: Key metrics with trends
-- **Engagement analysis**: Best and worst performing posts
-- **ROI breakdown**: Cost efficiency metrics
-- **Audience insights**: Demographics and behavior patterns
-- **Recommendations**: Data-driven suggestions for optimization
-- **Visual reports**: Charts and graphs (Excel/PDF format)
+1. Validate input data completeness (reach > 0, dates valid)
+2. Calculate engagement metrics per post
+3. Aggregate campaign-level metrics
+4. Calculate ROI if ad spend provided
+5. Compare against platform benchmarks
+6. Identify top and bottom performers
+7. Generate recommendations
+8. **Validation:** Engagement rate < 100%, ROI matches spend data
 
-## How to Use
+### Input Requirements
 
-"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?"
-"Compare performance across all social platforms for the last month"
+| Field | Required | Description |
+|-------|----------|-------------|
+| platform | Yes | instagram, facebook, twitter, linkedin, tiktok |
+| posts[] | Yes | Array of post data |
+| posts[].likes | Yes | Like/reaction count |
+| posts[].comments | Yes | Comment count |
+| posts[].reach | Yes | Unique users reached |
+| posts[].impressions | No | Total views |
+| posts[].shares | No | Share/retweet count |
+| posts[].saves | No | Save/bookmark count |
+| posts[].clicks | No | Link clicks |
+| total_spend | No | Ad spend (for ROI) |
 
-## Scripts
+### Data Validation Checks
 
-- `calculate_metrics.py`: Core calculation engine for all social media metrics
-- `analyze_performance.py`: Performance analysis and recommendation generation
+Before analysis, verify:
 
-## Best Practices
+- [ ] Reach > 0 for all posts (avoid division by zero)
+- [ ] Engagement counts are non-negative
+- [ ] Date range is valid (start < end)
+- [ ] Platform is recognized
+- [ ] Spend > 0 if ROI requested
 
-1. Ensure data completeness before analysis (missing metrics affect accuracy)
-2. Compare metrics within same time periods for fair comparisons
-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
+---
 
-## Limitations
+## Engagement Metrics
 
-- 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)
-- Some platforms limit data availability (e.g., TikTok analytics for business accounts only)
+### Engagement Rate Calculation
+
+```
+Engagement Rate = (Likes + Comments + Shares + Saves) / Reach × 100
+```
+
+### Metric Definitions
+
+| Metric | Formula | Interpretation |
+|--------|---------|----------------|
+| Engagement Rate | Engagements / Reach × 100 | Audience interaction level |
+| CTR | Clicks / Impressions × 100 | Content click appeal |
+| Reach Rate | Reach / Followers × 100 | Content distribution |
+| Virality Rate | Shares / Impressions × 100 | Share-worthiness |
+| Save Rate | Saves / Reach × 100 | Content value |
+
+### Performance Categories
+
+| Rating | Engagement Rate | Action |
+|--------|-----------------|--------|
+| Excellent | > 6% | Scale and replicate |
+| Good | 3-6% | Optimize and expand |
+| Average | 1-3% | Test improvements |
+| Poor | < 1% | Analyze and pivot |
+
+---
+
+## ROI Calculation
+
+Calculate return on ad spend:
+
+1. Sum total engagements across posts
+2. Calculate cost per engagement (CPE)
+3. Calculate cost per click (CPC) if clicks available
+4. Estimate engagement value using benchmark rates
+5. Calculate ROI percentage
+6. **Validation:** ROI = (Value - Spend) / Spend × 100
+
+### ROI Formulas
+
+| Metric | Formula |
+|--------|---------|
+| Cost Per Engagement (CPE) | Total Spend / Total Engagements |
+| Cost Per Click (CPC) | Total Spend / Total Clicks |
+| Cost Per Thousand (CPM) | (Spend / Impressions) × 1000 |
+| Return on Ad Spend (ROAS) | Revenue / Ad Spend |
+
+### Engagement Value Estimates
+
+| Action | Value | Rationale |
+|--------|-------|-----------|
+| Like | $0.50 | Brand awareness |
+| Comment | $2.00 | Active engagement |
+| Share | $5.00 | Amplification |
+| Save | $3.00 | Intent signal |
+| Click | $1.50 | Traffic value |
+
+### ROI Interpretation
+
+| ROI % | Rating | Recommendation |
+|-------|--------|----------------|
+| > 500% | Excellent | Scale budget significantly |
+| 200-500% | Good | Increase budget moderately |
+| 100-200% | Acceptable | Optimize before scaling |
+| 0-100% | Break-even | Review targeting and creative |
+| < 0% | Negative | Pause and restructure |
+
+---
+
+## Platform Benchmarks
+
+### Engagement Rate by Platform
+
+| Platform | Average | Good | Excellent |
+|----------|---------|------|-----------|
+| Instagram | 1.22% | 3-6% | >6% |
+| Facebook | 0.07% | 0.5-1% | >1% |
+| Twitter/X | 0.05% | 0.1-0.5% | >0.5% |
+| LinkedIn | 2.0% | 3-5% | >5% |
+| TikTok | 5.96% | 8-15% | >15% |
+
+### CTR by Platform
+
+| Platform | Average | Good | Excellent |
+|----------|---------|------|-----------|
+| Instagram | 0.22% | 0.5-1% | >1% |
+| Facebook | 0.90% | 1.5-2.5% | >2.5% |
+| LinkedIn | 0.44% | 1-2% | >2% |
+| TikTok | 0.30% | 0.5-1% | >1% |
+
+### CPC by Platform
+
+| Platform | Average | Good |
+|----------|---------|------|
+| Facebook | $0.97 | <$0.50 |
+| Instagram | $1.20 | <$0.70 |
+| LinkedIn | $5.26 | <$3.00 |
+| TikTok | $1.00 | <$0.50 |
+
+See `references/platform-benchmarks.md` for complete benchmark data.
+
+---
+
+## Tools
+
+### Calculate Metrics
+
+```bash
+python scripts/calculate_metrics.py assets/sample_input.json
+```
+
+Calculates engagement rate, CTR, reach rate for each post and campaign totals.
+
+### Analyze Performance
+
+```bash
+python scripts/analyze_performance.py assets/sample_input.json
+```
+
+Generates full performance analysis with ROI, benchmarks, and recommendations.
+
+**Output includes:**
+- Campaign-level metrics
+- Post-by-post breakdown
+- Benchmark comparisons
+- Top performers ranked
+- Actionable recommendations
+
+---
+
+## Examples
+
+### Sample Input
+
+See `assets/sample_input.json`:
+
+```json
+{
+  "platform": "instagram",
+  "total_spend": 500,
+  "posts": [
+    {
+      "post_id": "post_001",
+      "content_type": "image",
+      "likes": 342,
+      "comments": 28,
+      "shares": 15,
+      "saves": 45,
+      "reach": 5200,
+      "impressions": 8500,
+      "clicks": 120
+    }
+  ]
+}
+```
+
+### Sample Output
+
+See `assets/expected_output.json`:
+
+```json
+{
+  "campaign_metrics": {
+    "total_engagements": 1521,
+    "avg_engagement_rate": 8.36,
+    "ctr": 1.55
+  },
+  "roi_metrics": {
+    "total_spend": 500.0,
+    "cost_per_engagement": 0.33,
+    "roi_percentage": 660.5
+  },
+  "insights": {
+    "overall_health": "excellent",
+    "benchmark_comparison": {
+      "engagement_status": "excellent",
+      "engagement_benchmark": "1.22%",
+      "engagement_actual": "8.36%"
+    }
+  }
+}
+```
+
+### Interpretation
+
+The sample campaign shows:
+- **Engagement rate 8.36%** vs 1.22% benchmark = Excellent (6.8x above average)
+- **CTR 1.55%** vs 0.22% benchmark = Excellent (7x above average)
+- **ROI 660%** = Outstanding return on $500 spend
+- **Recommendation:** Scale budget, replicate successful elements
+
+---
+
+## Reference Documentation
+
+### Platform Benchmarks
+
+`references/platform-benchmarks.md` contains:
+
+- Engagement rate benchmarks by platform and industry
+- CTR benchmarks for organic and paid content
+- Cost benchmarks (CPC, CPM, CPE)
+- Content type performance by platform
+- Optimal posting times and frequency
+- ROI calculation formulas

marketing-skill/social-media-analyzer/references/platform-benchmarks.md

@@ -0,0 +1,226 @@
+# Social Media Platform Benchmarks
+
+Industry benchmarks for engagement rates, CTR, and ROI by platform.
+
+---
+
+## Table of Contents
+
+- [Engagement Rate Benchmarks](#engagement-rate-benchmarks)
+- [Click-Through Rate Benchmarks](#click-through-rate-benchmarks)
+- [Cost Benchmarks](#cost-benchmarks)
+- [Content Type Performance](#content-type-performance)
+- [Posting Time Optimization](#posting-time-optimization)
+
+---
+
+## Engagement Rate Benchmarks
+
+### By Platform (2024-2025)
+
+| Platform | Average ER | Good ER | Excellent ER |
+|----------|------------|---------|--------------|
+| Instagram | 1.22% | 3-6% | >6% |
+| Facebook | 0.07% | 0.5-1% | >1% |
+| Twitter/X | 0.05% | 0.1-0.5% | >0.5% |
+| LinkedIn | 2.0% | 3-5% | >5% |
+| TikTok | 5.96% | 8-15% | >15% |
+
+### Engagement Rate Formula
+
+```
+Engagement Rate = (Likes + Comments + Shares + Saves) / Reach × 100
+```
+
+Alternative (by followers):
+```
+Engagement Rate = (Likes + Comments + Shares) / Followers × 100
+```
+
+### By Industry
+
+| Industry | Instagram | Facebook | LinkedIn |
+|----------|-----------|----------|----------|
+| Retail | 1.0% | 0.08% | 1.8% |
+| Technology | 0.9% | 0.06% | 2.5% |
+| Healthcare | 1.5% | 0.12% | 2.2% |
+| Finance | 0.8% | 0.05% | 2.8% |
+| Food & Beverage | 1.8% | 0.15% | 1.5% |
+| Travel | 1.4% | 0.10% | 1.9% |
+| B2B Services | 0.7% | 0.04% | 3.2% |
+
+---
+
+## Click-Through Rate Benchmarks
+
+### Organic CTR by Platform
+
+| Platform | Average CTR | Good CTR | Excellent CTR |
+|----------|-------------|----------|---------------|
+| Instagram | 0.22% | 0.5-1% | >1% |
+| Facebook | 0.90% | 1.5-2.5% | >2.5% |
+| Twitter/X | 0.86% | 1.5-2% | >2% |
+| LinkedIn | 0.44% | 1-2% | >2% |
+| TikTok | 0.30% | 0.5-1% | >1% |
+
+### Paid Ad CTR by Platform
+
+| Platform | Average CTR | Good CTR | Excellent CTR |
+|----------|-------------|----------|---------------|
+| Facebook Ads | 0.90% | 1.5-2% | >2% |
+| Instagram Ads | 0.58% | 1-1.5% | >1.5% |
+| LinkedIn Ads | 0.44% | 0.8-1.2% | >1.2% |
+| Twitter Ads | 1.55% | 2-3% | >3% |
+| TikTok Ads | 0.84% | 1.5-2% | >2% |
+
+---
+
+## Cost Benchmarks
+
+### Cost Per Click (CPC)
+
+| Platform | Average CPC | Low CPC | Industry Range |
+|----------|-------------|---------|----------------|
+| Facebook | $0.97 | <$0.50 | $0.50-$2.00 |
+| Instagram | $1.20 | <$0.70 | $0.70-$3.00 |
+| LinkedIn | $5.26 | <$3.00 | $3.00-$8.00 |
+| Twitter | $0.38 | <$0.25 | $0.25-$1.00 |
+| TikTok | $1.00 | <$0.50 | $0.50-$2.00 |
+
+### Cost Per Thousand Impressions (CPM)
+
+| Platform | Average CPM | Low CPM | Industry Range |
+|----------|-------------|---------|----------------|
+| Facebook | $7.19 | <$5.00 | $5.00-$15.00 |
+| Instagram | $7.91 | <$5.00 | $5.00-$15.00 |
+| LinkedIn | $33.80 | <$20.00 | $20.00-$50.00 |
+| Twitter | $6.46 | <$4.00 | $4.00-$12.00 |
+| TikTok | $10.00 | <$6.00 | $6.00-$15.00 |
+
+### Cost Per Engagement (CPE)
+
+| Platform | Average CPE | Good CPE |
+|----------|-------------|----------|
+| Facebook | $0.12 | <$0.08 |
+| Instagram | $0.15 | <$0.10 |
+| LinkedIn | $0.80 | <$0.50 |
+| Twitter | $0.08 | <$0.05 |
+| TikTok | $0.10 | <$0.06 |
+
+---
+
+## Content Type Performance
+
+### Instagram
+
+| Content Type | Avg Engagement | Best Use Case |
+|--------------|----------------|---------------|
+| Reels | 1.95% | Discovery, viral potential |
+| Carousels | 1.92% | Education, storytelling |
+| Single Image | 1.18% | Product showcase |
+| Stories | 0.5% swipe-up | Time-sensitive, behind-scenes |
+
+### Facebook
+
+| Content Type | Avg Engagement | Best Use Case |
+|--------------|----------------|---------------|
+| Video | 0.26% | Brand awareness |
+| Photo | 0.12% | Quick updates |
+| Link | 0.05% | Traffic driving |
+| Status | 0.04% | Community engagement |
+
+### LinkedIn
+
+| Content Type | Avg Engagement | Best Use Case |
+|--------------|----------------|---------------|
+| Document/PDF | 3.5% | Thought leadership |
+| Native Video | 2.8% | Personal brand |
+| Image | 2.0% | Announcements |
+| Text Only | 1.8% | Professional insights |
+| Link | 1.2% | Content sharing |
+
+### TikTok
+
+| Content Type | Avg Engagement | Best Use Case |
+|--------------|----------------|---------------|
+| Trending Sound | 8-12% | Discovery, virality |
+| Tutorial | 6-10% | Education, value |
+| Behind-Scenes | 5-8% | Authenticity |
+| Product Demo | 4-7% | Conversion |
+
+---
+
+## Posting Time Optimization
+
+### Best Posting Times by Platform
+
+**Instagram:**
+- Best days: Tuesday, Wednesday, Thursday
+- Best times: 11 AM, 2 PM, 7 PM (local time)
+- Worst: Sunday mornings
+
+**Facebook:**
+- Best days: Wednesday, Thursday, Friday
+- Best times: 9 AM, 1 PM, 4 PM
+- Worst: Weekends before noon
+
+**LinkedIn:**
+- Best days: Tuesday, Wednesday, Thursday
+- Best times: 7-8 AM, 12 PM, 5-6 PM
+- Worst: Weekends
+
+**Twitter/X:**
+- Best days: Wednesday, Thursday
+- Best times: 8 AM, 12 PM, 5 PM
+- Worst: Late night (after 10 PM)
+
+**TikTok:**
+- Best days: Tuesday, Thursday, Friday
+- Best times: 7 PM, 8 PM, 9 PM
+- Worst: Early mornings
+
+### Posting Frequency
+
+| Platform | Minimum | Optimal | Maximum |
+|----------|---------|---------|---------|
+| Instagram | 3/week | 1-2/day | 3/day |
+| Facebook | 3/week | 1/day | 2/day |
+| LinkedIn | 2/week | 1/day | 2/day |
+| Twitter | 1/day | 3-5/day | 10/day |
+| TikTok | 3/week | 1-3/day | 5/day |
+
+---
+
+## ROI Calculation
+
+### Standard ROI Formula
+
+```
+ROI = ((Revenue - Cost) / Cost) × 100
+```
+
+### Social Media ROI Components
+
+| Metric | Formula |
+|--------|---------|
+| Cost Per Click (CPC) | Total Spend / Total Clicks |
+| Cost Per Engagement (CPE) | Total Spend / Total Engagements |
+| Cost Per Thousand (CPM) | (Total Spend / Impressions) × 1000 |
+| Return on Ad Spend (ROAS) | Revenue / Ad Spend |
+| Customer Acquisition Cost (CAC) | Total Spend / New Customers |
+
+### Engagement Value Estimation
+
+| Action | Estimated Value |
+|--------|-----------------|
+| Like | $0.50 |
+| Comment | $2.00 |
+| Share | $5.00 |
+| Save | $3.00 |
+| Click | $1.50 |
+| Follow | $10.00 |
+
+**Total Engagement Value:**
+```
+Value = (Likes × $0.50) + (Comments × $2.00) + (Shares × $5.00) + (Saves × $3.00) + (Clicks × $1.50)
+```