rsa-refresh

name	rsa-refresh
description	Refresh RSA ad copy by scraping the business website, identifying LOW-performing assets, and generating replacement headlines and descriptions using AI. Auto-invoke when user says 'refresh RSAs for [account]', 'update RSA assets', 'rewrite RSAs', or 'replace low-performing RSA assets'. Uses Firecrawl for scraping and Claude for copy generation.

RSA Refresh Skill

Refreshes Responsive Search Ad copy by replacing LOW-performing assets with new AI-generated headlines and descriptions verified against the actual business website.

Workflow

Stage 1: Prepare Context

python scripts/rsa_refresh_generator.py \
  --cid YOUR_CID \
  --sheet-id YOUR_SHEET_ID \
  --prepare-for-claude

This will:

1. Query existing RSAs and asset performance labels (BEST/GOOD/LOW/LEARNING)
2. Scrape the business website using Firecrawl
3. Extract property/business features from the site
4. Output rsa_context_{cid}.json with all data Claude needs

Stage 2: Generate Copy (Claude Code)

Read rsa_context_{cid}.json and generate replacement headlines + descriptions following the reference docs:

• references/pm-headline-structure.md -- 15 headline rules (1 customizer + 14 AI-generated)
• references/description-voice-lifting.md -- 3 descriptions with voice lifting technique
• references/hallucination-filter.md -- Defense-in-depth filter for unverified claims

Save output as copy_{cid}.json with format:

{
  "headlines": {"AD_ID_1": ["H1", "H2", ...], "AD_ID_2": [...]},
  "descriptions": ["D1", "D2", "D3"]
}

Stage 3: Resume and Write to Sheet

python scripts/rsa_refresh_generator.py \
  --cid YOUR_CID \
  --sheet-id YOUR_SHEET_ID \
  --copy-file copy_YOUR_CID.json

This merges AI copy with existing ad structure and writes to Google Sheets with "Original RSAs" and "Refreshed RSAs" tabs. Review in the sheet before importing to Google Ads Editor.

Key Rules

• Empty > Inaccurate -- never include unverified claims
• Only use information explicitly found on the business website
• See references/hallucination-filter.md for forbidden terms
• LOW-performing assets are the primary replacement targets
• BEST and GOOD assets (and all customizer assets) are preserved

Prerequisites

• google-ads.yaml at project root (Google Ads API credentials)
• token-sheets.json at project root OR a refresh token in google-ads.yaml with the spreadsheets scope
• FIRECRAWL_API_KEY environment variable (set in .env or shell — get a key at firecrawl.dev)
• pip install google-ads gspread google-auth pyyaml python-dotenv firecrawl-py requests beautifulsoup4 playwright

Override paths if needed:

--config path/to/google-ads.yaml --sheets-token path/to/token-sheets.json

Optional: Pre-Refresh Baseline

python scripts/rsa_baseline_snapshot.py \
  --cid YOUR_CID \
  --account-name "Account Display Name" \
  --sheet-id YOUR_SHEET_ID

Captures IWQS, QS components, ad metrics, and impression share before making changes so you can measure improvement afterward. Writes to an "RSA Baseline" tab.

You can also have the generator capture the baseline automatically by adding --baseline-sheet-id YOUR_SHEET_ID to Stage 1.

Vertical Note

The helpers in scripts/rsa_refresh_generator.py (generate_keyword_headlines, generate_brand_headline) and the reference docs under references/ are tuned for property management (apartment / rental) accounts. To adapt for another vertical:

1. Replace the three files under references/ with your own headline structure, voice guide, and hallucination filter
2. Update the HALLUCINATION_PATTERNS list in the generator to match your industry's unverifiable claims
3. Rewrite generate_keyword_headlines for your ad-group taxonomy

Optional Enhancements

Set these env vars to enable additional context when generating copy:

• COMPLIANCE_PATH — directory containing a compliance/ad_copy_validator.py module to add geographic validation (checks headlines reference the correct city/state)
• SERP_API_PATH — directory containing get_gmb_reviews.py and analyze_competitors_for_rsa.py to add Google My Business social proof and competitor USP analysis to the context JSON

Both are optional. The script gracefully skips these features when the modules aren't available.

Related Skills

• ad-copy-verification-standard -- Mandatory verification protocol
• google-ads-creation -- RSA validation rules