facebook-ads-analyzer

name	facebook-ads-analyzer
description	Analyze Facebook Ads Manager CSV exports to identify top/bottom performing ads, calculate comprehensive metrics (CTR, CPC, CPM, conversion rate), generate ad ratings, provide optimization recommendations and create advertising strategy suggestions. Use when user mentions Facebook ads, ad performance analysis, Facebook Ads Manager CSV data, advertising optimization, ad metrics analysis, or asks for insights about Facebook advertising campaigns. Requires pandas and numpy packages.
allowed-tools	Read, Write, Bash, Glob, Grep

Facebook Ads Analyzer

Automatically analyze Facebook advertising data from CSV exports and generate actionable insights.

Quick Start

1. Provide a Facebook Ads Manager CSV export file
2. Specify your advertising goal (CRITICAL - affects analysis and recommendations):
   • Interaction (互动): Focus on message conversations and engagement
   • Conversion (转化): Focus on leads, purchases, and conversions
   • Traffic (流量): Focus on clicks and impressions
3. The Skill will automatically:
   • Load and clean the data
   • Calculate goal-specific metrics and weights
   • Rate each ad (Excellent/Medium/Poor)
   • Identify Top 10 and Bottom 10 ads
   • Generate goal-specific optimization recommendations
   • Create strategy suggestions

Minimal example:

Please analyze this Facebook ads CSV file: facebook_ads_export.csv
My advertising goal is to increase message conversations (互动目标)

What This Skill Does

Data Processing

• Loads Facebook Ads Manager CSV exports (handles UTF-8 BOM encoding)
• Cleans and validates data (removes invalid rows, handles missing values)
• Aggregates data by ad dimension

Metrics Calculation

• CTR (Click-Through Rate): 点击率
• CPC (Cost Per Click): 单次点击费用
• CPM (Cost Per Mille): 千次展示费用
• Engagement Rate: 互动率
• Conversion Rate: 转化率
• Frequency: 平均频次

Composite Scoring

Calculates a comprehensive score using weighted metrics:

Score = CTR × 30% + CPC × 25% + Conversion Rate × 25% + Engagement Rate × 20%

Ad Classification

• Excellent (优秀): Top 20% performers - Scale budget, expand audience
• Medium (中等): Middle 60% - A/B testing, refine targeting
• Poor (差): Bottom 20% - Pause or rebuild

Output Generation

• CSV file with detailed analysis results
• Markdown report with insights and recommendations
• Strategy proposals (Conservative/Balanced/Aggressive)

Input Requirements

CSV File Format

The Skill expects Facebook Ads Manager CSV exports with these columns:

Required Columns:

• 账户名称 (Account Name)
• 广告系列名称 (Campaign Name)
• 广告组名称 (Ad Set Name)
• 广告名称 (Ad Name)
• 单日 (Date)
• 国家/地区 (Country/Region)
• 展示次数 (Impressions)
• 已花费金额 (USD) (Amount Spent)

Optional Columns (for enhanced analysis):

• 点击量（全部） (Clicks)
• 点击率（全部） (CTR)
• 单次点击费用（全部） (CPC)
• 公共主页互动 (Page Engagement)
• 潜在客户人数 (Leads)
• 消息对话发起次数 (Conversations)
• 频次 (Frequency)

Usage Scenarios

Use this Skill when:

1. Analyzing Ad Performance

   • "Which ads are performing best?"
   • "Show me the worst performing ads"
   • "Analyze my Facebook ad campaigns"

2. Optimization Requests

   • "How can I improve my Facebook ads?"
   • "Give me optimization recommendations"
   • "What should I do with underperforming ads?"

3. Strategy Planning

   • "Create an advertising strategy"
   • "How should I allocate my ad budget?"
   • "Generate a media plan based on this data"

