Facebook Ads Analyzer

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

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