borghei/social-media-analyzer
> Social media campaign analysis and performance tracking that calculates engagement rates, ROI, and cross-platform benchmarks. Use for analyzing social performance, calculating engagement rate, or measuring campaign ROI.
npx skills add https://github.com/borghei/Claude-Skills --skill social-media-analyzerCampaign performance analysis with engagement metrics, ROI calculations, and platform benchmarks.
Before analyzing, confirm these inputs. If any is unknown or vague, ASK — do not assume:
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Analyze social media campaign performance:
| 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) |
Before analysis, verify:
Engagement Rate = (Likes + Comments + Shares + Saves) / Reach × 100
| 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 |
| 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 |
Calculate return on ad spend:
| 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 |
| 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 % | 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 | 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% |
| 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% |
| 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.
python scripts/calculate_metrics.py assets/sample_input.json
Calculates engagement rate, CTR, reach rate for each post and campaign totals.
python scripts/analyze_performance.py assets/sample_input.json
Generates full performance analysis with ROI, benchmarks, and recommendations.
Output includes:
See assets/sample_input.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
}
]
}
See assets/expected_output.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%"
}
}
}
The sample campaign shows:
references/platform-benchmarks.md contains:
| When you ask for... | You get... |
|---------------------|------------|
| "Social media audit" | Performance analysis across platforms with benchmarks |
| "What's performing?" | Top content analysis with patterns and recommendations |
| "Competitor social analysis" | Competitive social media comparison with gaps |
| "Campaign ROI" | Full ROI calculation with engagement value estimates |
All output passes quality verification:
| Problem | Likely Cause | Solution |
|---------|-------------|----------|
| Engagement rate appears unrealistically high (>50%) | Reach value is too low relative to engagements, or reach/impressions data is swapped | Verify that reach represents unique users reached (not impressions). Engagement rate = (likes + comments + shares + saves) / reach. If using Instagram data from 2025+, note that Instagram shifted from "impressions" to "views" as primary metric -- ensure you are using the correct field |
| Benchmark comparison shows "no_benchmark_available" | Platform name in input JSON does not match expected values | Use exact lowercase platform names: instagram, facebook, twitter, linkedin, tiktok. The analyzer matches against these exact strings |
| ROI calculation shows negative despite good engagement | Engagement value estimates are too conservative for your industry | The default engagement value model uses $0.50/like, $2.00/comment, $5.00/share, $3.00/save, $1.50/click. Adjust these values in calculate_metrics.py for your specific vertical. B2B companies typically have higher per-engagement values than B2C |
| TikTok metrics show low engagement compared to benchmarks | Using reach-based calculation on a platform where view-based metrics are standard | TikTok's 2026 benchmark engagement rate of 2.50-3.70% is calculated against views, not reach. Ensure your TikTok data uses video views in the reach field for accurate comparison. TikTok engagement rates rose 49% YoY in 2025 |
| LinkedIn engagement appears lower than expected | Comparing against outdated benchmarks | LinkedIn's 2026 median engagement rate is approximately 3.85-6.1%, significantly higher than other platforms. Carousel/document posts earn the highest engagement (up to 21.77% median). If your rate is below 2%, focus on conversation-starting content rather than corporate announcements |
| Instagram metrics declining despite consistent content quality | Algorithm and metric definition changes in 2025-2026 | Instagram shifted to "Views" as its primary metric across all formats (Reels, Stories, posts), replacing "Impressions" and "Plays." Carousel posts now earn the most engagement. Meta plans to replace reach with "Viewers" metric in Graph API by June 2026. Adapt your data collection accordingly |
| Campaign analysis has too few posts for reliable insights | Small sample size produces unreliable averages | Minimum 10 posts recommended for meaningful analysis. The analyze_performance.py script flags campaigns with fewer than 10 posts. For statistical reliability, aim for 30+ posts per analysis period |
In Scope:
Out of Scope:
Platform API Changes (2025-2026):
| Integration | Purpose | How to Connect |
|-------------|---------|----------------|
| Meta Business Suite | Export Instagram and Facebook campaign data | Export post-level metrics (likes, comments, shares, reach, impressions, clicks) as JSON for calculate_metrics.py and analyze_performance.py. Note: "Views" is replacing "Impressions" in 2026 |
| LinkedIn Campaign Manager | Export LinkedIn ad and organic performance data | Export engagement metrics per post. LinkedIn's native analytics now includes "Viewer" demographics and AI search visibility data |
| TikTok Business Center | Export TikTok campaign performance data | Export video-level metrics. Use video views as the reach equivalent for engagement rate calculation |
| Google Analytics 4 (GA4) | Track social traffic and conversions on your website | Connect social campaign UTM parameters to GA4 to measure downstream conversions. Use campaign-analytics skill for full attribution |
| campaign-analytics skill | Cross-channel ROI comparison | Feed social media ROI data into campaign_roi_calculator.py alongside other channels for unified portfolio analysis |
| content-creator skill | Content optimization based on performance data | Use top-performing post analysis to inform content strategy. Apply brand_voice_analyzer.py to ensure social content matches brand voice |
| marketing-demand-acquisition skill | Social as demand gen channel | Integrate social performance data into demand gen channel mix evaluation. Use CAC data from social alongside other acquisition channels |
Type: Python library (imported, not CLI)
Classes:
SocialMediaMetricsCalculator(campaign_data: Dict)Constructor Input: {"platform": "instagram", "total_spend": 500, "posts": [{"post_id": "str", "content_type": "str", "likes": int, "comments": int, "shares": int, "saves": int, "reach": int, "impressions": int, "clicks": int}]}
Key Methods:
| Method | Parameters | Returns |
|--------|-----------|---------|
| calculate_engagement_rate() | post: Dict (likes, comments, shares, saves, reach) | Engagement rate as percentage (float). Formula: (likes + comments + shares + saves) / reach * 100 |
| calculate_ctr() | clicks: int, impressions: int | CTR as percentage (float) |
| calculate_campaign_metrics() | None (uses constructor data) | Dict with platform, total_posts, total_engagements, total_reach, total_impressions, total_clicks, avg_engagement_rate, ctr |
| calculate_roi_metrics() | None (uses constructor data) | Dict with total_spend, cost_per_engagement, cost_per_click, estimated_value (at $2.50/engagement default), roi_percentage |
| identify_top_posts() | metric: str = 'engagement_rate', limit: int = 5 | Sorted list of top posts by specified metric. Supported metrics: engagement_rate, likes, comments, shares, clicks |
| analyze_all() | None | Combined dict of campaign_metrics, roi_metrics, and top_posts |
Type: Python library (imported, not CLI)
Classes:
PerformanceAnalyzer(campaign_metrics: Dict, roi_metrics: Dict)Built-in Benchmarks: Engagement rate and CTR benchmarks for facebook, instagram, twitter, linkedin, tiktok.
Key Methods:
| Method | Parameters | Returns |
|--------|-----------|---------|
| benchmark_performance() | None | Dict with engagement_status, engagement_benchmark, engagement_actual, ctr_status, ctr_benchmark, ctr_actual. Status values: excellent (>=1.5x benchmark), good (>=benchmark), below_average |
| generate_recommendations() | None | List of actionable recommendation strings based on engagement rate, CTR, CPC, ROI, and post volume thresholds |
| generate_insights() | None | Dict with overall_health (excellent/good/needs_improvement), benchmark_comparison, recommendations, key_strengths, areas_for_improvement |
Take borghei/social-media-analyzer from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.