4. Data Analysis

   • "Analyze this CSV file" (when it's Facebook ads data)
   • "Calculate metrics for my ads"
   • "Compare ad performance across regions"

Workflow

Step 1: Data Loading

The Skill uses Python scripts to:

1. Read the CSV file (UTF-8-sig encoding)
2. Validate required columns
3. Display data summary

Step 2: Goal Selection (CRITICAL)

Before analysis, the Skill MUST ask the user:

What is your advertising goal for this campaign?
1. Interaction (互动) - Focus on message conversations and engagement
2. Conversion (转化) - Focus on leads, purchases, and conversions
3. Traffic (流量) - Focus on clicks and impressions

The goal selection affects:

• Metric weights and scoring
• Rating thresholds
• Problem identification
• Optimization recommendations

Step 3: Analysis

Run the analyzer with the specified goal:

cd .claude/skills/facebook-ads-analyzer/scripts
python analyzer.py ../data_input.csv ../output_results.csv --goal interaction
# or --goal conversion
# or --goal traffic

Step 4: Results

The Skill generates:

• results.csv: Detailed analysis with scores and ratings
• report.md: Comprehensive analysis report with goal-specific insights
• strategy.md: Strategy recommendations based on the selected goal

Output Interpretation

CSV Output Columns

Column	Description
广告系列	Campaign Series
广告组	Ad Group
广告名称	Ad Name
总花费(USD)	Total Spend
总展示次数	Total Impressions
总点击量	Total Clicks
CTR(%)	Click-Through Rate
CPC(USD)	Cost Per Click
CPM(USD)	Cost Per Mille
互动率(%)	Engagement Rate
转化率(%)	Conversion Rate
综合得分	Composite Score (0-100)
评级	Rating (优秀/中等/差)

Rating Guide

• Score > 47: 🟢 Excellent - Increase budget by 20-50%
• Score 26-47: 🟡 Medium - A/B test, refine targeting
• Score < 26: 🔴 Poor - Pause or rebuild

Advanced Usage

Custom Analysis

For specific analysis needs, specify:

• Date range to analyze
• Specific regions to focus on
• Metrics to prioritize

Batch Processing

Process multiple CSV files:

Analyze all Facebook ad exports in the current directory

Report Customization

Request specific report sections:

• "Generate only the top 10 ads list"
• "Create strategy recommendations only"
• "Show region-by-region breakdown"

Example Interactions

Basic Analysis with Goal Selection:

User: Analyze my Facebook ads data in ads.csv
Claude: I'll analyze your Facebook ads data. First, I need to know your advertising goal to provide the most relevant insights. What is your primary goal for this campaign?
1. Interaction (互动) - Focus on message conversations and engagement
2. Conversion (转化) - Focus on leads, purchases, and conversions
3. Traffic (流量) - Focus on clicks and impressions

User: My goal is to increase message conversations (互动目标)
Claude: [Uses Skill to load, analyze with interaction weights, and generate goal-specific insights]

Optimization Focus:

User: Which ads should I pause based on this CSV?
Claude: To provide accurate recommendations, I need to know your advertising goal. What are you optimizing for?
1. Interaction (互动) - Message conversations
2. Conversion (转化) - Leads and purchases
3. Traffic (流量) - Clicks and impressions

User: We're focused on conversions (转化目标)
Claude: [Uses Skill to identify poor performing ads with conversion-specific recommendations]

Strategy Request:

User: Create a media plan from this Facebook data
Claude: [Uses Skill to generate strategy options with budget allocation]

Requirements

The Skill requires these Python packages:

pip install pandas numpy

For advanced features (optional):

pip install matplotlib seaborn  # For visualization

Best Practices

1. Data Quality: Ensure CSV exports are complete and from the same time period
2. Regular Analysis: Run analysis weekly to track performance trends
3. Action Oriented: Use recommendations to make immediate changes
4. Document Changes: Keep track of optimizations and their effects

Troubleshooting

Issue: "Column not found" error

• Solution: Verify CSV is from Facebook Ads Manager with Chinese column names

Issue: "Empty results"

• Solution: Check CSV has data rows (not just headers)

Issue: "Encoding error"

• Solution: Ensure CSV is exported with UTF-8 encoding

Issue: Skill not activating

• Solution: Use keywords like "Facebook ads", "ad performance", or "optimization"

Related Files

• QUICKSTART.md - 5-minute getting started guide
• EXAMPLES.md - Detailed usage examples
• REFERENCE.md - Complete API documentation
• scripts/analyzer.py - Main analysis script

Support

For issues or questions:

1. Check EXAMPLES.md for common scenarios
2. Review REFERENCE.md for technical details
3. Verify your CSV format matches requirements