Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat: Claude Code plugin refactor + Google Ads skill quality upgrade (#24)

Tong Chen11d7f5dddc99
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 00000000..beca4927
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,20 @@
+{
+ "name": "nowork-studio",
+ "owner": {
+ "name": "nowork-studio"
+ },
+ "metadata": {
+ "description": "SEO and Google Ads skills for Claude Code",
+ "version": "0.9.1"
+ },
+ "plugins": [
+ {
+ "name": "toprank",
+ "source": "./",
+ "description": "SEO analysis, Google Ads management, keyword research, content optimization, schema markup, and meta tags optimization.",
+ "version": "0.9.1",
+ "author": { "name": "nowork-studio" },
+ "category": "productivity"
+ }
+ ]
+}
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 00000000..90d42999
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,9 @@
+{
+ "name": "toprank",
+ "version": "0.9.1",
+ "description": "SEO analysis, Google Ads management, keyword research, content optimization, and schema markup tools powered by Google Search Console and Google Ads APIs.",
+ "author": {
+ "name": "nowork-studio"
+ },
+ "skills": "./skills/"
+}
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 00000000..02f5d213
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,13 @@
+{
+ "mcpServers": {
+ "adsagent": {
+ "command": "npx",
+ "args": [
+ "-y", "mcp-remote",
+ "https://www.adsagent.org/api/mcp",
+ "--transport", "http-first",
+ "--header", "Authorization:Bearer ${ADSAGENT_API_KEY}"
+ ]
+ }
+ }
+}
diff --git a/README.md b/README.md
index ce876d97..2ec634b5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# Toprank
-**SEO + Google Ads skills for Claude Code and Codex. Data-driven decisions, not dashboards.**
+**SEO + Google Ads skills for Claude Code. Data-driven decisions, not dashboards.**
Toprank gives your AI agent direct access to Google Search Console and Google Ads. It analyzes your traffic, surfaces what's hurting your rankings, finds wasted ad spend, and tells you exactly what to fix. When you have access to the repo, it goes further: rewriting meta tags, fixing headings, adding structured data, and shipping the changes.
@@ -17,7 +17,7 @@ Free, open-source. Install in 30 seconds.
### Google Ads
```
-You: /ads-audit
+You: /toprank:ads-audit
Claude: Connected to your Google Ads account (MyStore).
@@ -39,7 +39,7 @@ Claude: Connected to your Google Ads account (MyStore).
2. Add 12 negative keywords ($130/mo wasted on irrelevant terms)
3. Increase bids 15% on 2 high-converting keywords losing IS
- Business context saved — /ads-copy and /ads will use it.
+ Business context saved — /toprank:ads-copy and /toprank:ads will use it.
You: Do it all.
@@ -50,40 +50,10 @@ You: Do it all.
Done. All changes are reversible within 7 days.
```
-```
-You: Write new ad copy for my boarding service
-
-Claude: [reads your business context — knows your brand voice,
- differentiators, seasonal peaks, keyword landscape]
-
- [pulls current ad performance and search term language]
-
- VARIANT A: "Safety-First"
- H1 [Pin 1]: Dog Boarding in Seattle (25 chars)
- H2: Cage-Free, Supervised Care (26 chars)
- H3: Book Your Pet's Stay (20 chars)
- D1: Safe, cage-free boarding. Supervised play, daily updates.
- D2: Open 7 days. 3 locations. Book online now.
-
- VARIANT B: "Convenience"
- H1 [Pin 1]: Dog Boarding Near SeaTac (25 chars)
- H2: Drop Off Anytime, 7 Days (24 chars)
- ...
-
- Deploy Variant A?
-
-You: Yes, both as an A/B test.
-
- [created 2 RSAs in ad group, both paused]
- [enabled both — A/B test running]
-
- Check back in 2 weeks or after 100 clicks per variant.
-```
-
### SEO
```
-You: /seo-analysis
+You: /toprank:seo-analysis
Claude: Found your site at mystore.com — pulling Search Console data now.
@@ -102,281 +72,112 @@ Claude: Found your site at mystore.com — pulling Search Console data now.
doesn't match what people actually search for.
Here's your 30-day plan, most impactful first.
-
-You: Implement all of it.
-
- [fixes duplicate homepage — 2 lines of config]
- [consolidates competing pages, updates all internal links]
- [rewrites page titles to match real search queries]
-
- Done. Ready to ship.
```
---
-## Google Ads Setup
-
-The ads skills need an MCP server that talks to the Google Ads API. Two options:
+## Install
-### Option A: Free hosted server (easiest)
+Toprank is a **Claude Code plugin**. One-time setup, automatic updates.
-[AdsAgent](https://www.adsagent.org) runs a free MCP server so you don't have to deal with Google Ads API credentials, OAuth, or infrastructure.
+### Step 1: Add the marketplace
-1. **Get a free token** at [adsagent.org](https://www.adsagent.org) — sign in with Google to connect your Google Ads account
-2. **Run `/ads-audit`** in Claude Code — it walks you through setup and saves your token to `~/.adsagent/config.json`
-3. **Done** — all ads skills (`/ads`, `/ads-audit`, `/ads-copy`) now work
-
-<details>
-<summary>Manual MCP config (if you skipped the setup script)</summary>
-
-Add this to your Claude Code MCP config (`~/.claude/settings.json` or project `.mcp.json`):
+Open Claude Code settings and add to `extraKnownMarketplaces`:
```json
{
- "mcpServers": {
- "adsagent": {
- "command": "npx",
- "args": [
- "-y", "mcp-remote",
- "https://www.adsagent.org/api/mcp",
- "--transport", "http-first",
- "--header", "Authorization:Bearer YOUR_TOKEN_HERE"
- ],
- "env": {
- "ADS_AGENT_KEY": "YOUR_TOKEN_HERE"
+ "extraKnownMarketplaces": {
+ "nowork-studio": {
+ "source": {
+ "source": "github",
+ "repo": "nowork-studio/toprank"
}
}
}
}
```
-Replace `YOUR_TOKEN_HERE` with the token from [adsagent.org](https://www.adsagent.org).
-
-</details>
-
-### Option B: Self-hosted MCP server
-
-If you already have Google Ads API access and prefer to run your own MCP server, point the skills at your server instead. The only requirement is that your server implements the same MCP tool interface (e.g. `listCampaigns`, `getKeywords`, `pauseKeyword`, etc.).
+### Step 2: Enable the plugin
-Update the MCP config to point at your server:
+Add to `enabledPlugins` in settings:
```json
{
- "mcpServers": {
- "adsagent": {
- "command": "npx",
- "args": [
- "-y", "mcp-remote",
- "https://your-server.example.com/mcp",
- "--transport", "http-first",
- "--header", "Authorization:Bearer YOUR_AUTH_TOKEN"
- ]
- }
+ "enabledPlugins": {
+ "toprank@nowork-studio": true
}
}
```
-As long as your server exposes the same tools, the skills work identically.
-
----
-
-## Google Ads Skills
-
-### [`ads-audit`](google-ads/ads-audit/) — Account Audit & Business Context Setup
-
-**Run this first.** Audits your Google Ads account health and builds a business context profile that all other ads skills reuse.
-
-**What it does:**
-- Pulls all account data (campaigns, keywords, search terms, ads, impression share, conversions)
-- Scores 7 health dimensions: conversion tracking, campaign structure, keyword health, search term quality, ad copy, impression share, spend efficiency
-- Identifies wasted spend with specific keywords and dollar amounts
-- Builds and saves business context (brand voice, seasonality, competitors, keyword landscape) to `~/.adsagent/business-context.json`
-- Produces a prioritized action plan — top 3 things to fix first
-
-**How to trigger:**
-> "audit my ads", "ads audit", "set up my ads", "account overview", "how's my account", "ads health check", "what should I fix"
-
-### [`ads`](google-ads/ads/) — Google Ads Management
-
-Manage your Google Ads campaigns directly from Claude. Read performance data, optimize keywords, adjust bids and budgets, add negative keywords, and more. Powered by [AdsAgent](https://www.adsagent.org)'s free MCP server.
-
-**What it does:**
-- Reads campaign performance, keywords, search terms, impression share
-- Pauses wasteful keywords and adds negative keywords
-- Adjusts bids (within guardrails) and campaign budgets
-- Creates campaigns, ad groups, and responsive search ads
-- Every change is reversible within 7 days via `undoChange`
-
-**How to trigger:**
-> "how are my ads doing", "find wasted spend", "optimize bids", "add negative keywords", "pause campaign", "Google Ads performance", "check my ads"
-
-### [`ads-copy`](google-ads/ads-copy/) — Ad Copy Generator & A/B Testing
-
-Write Google Ads RSA copy grounded in your performance data and business context. Generates multiple variants with distinct messaging angles, deploys them, and tracks A/B test results.
-
-**What it does:**
-- Reads business context and current ad performance before writing
-- Generates RSA headlines (≤30 chars) and descriptions (≤90 chars) with character counts
-- Presents 2-3 named variants with pin positions and messaging angles
-- Deploys approved variants directly via `createAd` / `updateAdAssets`
-- Sets up and evaluates A/B tests with clear winner criteria
-
-**How to trigger:**
-> "write ad copy", "new headlines", "improve my ads CTR", "A/B test my ads", "RSA copy", "ad variants", "write me an ad"
-
-**Setup:** All Google Ads skills need a free token from [adsagent.org](https://www.adsagent.org). The setup script or `/ads-audit` will walk you through it.
-
----
-
-## SEO Skills
-
-### [`seo-analysis`](seo/seo-analysis/) — SEO Audit & Search Console Analysis
-
-A full SEO audit in one command. Connects to Google Search Console, auto-detects your site, and produces a prioritized action plan.
-
-**What it does:**
-- Guides you through GSC API setup if needed (one `gcloud` command)
-- Auto-detects your site URL if you're inside a website repo
-- Pulls 90 days of query/page performance data
-- Surfaces **quick wins**: position 4–10 queries, high-impression low-CTR pages
-- Flags **traffic drops** with period-over-period comparison
-- **Technical audit**: indexability, meta tags, headings, structured data, canonical URLs
-- Outputs a structured report with a 30-day action plan
-
-**How to trigger:**
-> "analyze my SEO", "SEO audit", "why is my traffic down", "what keywords am I ranking for", "check my search console", "improve my rankings", "technical SEO audit"
-
-### [`content-writer`](seo/content-writer/) — SEO Content Creation
-
-Write blog posts, landing pages, or improve existing content following Google's E-E-A-T and Helpful Content guidelines. Works standalone or spawned automatically by `seo-analysis` when content gaps are found.
-
-**What it does:**
-- Determines content type from context (blog post, landing page, or content improvement)
-- Researches search intent and SERP landscape before writing
-- Produces publication-ready content with SEO metadata, JSON-LD structured data, and internal linking plan
-- Quality gate checks: "last click" test, E-E-A-T signals, anti-pattern detection
-- When spawned by `seo-analysis`, writes multiple pieces in parallel for identified content gaps
-
-**How to trigger:**
-> "write a blog post about X", "create a landing page for Y", "improve this page", "content for keyword X", "draft an article", "rewrite this page"
-
-### [`keyword-research`](seo/keyword-research/) — Keyword Discovery & Analysis
+### Step 3: Configure Google Ads (optional)
-Discover high-value keywords, assess difficulty, classify search intent, and build topic clusters. Works standalone or feeds directly into `content-writer`.
+If you use Google Ads, set your AdsAgent API key (free from [adsagent.org](https://www.adsagent.org)):
-**What it does:**
-- Generates keyword lists from seed terms with long-tail variations
-- Classifies search intent (informational, navigational, commercial, transactional)
-- Scores keyword difficulty and calculates opportunity (volume x intent / difficulty)
-- Groups keywords into topic clusters with pillar/cluster relationships
-- Produces a prioritized content calendar
-
-**How to trigger:**
-> "keyword research", "find keywords", "what should I write about", "keyword analysis", "content ideas", "search volume", "keyword difficulty"
-
-### [`meta-tags-optimizer`](seo/meta-tags-optimizer/) — Title Tags, Meta Descriptions & Social Tags
-
-Create and optimize meta tags for better click-through rates in search results and social sharing.
-
-**What it does:**
-- Writes compelling title tags (50–60 chars) with keyword placement and power words
-- Creates meta descriptions (150–160 chars) with clear CTAs
-- Generates Open Graph and Twitter Card tags for social previews
-- Provides multiple A/B test variations with CTR impact estimates
-- Validates character lengths for proper SERP display
-
-**How to trigger:**
-> "optimize title tag", "write meta description", "improve CTR", "Open Graph tags", "fix my meta tags", "social media preview", "my click rate is low"
-
-### [`schema-markup-generator`](seo/schema-markup-generator/) — JSON-LD Structured Data
-
-Generate valid JSON-LD schema markup for rich results in Google Search.
+```bash
+export ADSAGENT_API_KEY=your_key_here
+```
-**What it does:**
-- Selects appropriate schema types based on content (FAQ, HowTo, Article, Product, LocalBusiness, etc.)
-- Generates ready-to-paste JSON-LD with all required properties
-- Handles complex multi-type schemas on a single page
-- Provides SERP preview showing expected rich result appearance
-- Includes validation guidance and implementation instructions
+The plugin's bundled MCP server picks this up automatically. Or configure any Google Ads MCP server manually.
-**How to trigger:**
-> "add schema markup", "generate structured data", "JSON-LD", "rich snippets", "FAQ schema", "product markup"
+That's it. All skills are now available.
---
-## Install — 30 seconds
-
-**Requirements:** Python 3.8+, `gcloud` CLI (`brew install google-cloud-sdk`), and one of:
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
-- [Codex](https://github.com/openai/codex) (`npm install -g @openai/codex`)
+## Skills
-### Claude Code
-
-Open Claude Code and paste this. Claude does the rest.
-
-> Install toprank: run **`git clone --single-branch --depth 1 https://github.com/nowork-studio/toprank.git ~/.claude/skills/toprank && cd ~/.claude/skills/toprank && ./setup`** then add a "toprank" section to CLAUDE.md that lists the available skills: /seo-analysis, /content-writer, /keyword-research, /meta-tags-optimizer, /schema-markup-generator, /ads-audit, /ads, /ads-copy.
-
-Add to your repo so teammates get it (optional):
-
-> Add toprank to this project: run **`cp -Rf ~/.claude/skills/toprank .claude/skills/toprank && cd .claude/skills/toprank && ./setup`** then add a "toprank" section to this project's CLAUDE.md that lists the available skills: /seo-analysis, /content-writer, /keyword-research, /meta-tags-optimizer, /schema-markup-generator, /ads-audit, /ads, /ads-copy.
+### Google Ads
-### Codex
+| Skill | What it does |
+|-------|-------------|
+| [`ads-audit`](skills/ads-audit/) | Account audit + business context setup. Run this first. Scores 7 health dimensions, identifies wasted spend, builds business profile. |
+| [`ads`](skills/ads/) | Campaign management. Read performance, optimize keywords, adjust bids/budgets, add negatives, create campaigns. |
+| [`ads-copy`](skills/ads-copy/) | RSA copy generator + A/B testing. Data-driven headlines and descriptions with character counts and pin positions. |
-Install to one repo:
+### SEO
-```bash
-git clone --single-branch --depth 1 https://github.com/nowork-studio/toprank.git .agents/skills/toprank
-cd .agents/skills/toprank && ./setup --host codex
-```
+| Skill | What it does |
+|-------|-------------|
+| [`seo-analysis`](skills/seo-analysis/) | Full SEO audit with GSC data. Quick wins, traffic drops, technical issues, 30-day action plan. |
+| [`content-writer`](skills/content-writer/) | SEO content creation following E-E-A-T guidelines. Blog posts, landing pages, content improvements. |
+| [`keyword-research`](skills/keyword-research/) | Keyword discovery, intent classification, topic clusters, prioritized content calendar. |
+| [`meta-tags-optimizer`](skills/meta-tags-optimizer/) | Title tags, meta descriptions, OG/Twitter cards with A/B variations and CTR estimates. |
+| [`schema-markup-generator`](skills/schema-markup-generator/) | JSON-LD structured data for rich results. FAQ, HowTo, Article, Product, LocalBusiness. |
+| [`setup-cms`](skills/setup-cms/) | Connect WordPress, Strapi, Contentful, or Ghost for automated SEO field audits. |
-Install globally:
-
-```bash
-git clone --single-branch --depth 1 https://github.com/nowork-studio/toprank.git ~/toprank
-cd ~/toprank && ./setup --host codex
-```
-
-Setup auto-detects which agents you have when you use `--host auto` (the default).
+All skills are namespaced: `/toprank:ads`, `/toprank:seo-analysis`, etc.
---
-## How Skills Work
-
-Each skill is a `SKILL.md` file that your agent loads as an instruction set. The agent reads the skill and follows its workflow, calling scripts, crawling pages, querying APIs, to produce a structured output.
+## How It Works
-Skills are discovered automatically. Claude Code reads from `~/.claude/skills/`, Codex reads from `.agents/skills/`. The `./setup` script handles both.
+Toprank is a Claude Code plugin. Each skill is a `SKILL.md` file with supporting reference documents, scripts, and eval tests.
```
toprank/
-├── setup <- run this to register skills
-├── seo/ <- SEO skills
+├── .claude-plugin/
+│ ├── plugin.json <- plugin metadata
+│ └── marketplace.json <- registry entry
+├── .mcp.json <- AdsAgent MCP server (auto-configured)
+├── skills/
│ ├── seo-analysis/
-│ │ ├── SKILL.md <- SEO audit workflow
-│ │ ├── scripts/ <- Python scripts for GSC API
-│ │ └── references/
-│ ├── content-writer/
-│ │ ├── SKILL.md <- content creation workflow
-│ │ └── references/
+│ │ ├── SKILL.md <- SEO audit workflow
+│ │ ├── scripts/ <- Python scripts for GSC API
+│ │ ├── references/ <- domain expertise docs
+│ │ └── evals/ <- quality tests
+│ ├── ads/
+│ │ ├── SKILL.md <- Google Ads management
+│ │ ├── references/ <- benchmarks, decision trees
+│ │ └── evals/ <- quality tests
+│ ├── ads-audit/
+│ ├── ads-copy/
│ ├── keyword-research/
-│ │ ├── SKILL.md <- keyword discovery & analysis
-│ │ └── references/
│ ├── meta-tags-optimizer/
-│ │ ├── SKILL.md <- title/description/OG optimization
-│ │ └── references/
│ ├── schema-markup-generator/
-│ │ ├── SKILL.md <- JSON-LD structured data
-│ │ └── references/
-│ └── setup-cms/
-│ └── SKILL.md <- CMS configuration wizard
-├── google-ads/ <- Google Ads skills
-│ ├── ads-audit/
-│ │ └── SKILL.md <- account audit + business context
-│ ├── ads/
-│ │ └── SKILL.md <- Google Ads management
-│ └── ads-copy/
-│ └── SKILL.md <- RSA copy generator + A/B testing
-└── toprank-upgrade/
- └── SKILL.md <- auto-upgrade workflow
+│ ├── content-writer/
+│ ├── setup-cms/
+│ └── toprank-upgrade/
+├── test/ <- unit + LLM-judge eval tests
+└── VERSION
```
---
diff --git a/bin/preamble.md b/bin/preamble.md
deleted file mode 100755
index cd38a6a1..00000000
--- a/bin/preamble.md
+++ /dev/null
@@ -1,14 +0,0 @@
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
-
-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
-
----
-
diff --git a/bin/toprank-config b/bin/toprank-config
deleted file mode 100755
index cc0d0a5e..00000000
--- a/bin/toprank-config
+++ /dev/null
@@ -1,39 +0,0 @@
-#!/usr/bin/env bash
-# toprank-config — read/write ~/.toprank/config.yaml
-#
-# Usage:
-# toprank-config get <key> — read a config value
-# toprank-config set <key> <value> — write a config value
-# toprank-config list — show all config
-#
-# Env overrides (for testing):
-# TOPRANK_STATE_DIR — override ~/.toprank state directory
-set -euo pipefail
-
-STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"
-CONFIG_FILE="$STATE_DIR/config.yaml"
-
-case "${1:-}" in
- get)
- KEY="${2:?Usage: toprank-config get <key>}"
- grep -E "^${KEY}:" "$CONFIG_FILE" 2>/dev/null | tail -1 | awk '{print $2}' | tr -d '[:space:]' || true
- ;;
- set)
- KEY="${2:?Usage: toprank-config set <key> <value>}"
- VALUE="${3:?Usage: toprank-config set <key> <value>}"
- mkdir -p "$STATE_DIR"
- if grep -qE "^${KEY}:" "$CONFIG_FILE" 2>/dev/null; then
- _tmpfile="$(mktemp "${CONFIG_FILE}.XXXXXX")"
- sed "s/^${KEY}:.*/${KEY}: ${VALUE}/" "$CONFIG_FILE" > "$_tmpfile" && mv "$_tmpfile" "$CONFIG_FILE"
- else
- echo "${KEY}: ${VALUE}" >> "$CONFIG_FILE"
- fi
- ;;
- list)
- cat "$CONFIG_FILE" 2>/dev/null || true
- ;;
- *)
- echo "Usage: toprank-config {get|set|list} [key] [value]"
- exit 1
- ;;
-esac
diff --git a/bin/toprank-update-check b/bin/toprank-update-check
deleted file mode 100755
index a089d31f..00000000
--- a/bin/toprank-update-check
+++ /dev/null
@@ -1,167 +0,0 @@
-#!/usr/bin/env bash
-# toprank-update-check — periodic version check for toprank skills.
-#
-# Output (one line, or nothing):
-# JUST_UPGRADED <old> <new> — marker found from recent upgrade
-# UPGRADE_AVAILABLE <old> <new> — remote VERSION differs from local
-# (nothing) — up to date, snoozed, disabled, or check skipped
-#
-# Env overrides (for testing):
-# TOPRANK_DIR — override auto-detected toprank root
-# TOPRANK_REMOTE_URL — override remote VERSION URL
-# TOPRANK_STATE_DIR — override ~/.toprank state directory
-set -euo pipefail
-
-TOPRANK_DIR="${TOPRANK_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
-STATE_DIR="${TOPRANK_STATE_DIR:-$HOME/.toprank}"
-CACHE_FILE="$STATE_DIR/last-update-check"
-MARKER_FILE="$STATE_DIR/just-upgraded-from"
-SNOOZE_FILE="$STATE_DIR/update-snoozed"
-VERSION_FILE="$TOPRANK_DIR/VERSION"
-REMOTE_URL="${TOPRANK_REMOTE_URL:-https://raw.githubusercontent.com/nowork-studio/toprank/main/VERSION}"
-CONFIG_BIN="$TOPRANK_DIR/bin/toprank-config"
-VERSION_RE='^[0-9]+(\.[0-9]+)+$'
-
-# State dir must exist early so any writes below succeed.
-mkdir -p "$STATE_DIR"
-
-# ─── Force flag (busts cache + snooze for standalone /toprank-upgrade) ──
-if [ "${1:-}" = "--force" ]; then
- rm -f "$CACHE_FILE"
- rm -f "$SNOOZE_FILE"
-fi
-
-# ─── Step 0: Check if updates are disabled ────────────────────
-_UC=$("$CONFIG_BIN" get update_check 2>/dev/null || true)
-if [ "$_UC" = "false" ]; then
- exit 0
-fi
-
-# ─── Snooze helper ──────────────────────────────────────────
-# check_snooze <remote_version>
-# Returns 0 if snoozed (stay quiet), 1 if not snoozed (should output).
-#
-# Snooze file format: <version> <level> <epoch>
-# Level durations: 1=24h, 2=48h, 3+=7d
-# New version resets snooze.
-check_snooze() {
- local remote_ver="$1"
- if [ ! -f "$SNOOZE_FILE" ]; then
- return 1
- fi
- local snoozed_ver snoozed_level snoozed_epoch
- snoozed_ver="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
- snoozed_level="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
- snoozed_epoch="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
-
- if [ -z "$snoozed_ver" ] || [ -z "$snoozed_level" ] || [ -z "$snoozed_epoch" ]; then
- return 1
- fi
- case "$snoozed_level" in *[!0-9]*) return 1 ;; esac
- case "$snoozed_epoch" in *[!0-9]*) return 1 ;; esac
-
- if [ "$snoozed_ver" != "$remote_ver" ]; then
- return 1
- fi
-
- local duration
- case "$snoozed_level" in
- 1) duration=86400 ;; # 24 hours
- 2) duration=172800 ;; # 48 hours
- *) duration=604800 ;; # 7 days (level 3+)
- esac
-
- local now
- now="$(date +%s)"
- local expires=$(( snoozed_epoch + duration ))
- if [ "$now" -lt "$expires" ]; then
- return 0 # still snoozed
- fi
- return 1 # snooze expired
-}
-
-# ─── Step 1: Read and validate local version ─────────────────
-LOCAL=""
-if [ -f "$VERSION_FILE" ]; then
- LOCAL="$(cat "$VERSION_FILE" 2>/dev/null | tr -d '[:space:]')"
-fi
-if [ -z "$LOCAL" ]; then
- exit 0
-fi
-# Reject malformed local VERSION to avoid writing garbage to cache.
-if ! echo "$LOCAL" | grep -qE "$VERSION_RE"; then
- exit 0
-fi
-
-# ─── Step 2: Check "just upgraded" marker ─────────────────────
-# Exit immediately after printing JUST_UPGRADED — do not fall through
-# to the network fetch or we'd produce two output lines.
-if [ -f "$MARKER_FILE" ]; then
- OLD="$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]')"
- rm -f "$MARKER_FILE"
- rm -f "$SNOOZE_FILE"
- if [ -n "$OLD" ]; then
- echo "JUST_UPGRADED $OLD $LOCAL"
- fi
- exit 0
-fi
-
-# ─── Step 3: Check cache freshness ──────────────────────────
-# UP_TO_DATE: 60 min TTL. UPGRADE_AVAILABLE: 720 min TTL (keep notifying).
-if [ -f "$CACHE_FILE" ]; then
- CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
- case "$CACHED" in
- UP_TO_DATE*) CACHE_TTL=5 ;;
- UPGRADE_AVAILABLE*) CACHE_TTL=720 ;;
- *) CACHE_TTL=0 ;;
- esac
-
- STALE=$(find "$CACHE_FILE" -mmin +$CACHE_TTL 2>/dev/null || true)
- if [ -z "$STALE" ] && [ "$CACHE_TTL" -gt 0 ]; then
- case "$CACHED" in
- UP_TO_DATE*)
- CACHED_VER="$(echo "$CACHED" | awk '{print $2}')"
- if [ "$CACHED_VER" = "$LOCAL" ]; then
- exit 0
- fi
- ;;
- UPGRADE_AVAILABLE*)
- CACHED_OLD="$(echo "$CACHED" | awk '{print $2}')"
- if [ "$CACHED_OLD" = "$LOCAL" ]; then
- CACHED_NEW="$(echo "$CACHED" | awk '{print $3}')"
- if check_snooze "$CACHED_NEW"; then
- exit 0
- fi
- echo "$CACHED"
- exit 0
- fi
- ;;
- esac
- fi
-fi
-
-# ─── Step 4: Slow path — fetch remote version ────────────────
-REMOTE="$(curl -sf --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
-REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
-
-# Validate: must look like a version number (reject HTML error pages, etc.)
-if ! echo "$REMOTE" | grep -qE "$VERSION_RE"; then
- _TMP="$CACHE_FILE.$$.tmp"
- echo "UP_TO_DATE $LOCAL" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
- exit 0
-fi
-
-if [ "$LOCAL" = "$REMOTE" ]; then
- _TMP="$CACHE_FILE.$$.tmp"
- echo "UP_TO_DATE $LOCAL" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
- exit 0
-fi
-
-# Versions differ — upgrade available
-_TMP="$CACHE_FILE.$$.tmp"
-echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$_TMP" && mv "$_TMP" "$CACHE_FILE" || rm -f "$_TMP"
-if check_snooze "$REMOTE"; then
- exit 0
-fi
-
-echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"
diff --git a/google-ads/ads-audit/SKILL.md b/google-ads/ads-audit/SKILL.md
deleted file mode 100644
index f0e7a6a1..00000000
--- a/google-ads/ads-audit/SKILL.md
+++ /dev/null
@@ -1,266 +0,0 @@
----
-name: ads-audit
-description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to AdsAgent and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.
----
-
-# Google Ads Audit + Business Context Setup
-
-This is the starting point for any Google Ads account. It does two things:
-
-1. **Audits the account** — surfaces what's working, what's wasting money, and what to fix first
-2. **Builds business context** — gathers and saves business information to `~/.adsagent/business-context.json` so every other ads skill (copy, landing pages, competitive analysis) can use it without re-asking
-
-Run this before anything else. If another ads skill finds `business-context.json` missing, it should point the user here.
-
-## Setup
-
-Before anything else, verify the user has the AdsAgent MCP server connected and a token configured. Follow these steps in order — stop at the first issue and resolve it before continuing.
-
-### Step 1: Check for the AdsAgent MCP server
-
-Try calling `mcp__adsagent__listConnectedAccounts`. If the tool exists and responds, the MCP server is connected — skip to Step 2.
-
-If the tool doesn't exist (not in available tools), the MCP server isn't configured. Guide the user:
-
-> The AdsAgent MCP server isn't connected yet. To set it up:
->
-> 1. **Get a free token** at [adsagent.org](https://www.adsagent.org)
-> 2. **Add the MCP server** to your Claude settings. Open your Claude Code settings (or Claude Desktop config) and add this to `mcpServers`:
->
-> ```json
-> {
-> "adsagent": {
-> "command": "npx",
-> "args": [
-> "-y", "mcp-remote",
-> "https://www.adsagent.org/api/mcp",
-> "--transport", "http-first",
-> "--header", "Authorization:Bearer YOUR_API_KEY"
-> ]
-> }
-> }
-> ```
->
-> Replace `YOUR_API_KEY` with the token from step 1.
->
-> 3. **Restart Claude** to pick up the new MCP server.
->
-> Alternatively, if you installed toprank via the setup script, re-run `./setup --api-key YOUR_KEY` and it will configure everything automatically.
-
-Wait for the user to complete setup before proceeding.
-
-### Step 2: Check for token and account
-
-Read `~/.adsagent/config.json` for `apiKey` (the token) and `accountId`.
-
-- If `apiKey` is missing, ask the user for their token and save it as `apiKey` in `~/.adsagent/config.json`.
-- If `accountId` is missing, run `mcp__adsagent__listConnectedAccounts`:
- - **One account** → save it automatically
- - **Multiple accounts** → show list, ask user to pick
- - **Zero accounts** → direct user to [adsagent.org](https://www.adsagent.org) to connect a Google Ads account
-
-## Phase 1: Pull Account Data
-
-Gather everything in parallel before asking the user a single question. The goal is to show up informed.
-
-**Account basics:**
-- `mcp__adsagent__getAccountInfo` — business name, currency, timezone
-- `mcp__adsagent__getAccountSettings` — auto-tagging, tracking template, conversion setup
-
-**Campaign structure:**
-- `mcp__adsagent__listCampaigns` — all campaigns with spend, clicks, conversions
-- `mcp__adsagent__listAdGroups` — ad groups per campaign (focus on top-spend campaigns)
-
-**Performance data:**
-- `mcp__adsagent__getCampaignPerformance` — daily trends for the last 30 days
-- `mcp__adsagent__getKeywords` — top keywords with quality scores, bids, conversions
-- `mcp__adsagent__getSearchTermReport` — actual search queries triggering ads
-- `mcp__adsagent__getImpressionShare` — search IS, top IS, budget-lost IS, rank-lost IS
-
-**Ads and conversions:**
-- `mcp__adsagent__listAds` — ad copy, status, and per-ad metrics
-- `mcp__adsagent__getConversionActions` — what conversions are set up and how they're configured
-- `mcp__adsagent__getNegativeKeywords` — existing negative keyword coverage
-
-**Recommendations:**
-- `mcp__adsagent__getRecommendations` — Google's optimization suggestions (evaluate critically, don't blindly follow)
-
-## Phase 2: Analyze and Score
-
-Work through each dimension. For each one, assign a quick status: OK / Needs Work / Critical.
-
-### Account Health Dimensions
-
-**1. Conversion tracking**
-- Are conversion actions set up? Are they firing?
-- Is auto-tagging enabled?
-- Red flag: spending money with no conversion tracking = flying blind
-
-**2. Campaign structure**
-- Are campaigns organized by service/product and location?
-- Are ad groups tightly themed (5-20 keywords each)?
-- Red flag: one ad group with 200 keywords = poor relevance
-
-**3. Keyword health**
-- What's the average quality score? (Below 5 = problems)
-- Any high-spend, zero-conversion keywords?
-- Are match types appropriate? (Broad match without negatives = waste)
-- Are there enough negatives blocking irrelevant queries?
-
-**4. Search term quality**
-- What % of search terms are relevant?
-- Are there obvious negatives missing?
-- Are there high-converting search terms not yet added as keywords?
-
-**5. Ad copy**
-- How many RSAs per ad group? (Should have at least 2 for testing)
-- Are headlines and descriptions varied or repetitive?
-- Are there ads with low CTR that need refreshing?
-
-**6. Impression share**
-- How much traffic are you losing to budget vs. rank?
-- Budget-lost IS > 20% = you're leaving money on the table or need to tighten targeting
-- Rank-lost IS > 50% = quality score or bid issues
-
-**7. Spend efficiency**
-- What's the overall CPA? How does it compare across campaigns?
-- Any campaigns with high spend but low conversions?
-- What % of spend goes to converting keywords vs. non-converting?
-
-## Phase 3: Build Business Context
-
-Now that you understand the account, fill in the business context. Pull as much as possible from the data you already have — only ask the user for what you can't infer.
-
-### What to infer from account data
-
-| Field | Source |
-|-------|--------|
-| `business_name` | `getAccountInfo` |
-| `services` | Campaign and ad group names, keyword themes |
-| `locations` | Campaign geo-targeting, location extensions |
-| `brand_voice` | Existing ad copy tone and word choices |
-| `keyword_landscape.high_intent_terms` | Top-converting keywords |
-| `keyword_landscape.competitive_terms` | Low impression share keywords with high CPC |
-| `keyword_landscape.long_tail_opportunities` | Converting search terms not yet added as keywords |
-
-### What to ask the user
-
-Present what you inferred, then ask for what's missing. Frame it conversationally, not as a checklist.
-
-**Always ask:**
-- "What makes you different from competitors?" → `differentiators`
-- "Who are your main competitors?" → `competitors`
-- "Is your business seasonal? When's your busiest time?" → `seasonality`
-- "What's your website URL?" → for landing page context
-
-**Ask if not obvious from data:**
-- Industry (if campaign names don't make it clear)
-- Target audience (if search terms don't reveal it)
-- Current offers or promotions
-- Social proof (reviews, awards, years in business)
-
-### Website analysis
-
-If the user provides their website URL (or it's visible in ad final URLs):
-
-- Note the URL in `landing_pages`
-- Look at what the ads link to — do headlines match landing page content?
-- Note any offers, trust signals, or CTAs visible on the site that could inform ad copy
-
-### Save the context
-
-Write the complete business context to `~/.adsagent/business-context.json`:
-
-```json
-{
- "business_name": "",
- "industry": "",
- "website": "",
- "services": [],
- "locations": [],
- "target_audience": "",
- "brand_voice": {
- "tone": "",
- "words_to_avoid": [],
- "words_to_use": []
- },
- "differentiators": [],
- "competitors": [],
- "seasonality": {
- "peak_months": [],
- "slow_months": [],
- "seasonal_hooks": []
- },
- "keyword_landscape": {
- "high_intent_terms": [],
- "competitive_terms": [],
- "long_tail_opportunities": []
- },
- "social_proof": [],
- "offers_or_promotions": [],
- "landing_pages": {},
- "notes": "",
- "audit_date": "",
- "account_id": ""
-}
-```
-
-Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.
-
-## Phase 4: Deliver the Audit Report
-
-Present findings as a concise, actionable report. No fluff — every line should either inform a decision or recommend an action.
-
-### Report format
-
-```
-# Google Ads Audit: [Business Name]
-**Account:** [ID] | **Period:** Last 30 days | **Date:** [today]
-
-## Scorecard
-| Dimension | Status | Summary |
-|----------------------|-------------|--------------------------------------|
-| Conversion tracking | OK / Needs Work / Critical | [one line] |
-| Campaign structure | ... | ... |
-| Keyword health | ... | ... |
-| Search term quality | ... | ... |
-| Ad copy | ... | ... |
-| Impression share | ... | ... |
-| Spend efficiency | ... | ... |
-
-## Key Numbers
-- **Total spend (30d):** $X,XXX
-- **Conversions:** XX at $XX CPA
-- **Top campaign:** [name] — XX% of spend, XX% of conversions
-- **Wasted spend:** ~$XXX on non-converting keywords/terms
-
-## Top 3 Actions (do these first)
-1. **[Action]** — [why, expected impact]
-2. **[Action]** — [why, expected impact]
-3. **[Action]** — [why, expected impact]
-
-## Detailed Findings
-[Organized by dimension — only include dimensions that need work.
-For each, state the problem, show the data, recommend the fix.]
-
-## Business Context Saved
-Saved to ~/.adsagent/business-context.json — other ads skills
-(/ads-copy, /ads-landing, /ads-compete) will use this automatically.
-[List any fields that are incomplete and need user input later.]
-```
-
-### What makes a good action item
-
-- **Specific:** "Pause keyword 'free dog food' — $847 spent, 0 conversions" not "Review underperforming keywords"
-- **Quantified:** Include the spend, impressions, or conversions at stake
-- **Prioritized:** Highest-impact items first. Stopping waste > starting new things
-- **Actionable with /ads:** Every recommendation should be something the user can execute immediately using the `/ads` skill
-
-## Rules
-
-1. **Data first, questions second.** Pull all account data before asking the user anything. Show up informed.
-2. **Infer before asking.** Don't ask "what industry are you in?" if the campaigns clearly say "plumbing services."
-3. **Be specific.** Name the campaigns, keywords, and dollar amounts. Vague advice is useless.
-4. **Prioritize by money.** The biggest waste or biggest opportunity comes first.
-5. **Save the context.** Always write `business-context.json` — this is the handoff to every other ads skill.
-6. **Don't fix things here.** This skill diagnoses and recommends. The user executes fixes with `/ads`. Offer to switch to `/ads` for implementation.
diff --git a/google-ads/ads-copy/SKILL.md b/google-ads/ads-copy/SKILL.md
deleted file mode 100644
index 1b100e44..00000000
--- a/google-ads/ads-copy/SKILL.md
+++ /dev/null
@@ -1,206 +0,0 @@
----
-name: ads-copy
-description: Generate and A/B test Google Ads copy. Use when asked to write ad copy, headlines, descriptions, create ad variants, test ad messaging, improve CTR, or generate RSA (Responsive Search Ad) components. Trigger on "ad copy", "write ads", "headlines", "descriptions", "RSA", "responsive search ad", "ad text", "ad creative", "improve CTR", "ad A/B test", "ad variants", "write me an ad", or when the user wants to improve click-through rate on existing ads.
----
-
-# Ad Copy Generator + A/B Tester
-
-Write Google Ads RSA copy and run structured A/B tests to find winning messaging.
-
-## Setup
-
-This skill requires the AdsAgent MCP server. Try calling `mcp__adsagent__listConnectedAccounts` to verify it's connected.
-
-- **If the tool doesn't exist** → the MCP server isn't configured. Run `/ads-audit` which walks the user through full setup (MCP server, token, account selection, and business context).
-- **If the tool works** → read `~/.adsagent/config.json` for `apiKey` and `accountId`. If missing, run `/ads-audit` for onboarding.
-
-## Business Context — Read First, Ask Once
-
-Every ad copy decision depends on understanding the business. This skill stores business context in `~/.adsagent/business-context.json` so it only needs to be gathered once.
-
-### On every invocation:
-
-1. **Read `~/.adsagent/business-context.json`**. If it exists and has content, use it — skip the intake interview.
-2. **If missing or empty**, run the intake interview below, then save the result.
-3. **If the user volunteers new info** (new service, changed positioning, seasonal update), merge it into the existing file.
-
-### Intake interview
-
-Gather these fields. Don't ask them as a rigid checklist — pull what you can from context (the account's existing ads, website, campaign names) and only ask what's missing.
-
-```json
-{
- "business_name": "",
- "industry": "",
- "services": [""],
- "locations": [""],
- "target_audience": "",
- "brand_voice": {
- "tone": "",
- "words_to_avoid": [""],
- "words_to_use": [""]
- },
- "differentiators": [""],
- "competitors": [""],
- "seasonality": {
- "peak_months": [""],
- "slow_months": [""],
- "seasonal_hooks": [""]
- },
- "keyword_landscape": {
- "high_intent_terms": [""],
- "competitive_terms": [""],
- "long_tail_opportunities": [""]
- },
- "social_proof": [""],
- "offers_or_promotions": [""],
- "landing_pages": {},
- "notes": ""
-}
-```
-
-**Why each field matters for copy:**
-
-| Field | How it shapes copy |
-|-------|-------------------|
-| `industry` | Sets baseline competitive intensity and CPC expectations |
-| `services` | Determines headline categories and description angles |
-| `locations` | Geo-specific headlines get higher quality scores and CTR |
-| `brand_voice` | Tone, forbidden words, preferred language |
-| `differentiators` | These ARE the value prop headlines — the reason someone picks you |
-| `competitors` | Knowing who you're against sharpens positioning (without naming them in ads) |
-| `seasonality` | Tells you WHEN to push urgency copy vs. evergreen, which months to bid up |
-| `keyword_landscape` | High-intent terms go in headlines; competitive terms need sharper differentiation; long-tail = cheaper, more specific copy angles |
-| `social_proof` | Reviews, awards, years in business — trust signal headlines and descriptions |
-| `offers_or_promotions` | Time-sensitive copy angles, CTA variations |
-| `landing_pages` | Copy must match the page or conversions drop — know what's there |
-
-### Bootstrapping from existing data
-
-Before asking the user anything, try to fill fields from what's already available:
-
-- `mcp__adsagent__getAccountInfo` → business name, location hints
-- `mcp__adsagent__listCampaigns` → service categories, geo targeting
-- `mcp__adsagent__listAds` → current voice, headlines in use
-- `mcp__adsagent__getKeywords` → keyword landscape
-- `mcp__adsagent__getSearchTermReport` → real user language, long-tail opportunities
-- `mcp__adsagent__getImpressionShare` → competitive pressure signals
-
-Present what you found and ask the user to confirm/correct/fill gaps. This is faster and more accurate than starting from zero.
-
-## Workflow
-
-### 1. Understand the brief
-
-Detect or ask:
-- What product/service is this ad for?
-- Target audience or segment?
-- Which campaign/ad group? (pull with `mcp__adsagent__listCampaigns` → `mcp__adsagent__listAdGroups`)
-- Landing page URL?
-- Any geographic targeting?
-
-Cross-reference against the business context — if the user says "write copy for boarding" and context has boarding details, you already know the angles.
-
-### 2. Research what's working
-
-Pull data before writing — copy should be grounded in what converts, not guesses.
-
-**Current ad performance:**
-- `mcp__adsagent__listAds` — existing headlines/descriptions and their metrics
-- `mcp__adsagent__getKeywords` — active keywords
-- `mcp__adsagent__getSearchTermReport` — actual user queries (reveals real language and intent)
-- `mcp__adsagent__getCampaignPerformance` — CTR/conversion benchmarks to beat
-
-**Use seasonality context.** If business context shows peak months, factor that into copy urgency. During slow months, lean on evergreen value props. During peaks, lean on scarcity and timeliness.
-
-**Use keyword landscape context.** For competitive terms (high CPC, many bidders), copy must differentiate harder — lead with what's unique, not what everyone says. For long-tail terms, match the specific intent closely.
-
-**If the user has a database with lead/conversion data**, query it to find which keywords and messaging actually convert. The language paying customers use is the language your ads should mirror.
-
-### 3. Generate RSA components
-
-Google RSA: up to **15 headlines** (30 chars max) and **4 descriptions** (90 chars max). Google's AI mixes and matches them.
-
-**Always count characters. Flag any that exceed limits.**
-
-Generate 3-4 headlines per category:
-
-| Category | Purpose | Pin guidance |
-|----------|---------|-------------|
-| Product/Service + Location | Relevance, match search intent | **Pin to position 1** |
-| Value proposition | Why this business over competitors | Position 2 candidate |
-| Trust signals | Credibility (ratings, years, locations) | Any position |
-| Call to action | Drive the click | Position 3 candidate |
-
-Descriptions (one per angle):
-1. **Core value prop** + location specificity
-2. **Differentiator** + CTA
-3. **Trust signal** + social proof
-4. **Urgency** or seasonal angle
-
-### 4. Present variants
-
-Show 2-3 variants, each with a distinct messaging angle. Name the angle so it's clear what's being tested.
-
-```
-VARIANT A: "[Angle Name]"
- H1 [Pin 1]: [Service] in [Location] (XX chars)
- H2: [Value prop headline] (XX chars)
- H3: [CTA headline] (XX chars)
- D1: [Value prop description — max 90 chars]
- D2: [Trust/CTA description — max 90 chars]
-
-VARIANT B: "[Different Angle]"
- H1 [Pin 1]: ...
- ...
-```
-
-Always show character counts. Always show pin positions.
-
-### 5. Deploy
-
-After user approves a variant, push it live:
-
-- **New ad:** `mcp__adsagent__createAd` — create the RSA in the target ad group (created paused)
-- **Update existing:** `mcp__adsagent__updateAdAssets` — replace headlines/descriptions on a live ad
-- **Enable when ready:** `mcp__adsagent__enableAd`
-
-Always confirm before any write operation. Note the `changeId` returned — user can undo within 7 days via `mcp__adsagent__undoChange`.
-
-### 6. A/B test (if running one)
-
-1. **Identify the variable** — messaging angle, CTA style, emotional vs. practical
-2. **Deploy both variants** as separate ads in the same ad group (both paused, enable together)
-3. **Minimum run:** 2 weeks or 100 clicks per variant, whichever comes first
-4. **Success metric:** CTR for awareness campaigns, conversion rate for bottom-funnel
-
-### 7. Check results
-
-After the test period, pull results:
-
-```
-mcp__adsagent__listAds → compare metrics for each variant
-```
-
-| Variant | Impressions | Clicks | CTR | Conversions | Conv Rate | Winner? |
-|---------|------------|--------|-----|-------------|-----------|---------|
-| A | | | | | | |
-| B | | | | | | |
-
-**Interpret:**
-- Higher CTR + higher conversion rate → clear winner, pause the loser
-- Higher CTR + lower conversion rate → ad attracts clicks but landing page doesn't match the promise. Suggest `/ads-landing` to fix alignment
-- No statistical difference → need more volume or a bolder variant
-
-After deciding a winner: pause the loser with `mcp__adsagent__pauseAd`, keep the winner running.
-
-## Rules
-
-1. **Business context first.** Read `~/.adsagent/business-context.json` before doing anything. If it doesn't exist, build it.
-2. **Research before writing.** Always pull current performance data. Don't write copy in a vacuum.
-3. **Character limits are hard.** Count every headline (≤30) and description (≤90). No exceptions.
-4. **Never deploy without confirmation.** Show the exact copy, get a yes, then create/update.
-5. **Note changeIds.** Every write returns one. Tell the user they can undo within 7 days.
-6. **Ground copy in conversion data.** If conversion data is available, use the language that converts.
-7. **Seasonal awareness.** Check the business context for peak/slow months. Adjust urgency and messaging accordingly.
-8. **Defer to /ads for account management.** This skill writes copy and deploys ads. For bid/budget/keyword work, use `/ads`.
diff --git a/google-ads/ads/SKILL.md b/google-ads/ads/SKILL.md
deleted file mode 100644
index 9c3ae321..00000000
--- a/google-ads/ads/SKILL.md
+++ /dev/null
@@ -1,195 +0,0 @@
----
-name: ads
-description: Manage Google Ads campaigns — read performance, optimize keywords, adjust bids and budgets, add negatives, pause/enable campaigns, manage ads/ad groups, tracking templates, location targeting, network settings, rename campaigns/ad groups, bulk operations, and undo changes. Use this skill whenever the user mentions Google Ads, campaigns, keywords, ad spend, CPA, ROAS, search terms, negative keywords, bids, budgets, ads performance, location targeting, geo targeting, or campaign settings — even if they don't say "ads" explicitly.
-version: 2.0.0
-triggers:
- - google ads
- - campaigns
- - keywords
- - ad spend
- - CPA
- - ROAS
- - search terms
- - negative keywords
- - bid
- - budget
- - pause campaign
- - ads performance
- - location targeting
- - geo targeting
- - campaign settings
- - rename campaign
- - rename ad group
- - bulk keywords
----
-
-# AdsAgent — Google Ads Management
-
-Call Google Ads tools using the AdsAgent MCP server.
-
-## Configuration
-
-All persistent config lives in `~/.adsagent/config.json`. This file survives across sessions and works in every context — Claude Code, Claude Desktop, MCP servers, etc.
-
-The config file has this shape:
-
-```json
-{
- "apiKey": "asa_...",
- "accountId": "1234567890"
-}
-```
-
-## Onboarding
-
-Before doing anything else, check whether the user is set up. Follow these steps in order — stop at the first issue and resolve it before continuing.
-
-### Step 0: Check for the AdsAgent MCP server
-
-Try calling `mcp__adsagent__listConnectedAccounts`. If it responds, the MCP server is connected — skip to Step 1.
-
-If the tool doesn't exist, the MCP server isn't configured yet. Guide the user:
-
-> The AdsAgent MCP server isn't connected. To set it up:
->
-> 1. **Get a free token** at [adsagent.org](https://www.adsagent.org)
-> 2. **Add the MCP server** to your Claude settings (`mcpServers`):
->
-> ```json
-> {
-> "adsagent": {
-> "command": "npx",
-> "args": [
-> "-y", "mcp-remote",
-> "https://www.adsagent.org/api/mcp",
-> "--transport", "http-first",
-> "--header", "Authorization:Bearer YOUR_API_KEY"
-> ]
-> }
-> }
-> ```
->
-> Replace `YOUR_API_KEY` with the token from step 1.
->
-> 3. **Restart Claude** to pick up the new MCP server.
->
-> If you installed toprank via the setup script, re-run `./setup --api-key YOUR_KEY` to configure everything automatically.
-
-### Step 1: Check for token
-
-Read `~/.adsagent/config.json` (create `~/.adsagent/` if it doesn't exist).
-
-Look for `apiKey` (the token) in the config file. If it's present, skip to Step 2.
-
-If it's missing, tell the user:
-
-> To use AdsAgent, you need a free token. You can get one from [adsagent.org](https://www.adsagent.org).
-> Once you have it, paste it here and I'll save it for you.
-
-When the user provides the key, save it to `~/.adsagent/config.json`.
-
-Then continue to Step 2.
-
-### Step 2: Select a Google Ads account
-
-Look for `accountId` in the config file. If it's present, proceed to fulfil the user's request.
-
-If `accountId` is not set:
-
-1. Run `listConnectedAccounts` to get all connected Google Ads accounts.
-2. **If there is exactly one account**, save it automatically — no need to bother the user. Write `accountId` to `~/.adsagent/config.json` and tell the user which account was selected (show account name and ID).
-3. **If there are multiple accounts**, present them as a numbered list showing account name and ID, then ask the user to pick one. Save their choice to `~/.adsagent/config.json`.
-4. **If there are zero accounts**, tell the user they don't have any Google Ads accounts connected yet and direct them to [adsagent.org](https://www.adsagent.org) to connect one.
-
-### Switching accounts
-
-If the user wants to switch accounts, run `listConnectedAccounts`, let them pick, and update `accountId` in `~/.adsagent/config.json`.
-
-## Calling tools
-
-Call tools directly via the MCP server using the `mcp__adsagent__<toolName>` pattern. Read `~/.adsagent/config.json` first to get the `accountId`.
-
-**Examples:**
-
-```
-mcp__adsagent__listCampaigns(accountId: "1234567890")
-mcp__adsagent__getKeywords(accountId: "1234567890", campaignId: "111222333")
-mcp__adsagent__listConnectedAccounts()
-```
-
-Always pass `accountId` from `~/.adsagent/config.json` to every tool call (except `listConnectedAccounts`). All responses are JSON.
-
-## Available Tools
-
-### Read (safe, no side effects)
-- **getAccountInfo** — Account name, currency, timezone, test status
-- **listCampaigns** — All campaigns with impressions, clicks, cost, conversions
-- **getCampaignPerformance** — Daily metrics over a date range
-- **getKeywords** — Top keywords with quality scores
-- **getSearchTermReport** — Actual search queries triggering ads
-- **runGaqlQuery** — Run a custom read-only GAQL SELECT query (max 50 rows)
-- **getChanges** — Recent AdsAgent changes with `changeId`s for undo
-- **listConnectedAccounts** — All connected Google Ads accounts
-- **getTrackingTemplate** — Current tracking template at account/campaign/ad-group/ad level
-- **listAdGroups** — Ad groups in a campaign with metrics
-- **listAds** — Ads in a campaign/ad group with copy, URLs, status, metrics
-- **getImpressionShare** — Search/top/abs-top IS and budget/rank-lost IS
-- **getConversionActions** — Conversion actions and settings
-- **getAccountSettings** — Auto-tagging, tracking template, conversion tracking IDs
-- **getCampaignSettings** — Bidding, network, locations, schedule
-- **getNegativeKeywords** — List negative keywords for a campaign (check before adding new negatives to avoid duplicates)
-- **getRecommendations** — Google optimization recommendations
-
-### Write (mutates the account — always confirm with user first)
-All write tools return a `changeId` on success. Use this with `undoChange` to reverse the operation within 7 days.
-- **pauseKeyword** — Stop a keyword
-- **enableKeyword** — Re-enable a paused keyword
-- **addKeyword** — Add a new keyword to an ad group
-- **updateBid** — Change CPC bid (manual/enhanced CPC only, max 25% change)
-- **addNegativeKeyword** — Block irrelevant search terms (phrase match)
-- **removeNegativeKeyword** — Remove a negative keyword
-- **updateCampaignBudget** — Change daily budget (max 50% change)
-- **createCampaign** — Create a full paused search campaign
-- **pauseCampaign** — Pause all ads in a campaign
-- **enableCampaign** — Re-enable a paused campaign
-- **setTrackingTemplate** — Set/clear tracking template
-- **createAdGroup** — Create a new ad group
-- **createAd** — Create a new Responsive Search Ad
-- **pauseAd** — Pause an ad
-- **enableAd** — Re-enable an ad
-- **updateAdFinalUrl** — Change an ad's landing page URL
-- **updateAdAssets** — Replace an RSA's headlines/descriptions (complete replacement — provide every asset, not just changed ones; optionally pin assets to positions)
-- **bulkUpdateBids** — Update up to 50 keyword bids in one call (each capped at 25% change)
-- **bulkPauseKeywords** — Pause up to 100 keywords in one call (partial success possible)
-- **bulkAddKeywords** — Add up to 100 keywords to an ad group in one call (partial success possible)
-- **moveKeywords** — Move keywords between ad groups in the same campaign (adds to destination first, pauses source on success, rolls back on failure)
-- **renameCampaign** — Rename a campaign
-- **renameAdGroup** — Rename an ad group
-- **updateCampaignSettings** — Update network targeting (Google Search, Search Partners, Display Network) and/or location targeting (add/remove geo targets by geo target constant ID, e.g. '2840' for US, '200840' for Seattle-Tacoma DMA). Also supports negative location targeting (exclusions).
-- **undoChange** — Reverse a previous write by `changeId`
-
-## Rules
-
-1. **Never make write changes without explicit user confirmation.** Always show what you plan to change, the current value, and the new value before executing.
-2. **Start with reads.** When the user asks about ads, begin with `getAccountInfo` and `listCampaigns` to build context.
-3. **Show numbers clearly.** Format cost as dollars, show CTR as percentages, include date ranges.
-4. **Recommend before acting.** When you spot waste (high-spend zero-conversion keywords, irrelevant search terms), recommend the action and wait for approval.
-5. **Guardrails are server-side.** Bid changes >25% and budget changes >50% will be rejected by the server. Don't try to circumvent this.
-6. **After every write, note the `changeId`.** Tell the user they can undo the change within 7 days. Use `getChanges` to review recent operations.
-
-## Common Workflows
-
-### "How are my ads doing?"
-1. `getAccountInfo` → `listCampaigns` → summarize top spenders, best/worst performers, total spend
-
-### "Find wasted spend"
-1. `listCampaigns` → pick top-spend campaigns
-2. `getKeywords` for each → find high-spend, zero-conversion keywords
-3. `getSearchTermReport` → find irrelevant search terms
-4. Recommend: pause wasteful keywords + add negative keywords
-
-### "Optimize bids"
-1. `getKeywords` → find keywords with good conversion rates but low impression share
-2. `getImpressionShare` / `getCampaignSettings` as needed for context
-3. Recommend bid increases (within 25% limit) for high-performers
-4. Recommend bid decreases for underperformers
diff --git a/google-ads/ads/mcporter.json b/google-ads/ads/mcporter.json
deleted file mode 100644
index a83ee5ec..00000000
--- a/google-ads/ads/mcporter.json
+++ /dev/null
@@ -1,19 +0,0 @@
-{
- "mcpServers": {
- "google-ads": {
- "command": "npx",
- "args": [
- "-y",
- "mcp-remote",
- "https://www.adsagent.org/api/mcp",
- "--transport",
- "http-first",
- "--header",
- "Authorization:Bearer ${ADS_AGENT_KEY}"
- ],
- "env": {
- "ADS_AGENT_KEY": "${ADS_AGENT_KEY}"
- }
- }
- }
-}
diff --git a/requirements-test.txt b/requirements-test.txt
index df83eb78..0d6dfad8 100644
--- a/requirements-test.txt
+++ b/requirements-test.txt
@@ -1,3 +1,3 @@
-anthropic>=0.40.0
+google-genai>=1.0.0
pytest>=8.0.0
pytest-timeout>=2.3.0
diff --git a/setup b/setup
deleted file mode 100755
index 851ecc95..00000000
--- a/setup
+++ /dev/null
@@ -1,503 +0,0 @@
-#!/usr/bin/env python3
-"""
-toprank setup — register skills with Claude Code, Codex, and/or OpenClaw.
-
-Cross-platform (Windows, macOS, Linux).
-Usage: ./setup [--host claude|codex|openclaw|auto] [--skill NAME] [--api-key KEY]
-"""
-
-import argparse
-import json
-import os
-import platform
-import shutil
-import subprocess
-import sys
-import tempfile
-
-TOPRANK_DIR = os.path.dirname(os.path.abspath(__file__))
-TOPRANK_NAME = os.path.basename(TOPRANK_DIR)
-SKILLS_DIR = os.path.dirname(TOPRANK_DIR)
-
-# Subdirectories that contain skills (each subdir may hold multiple skill folders)
-SKILL_CATEGORIES = ["seo", "google-ads"]
-
-
-def parse_args():
- parser = argparse.ArgumentParser(description="Register toprank skills with your agent")
- parser.add_argument(
- "--host",
- choices=["claude", "codex", "openclaw", "auto"],
- default="auto",
- help="Target host (default: auto-detect)",
- )
- parser.add_argument(
- "--skill",
- default="",
- help="Only setup a single skill by name",
- )
- parser.add_argument(
- "--api-key",
- default="",
- help="API key for MCP server configuration",
- )
- return parser.parse_args()
-
-
-def make_bin_executable():
- bin_dir = os.path.join(TOPRANK_DIR, "bin")
- if not os.path.isdir(bin_dir):
- return
- if platform.system() == "Windows":
- return # Windows uses file associations, not executable bits
- for fname in os.listdir(bin_dir):
- fpath = os.path.join(bin_dir, fname)
- if os.path.isfile(fpath):
- try:
- os.chmod(fpath, os.stat(fpath).st_mode | 0o111)
- except OSError:
- pass
-
-
-def discover_skills():
- """Find all skills and return (name, relative_path) tuples.
-
- Scans category subdirectories (seo/, google-ads/) and the root for
- directories containing a SKILL.md file.
- """
- skills = []
-
- # Scan category subdirectories
- for category in SKILL_CATEGORIES:
- cat_dir = os.path.join(TOPRANK_DIR, category)
- if not os.path.isdir(cat_dir):
- continue
- for entry in sorted(os.listdir(cat_dir)):
- skill_dir = os.path.join(cat_dir, entry)
- if os.path.isdir(skill_dir) and os.path.isfile(os.path.join(skill_dir, "SKILL.md")):
- rel_path = os.path.join(category, entry)
- skills.append((entry, rel_path))
-
- # Scan root level (for toprank-upgrade and any other root-level skills)
- for entry in sorted(os.listdir(TOPRANK_DIR)):
- skill_dir = os.path.join(TOPRANK_DIR, entry)
- if entry in SKILL_CATEGORIES:
- continue # already scanned
- if os.path.isdir(skill_dir) and os.path.isfile(os.path.join(skill_dir, "SKILL.md")):
- skills.append((entry, entry))
-
- return skills
-
-
-def inject_preamble(skills):
- preamble_file = os.path.join(TOPRANK_DIR, "bin", "preamble.md")
- if not os.path.isfile(preamble_file):
- return []
-
- with open(preamble_file) as f:
- preamble = f.read()
-
- injected = []
- for skill_name, rel_path in skills:
- if skill_name in ("toprank-upgrade", "ads"):
- continue
- skill_path = os.path.join(TOPRANK_DIR, rel_path, "SKILL.md")
- if not os.path.isfile(skill_path):
- continue
- with open(skill_path) as f:
- content = f.read()
- if "toprank-update-check" in content:
- continue
-
- parts = content.split("---", 2)
- if len(parts) < 3:
- continue
-
- new_content = parts[0] + "---" + parts[1] + "---\n\n" + preamble + parts[2].lstrip("\n")
- skill_dir_path = os.path.dirname(skill_path)
- fd, tmp_path = tempfile.mkstemp(dir=skill_dir_path)
- try:
- with os.fdopen(fd, "w") as f:
- f.write(new_content)
- os.replace(tmp_path, skill_path)
- except Exception:
- try:
- os.unlink(tmp_path)
- except OSError:
- pass
- raise
- injected.append(skill_name)
-
- return injected
-
-
-def _symlink(src, dst):
- """Create symlink src->dst. Falls back to copy on Windows if symlinks fail."""
- if os.path.islink(dst):
- os.unlink(dst)
-
- try:
- os.symlink(src, dst)
- return "symlinked"
- except (OSError, NotImplementedError):
- full_src = src if os.path.isabs(src) else os.path.join(SKILLS_DIR, src)
- if platform.system() == "Windows":
- result = subprocess.run(
- ["cmd", "/c", "mklink", "/J", dst, full_src],
- capture_output=True,
- )
- if result.returncode == 0:
- return "junctioned"
- # Last resort: copy
- if os.path.isdir(full_src):
- shutil.copytree(full_src, dst)
- else:
- shutil.copy2(full_src, dst)
- return "copied"
-
-
-def setup_claude(skills):
- print("Claude Code:")
- linked = []
- for skill_name, rel_path in skills:
- src = os.path.join(TOPRANK_NAME, rel_path) # relative path for portability
- dst = os.path.join(SKILLS_DIR, skill_name)
-
- if os.path.exists(dst) and not os.path.islink(dst):
- print(f" skipped {skill_name} (real directory exists at {dst})")
- continue
-
- method = _symlink(src, dst)
- linked.append(f"{skill_name} ({method})")
-
- if linked:
- print(f" linked skills: {', '.join(linked)}")
- for skill_name, _ in skills:
- print(f" -> {os.path.join(SKILLS_DIR, skill_name)}")
- else:
- print(" no new skills to link")
-
-
-def setup_codex(skills):
- print("Codex:")
- try:
- result = subprocess.run(
- ["git", "rev-parse", "--show-toplevel"],
- capture_output=True, text=True, cwd=TOPRANK_DIR,
- )
- repo_root = result.stdout.strip() if result.returncode == 0 else ""
- except FileNotFoundError:
- repo_root = ""
-
- # If the git root IS the toprank directory itself, we're running from
- # within the toprank clone (e.g. ~/.claude/skills/toprank), not from a
- # user project. Fall back to ~/.codex/skills/ so Codex can find them.
- if repo_root and os.path.realpath(repo_root) == os.path.realpath(TOPRANK_DIR):
- repo_root = ""
-
- agents_dir = (
- os.path.join(repo_root, ".agents", "skills")
- if repo_root
- else os.path.join(os.path.expanduser("~"), ".codex", "skills")
- )
-
- linked = []
- for skill_name, rel_path in skills:
- codex_skill_name = f"toprank-{skill_name}"
- codex_dir = os.path.join(agents_dir, codex_skill_name)
- os.makedirs(os.path.join(codex_dir, "agents"), exist_ok=True)
-
- # Read description from frontmatter
- skill_md = os.path.join(TOPRANK_DIR, rel_path, "SKILL.md")
- desc = f"Toprank {skill_name} skill"
- if os.path.isfile(skill_md):
- with open(skill_md) as f:
- content = f.read()
- in_desc = False
- desc_lines = []
- for line in content.splitlines():
- if line.startswith("description:"):
- rest = line[len("description:"):].strip()
- if rest and rest != ">":
- desc = rest[:120]
- break
- in_desc = True
- elif in_desc:
- if line.startswith("---") or (line and not line.startswith(" ")):
- break
- desc_lines.append(line.strip())
- if desc_lines:
- desc = " ".join(desc_lines)[:120]
-
- yaml_path = os.path.join(codex_dir, "agents", "openai.yaml")
- with open(yaml_path, "w") as f:
- f.write(f"""interface:
- display_name: "toprank-{skill_name}"
- short_description: "{desc}"
- default_prompt: "Use toprank-{skill_name} for this task."
-policy:
- allow_implicit_invocation: true
-""")
-
- # Copy SKILL.md and asset directories (not symlink — Codex rejects external symlinks)
- for asset in ["SKILL.md", "scripts", "references"]:
- asset_src = os.path.join(TOPRANK_DIR, rel_path, asset)
- asset_dst = os.path.join(codex_dir, asset)
- if not os.path.exists(asset_src):
- continue
- if os.path.islink(asset_dst):
- os.unlink(asset_dst)
- if os.path.isdir(asset_src):
- if os.path.exists(asset_dst):
- shutil.rmtree(asset_dst)
- shutil.copytree(asset_src, asset_dst)
- else:
- shutil.copy2(asset_src, asset_dst)
-
- linked.append(codex_skill_name)
-
- if linked:
- print(f" linked skills: {', '.join(linked)}")
- for codex_skill_name in linked:
- print(f" -> {os.path.join(agents_dir, codex_skill_name)}")
- else:
- print(" no new skills to link")
-
-
-def setup_openclaw(skills):
- """OpenClaw rejects symlinks that resolve outside the skills root, so we copy."""
- print("OpenClaw:")
- openclaw_skills = os.path.join(os.path.expanduser("~"), ".openclaw", "workspace", "skills")
- os.makedirs(openclaw_skills, exist_ok=True)
-
- installed = []
- for skill_name, rel_path in skills:
- src = os.path.join(TOPRANK_DIR, rel_path)
- dst = os.path.join(openclaw_skills, skill_name)
- if os.path.islink(dst):
- os.unlink(dst)
- os.makedirs(dst, exist_ok=True)
- for entry in os.listdir(src):
- s = os.path.join(src, entry)
- d = os.path.join(dst, entry)
- if os.path.isdir(s):
- if os.path.exists(d):
- shutil.rmtree(d)
- shutil.copytree(s, d)
- else:
- shutil.copy2(s, d)
- installed.append(skill_name)
-
- if installed:
- print(f" installed skills: {', '.join(installed)}")
- for skill_name in installed:
- print(f" -> {os.path.join(openclaw_skills, skill_name)}")
- else:
- print(" no new skills to install")
-
-
-def detect_hosts(host_arg):
- install_claude = False
- install_codex = False
- install_openclaw = False
-
- if host_arg == "claude":
- install_claude = True
- elif host_arg == "codex":
- install_codex = True
- elif host_arg == "openclaw":
- install_openclaw = True
- else:
- claude_skills = os.path.join(".claude", "skills")
- if SKILLS_DIR.endswith(claude_skills) or SKILLS_DIR.replace("\\", "/").endswith(claude_skills):
- install_claude = True
- if shutil.which("codex"):
- install_codex = True
- openclaw_skills = os.path.join(".openclaw", "workspace", "skills")
- if SKILLS_DIR.endswith(openclaw_skills) or SKILLS_DIR.replace("\\", "/").endswith(openclaw_skills):
- install_openclaw = True
- if shutil.which("openclaw"):
- install_openclaw = True
- if not install_claude and not install_codex and not install_openclaw:
- install_claude = True
-
- return install_claude, install_codex, install_openclaw
-
-
-def setup_mcp(skills, api_key):
- """Configure AdsAgent MCP server in Claude Desktop settings."""
- has_ads = any(rel_path.replace("\\", "/").startswith("google-ads/") for _, rel_path in skills)
- if not has_ads:
- return
-
- key = api_key
- if not key:
- config_path = os.path.join(os.path.expanduser("~"), ".adsagent", "config.json")
- if os.path.isfile(config_path):
- try:
- with open(config_path) as f:
- key = json.load(f).get("apiKey", "")
- except Exception:
- pass
- if not key:
- return
-
- new_servers = {
- "adsagent": {
- "command": "npx",
- "args": [
- "-y",
- "mcp-remote",
- "https://www.adsagent.org/api/mcp",
- "--transport",
- "http-first",
- "--header",
- f"Authorization:Bearer {key}",
- ],
- }
- }
-
- print("MCP servers:")
- configs_written = []
-
- system = platform.system()
- if system == "Darwin":
- desktop_config = os.path.join(
- os.path.expanduser("~"), "Library", "Application Support", "Claude", "claude_desktop_config.json"
- )
- elif system == "Linux":
- desktop_config = os.path.join(
- os.path.expanduser("~"), ".config", "Claude", "claude_desktop_config.json"
- )
- elif system == "Windows":
- desktop_config = os.path.join(os.environ.get("APPDATA", ""), "Claude", "claude_desktop_config.json")
- else:
- desktop_config = ""
-
- if desktop_config:
- os.makedirs(os.path.dirname(desktop_config), exist_ok=True)
- config = {}
- if os.path.isfile(desktop_config):
- with open(desktop_config) as f:
- config = json.load(f)
- config.setdefault("mcpServers", {}).update(new_servers)
- with open(desktop_config, "w") as f:
- json.dump(config, f, indent=2)
- configs_written.append("Claude Desktop")
-
- if configs_written:
- print(f" configured: {', '.join(configs_written)}")
- for name in new_servers:
- print(f" + {name}")
-
-
-def prompt_google_ads_setup(skills):
- """Interactively set up Google Ads if the user wants it and stdin is a TTY."""
- has_ads = any(rel_path.replace("\\", "/").startswith("google-ads/") for _, rel_path in skills)
- if not has_ads:
- return ""
-
- # Check if API key already exists
- config_path = os.path.join(os.path.expanduser("~"), ".adsagent", "config.json")
- if os.path.isfile(config_path):
- try:
- with open(config_path) as f:
- existing_key = json.load(f).get("apiKey", "")
- if existing_key:
- return existing_key # Already configured
- except Exception:
- pass
-
- # Only prompt if stdin is a TTY (skip for piped installs)
- # TOPRANK_FORCE_INTERACTIVE=1 overrides the TTY check (for testing)
- if not sys.stdin.isatty() and not os.environ.get("TOPRANK_FORCE_INTERACTIVE"):
- return ""
-
- print()
- try:
- use_ads = input("Do you use Google Ads? (y/n): ").strip().lower()
- except (EOFError, KeyboardInterrupt):
- print()
- return ""
-
- if use_ads not in ("y", "yes"):
- return ""
-
- print()
- print(" Get your free API key at: https://www.adsagent.org")
- print()
- try:
- api_key = input(" Paste your API key: ").strip()
- except (EOFError, KeyboardInterrupt):
- print()
- return ""
-
- if not api_key:
- return ""
-
- # Save the key
- config_dir = os.path.join(os.path.expanduser("~"), ".adsagent")
- os.makedirs(config_dir, exist_ok=True)
- with open(os.path.join(config_dir, "config.json"), "w") as f:
- json.dump({"apiKey": api_key}, f)
- print(" saved to ~/.adsagent/config.json")
-
- return api_key
-
-
-def main():
- args = parse_args()
-
- print("toprank setup")
- print("─────────────")
- print()
-
- make_bin_executable()
-
- skills = discover_skills()
- if not skills:
- print(" no skills found")
- return
-
- if args.skill:
- match = [(name, rel) for name, rel in skills if name == args.skill]
- if not match:
- print(f" skill '{args.skill}' not found", file=sys.stderr)
- sys.exit(1)
- skills = match
-
- injected = inject_preamble(skills)
- if injected:
- print(f" injected preamble: {' '.join(injected)}")
-
- install_claude, install_codex, install_openclaw = detect_hosts(args.host)
-
- if install_claude:
- setup_claude(skills)
- if install_codex:
- setup_codex(skills)
- if install_openclaw:
- setup_openclaw(skills)
-
- # Google Ads API key: use --api-key flag, or prompt interactively
- api_key = args.api_key
- if api_key:
- config_dir = os.path.join(os.path.expanduser("~"), ".adsagent")
- os.makedirs(config_dir, exist_ok=True)
- with open(os.path.join(config_dir, "config.json"), "w") as f:
- json.dump({"apiKey": api_key}, f)
- print(" wrote ~/.adsagent/config.json")
- else:
- api_key = prompt_google_ads_setup(skills)
-
- setup_mcp(skills, api_key)
-
- seo_count = sum(1 for _, rel in skills if rel.startswith("seo/"))
- ads_count = sum(1 for _, rel in skills if rel.startswith("google-ads/"))
- print()
- print(f"Done. {seo_count} SEO skills and {ads_count} Google Ads skill(s) installed.")
- print(" Try: /seo-analysis or /ads")
-
-
-if __name__ == "__main__":
- main()
diff --git a/skills/ads-audit/SKILL.md b/skills/ads-audit/SKILL.md
new file mode 100644
index 00000000..c975060f
--- /dev/null
+++ b/skills/ads-audit/SKILL.md
@@ -0,0 +1,551 @@
+---
+name: ads-audit
+description: Google Ads account audit and business context setup. Run this first — it gathers business information, analyzes account health, and saves context that all other ads skills reuse. Trigger on "audit my ads", "ads audit", "set up my ads", "onboard", "account overview", "how's my account", "ads health check", "what should I fix in my ads", or when the user is new to AdsAgent and hasn't run an audit before. Also trigger proactively when other ads skills detect that business-context.json is missing.
+---
+
+## MCP Server Detection
+
+Before calling any Google Ads tool, detect which MCP server is available:
+
+1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
+2. If not found, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*` in the available tools
+3. If neither exists, guide the user:
+
+> No Google Ads MCP server detected. The easiest setup:
+>
+> 1. Get a free API key at [adsagent.org](https://www.adsagent.org)
+> 2. Set the environment variable: `export ADSAGENT_API_KEY=your_key`
+> 3. Restart Claude Code (the toprank plugin's .mcp.json will auto-configure the server)
+>
+> Or configure any Google Ads MCP server manually in your MCP settings.
+
+Use whichever MCP server's tool prefix is available for all subsequent calls in this session.
+
+# Google Ads Audit + Business Context Setup
+
+This is the starting point for any Google Ads account. It does two things:
+
+1. **Audits the account** — surfaces what's working, what's wasting money, and what to fix first
+2. **Builds business context** — gathers and saves business information to `~/.adsagent/business-context.json` so every other ads skill (copy, landing pages, competitive analysis) can use it without re-asking
+
+Run this before anything else. If another ads skill finds `business-context.json` missing, it should point the user here.
+
+## Setup
+
+Before anything else, verify the user has the AdsAgent MCP server connected and a token configured. Follow these steps in order — stop at the first issue and resolve it before continuing.
+
+### Step 1: Check for the AdsAgent MCP server
+
+Follow the **MCP Server Detection** section above. If no MCP server is found, guide the user through setup before proceeding. Wait for the user to complete setup before continuing.
+
+### Step 2: Check for token and account
+
+Read `~/.adsagent/config.json` for `apiKey` (the token) and `accountId`.
+
+- If `apiKey` is missing, ask the user for their token and save it as `apiKey` in `~/.adsagent/config.json`.
+- If `accountId` is missing, run `mcp__adsagent__listConnectedAccounts`:
+ - **One account** → save it automatically
+ - **Multiple accounts** → show list, ask user to pick
+ - **Zero accounts** → direct user to [adsagent.org](https://www.adsagent.org) to connect a Google Ads account
+
+## Reference Documents
+
+Read these reference documents during analysis for expert-level context:
+
+- `references/account-health-scoring.md` — Detailed scoring rubrics for each dimension (0-5 scale with specific criteria)
+- Read from ads skill: `../ads/references/industry-benchmarks.md` — Compare account metrics to industry averages
+- Read from ads skill: `../ads/references/quality-score-framework.md` — QS diagnostics and component-level analysis
+- Read from ads skill: `../ads/references/search-term-analysis-guide.md` — Search term relevance scoring methodology
+- Read from ads skill: `../ads/references/campaign-structure-guide.md` — Account structure best practices
+
+Read these before starting Phase 2 analysis. They contain the numeric thresholds that separate a generic audit from an expert one.
+
+## Phase 1: Pull Account Data
+
+Gather everything in parallel before asking the user a single question. The goal is to show up informed.
+
+**Pull all data calls simultaneously to minimize wait time. Use parallel tool calls — every call below is independent and can run at the same time.**
+
+**Account basics:**
+- `mcp__adsagent__getAccountInfo` — business name, currency, timezone
+- `mcp__adsagent__getAccountSettings` — auto-tagging, tracking template, conversion setup
+
+**Campaign structure:**
+- `mcp__adsagent__listCampaigns` — all campaigns with spend, clicks, conversions
+- `mcp__adsagent__listAdGroups` — ad groups per campaign (focus on top-spend campaigns)
+
+**Performance data:**
+- `mcp__adsagent__getCampaignPerformance` — daily trends for the last 30 days
+- `mcp__adsagent__getKeywords` — top keywords with quality scores, bids, conversions
+- `mcp__adsagent__getSearchTermReport` — actual search queries triggering ads
+- `mcp__adsagent__getImpressionShare` — search IS, top IS, budget-lost IS, rank-lost IS
+
+**Ads and conversions:**
+- `mcp__adsagent__listAds` — ad copy, status, and per-ad metrics
+- `mcp__adsagent__getConversionActions` — what conversions are set up and how they're configured
+- `mcp__adsagent__getNegativeKeywords` — existing negative keyword coverage
+
+**Recommendations:**
+- `mcp__adsagent__getRecommendations` — Google's optimization suggestions (evaluate critically, don't blindly follow)
+
+**Minimum data for a meaningful audit:** `listCampaigns`, `getKeywords`, and `getImpressionShare` must return data. If the account has zero campaigns or zero spend, skip to Phase 3 (business context) — there's nothing to audit yet, but the context is still valuable for account setup.
+
+## Phase 2: Analyze and Score
+
+Work through each dimension. For each one, assign a numeric score (0-5) and a status label.
+
+### Scoring Framework
+
+Read `references/account-health-scoring.md` for the detailed rubric per dimension. Use this summary for quick reference:
+
+**Score definitions:**
+
+| Score | Label | Meaning |
+|-------|-------|---------|
+| 0 | Critical | Broken or missing entirely — actively losing money |
+| 1 | Poor | Major problems — significant waste or missed opportunity |
+| 2 | Needs Work | Below acceptable — several clear issues to fix |
+| 3 | Acceptable | Functional but room for meaningful improvement |
+| 4 | Good | Well-managed with minor optimization opportunities |
+| 5 | Excellent | Best-practice level — maintain and scale |
+
+**Overall Health Score:** Sum all 7 dimension scores, multiply by (100/35), round to nearest integer. This gives a 0-100 score.
+
+| Overall Score | Label | Summary |
+|---------------|-------|---------|
+| 0-25 | Critical | Account has fundamental problems. Stop spending until fixed |
+| 26-50 | Needs Work | Significant waste. Focus on top 3 issues before scaling |
+| 51-75 | OK | Functional but leaving money on the table |
+| 76-90 | Strong | Well-managed. Focus on scaling and marginal gains |
+| 91-100 | Excellent | Top-tier account. Maintain and test incrementally |
+
+### Account Health Dimensions
+
+**1. Conversion tracking** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No conversion actions set up. Spending blind |
+| 1 | Conversion actions exist but aren't firing (0 conversions recorded despite clicks) |
+| 2 | Conversions tracked but auto-tagging disabled, or using only micro-conversions (page views, not leads/sales) |
+| 3 | Primary conversion action firing, auto-tagging on, but multiple conversion actions counting duplicates or no value assigned |
+| 4 | Clean conversion setup: primary action firing, auto-tagging on, values assigned, no duplicate counting |
+| 5 | Full setup: primary + secondary actions, proper attribution window, enhanced conversions or offline conversion import |
+
+- Red flag: spending money with no conversion tracking = flying blind. Score 0-1 is a STOP condition — recommend pausing spend until tracking is fixed
+- Check: is auto-tagging enabled? If not, Google Analytics integration breaks
+- Check: are conversion actions using "Every" or "One" counting? Lead gen should use "One", e-commerce should use "Every"
+
+**2. Campaign structure** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Single campaign with one ad group containing 50+ unrelated keywords |
+| 1 | Some structure but ad groups have 30+ keywords with mixed intent (e.g., "plumber" and "plumbing school" in same group) |
+| 2 | Campaigns exist per service/product but ad groups are too broad (15-30 keywords of mixed theme) |
+| 3 | Campaigns per service, ad groups by theme (5-20 keywords), but missing brand campaign separation or geo structure |
+| 4 | Clean structure: brand separated, services split, tight ad groups, appropriate geo targeting |
+| 5 | Optimal: brand/non-brand split, service campaigns, geo-specific where relevant, ad groups of 5-15 tightly themed keywords, negative keyword lists at appropriate levels |
+
+- Red flag: one ad group with 200 keywords = poor relevance, QS will suffer
+- Check: are brand and non-brand keywords in separate campaigns? Mixing them inflates brand CTR and hides non-brand problems
+- Check: for multi-location businesses, is there geo-specific structure?
+- Reference `../ads/references/campaign-structure-guide.md` for the ideal structure patterns
+
+**3. Keyword health** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No keywords with conversions. Average QS < 3. >50% of keywords are zombies (0 impressions 30+ days) |
+| 1 | Average QS 3-4. >30% of spend on non-converting keywords. Heavy use of broad match without negatives |
+| 2 | Average QS 4-5. 20-30% of spend on non-converting keywords. Some match type issues |
+| 3 | Average QS 5-6. 10-20% wasted spend. Reasonable match type mix but gaps in negative coverage |
+| 4 | Average QS 6-7. <10% wasted spend. Good match type strategy. Solid negative keyword lists |
+| 5 | Average QS 7+. <5% wasted spend. Tight match types. Comprehensive negatives. Regular search term mining |
+
+- Calculate: what % of total keyword spend goes to keywords with 0 conversions and >10 clicks? This is your keyword waste rate
+- Calculate: average QS weighted by spend (not by keyword count — a QS-3 keyword spending $2,000/month matters more than a QS-3 keyword spending $5/month)
+- Check for zombie keywords: 0 impressions for 30+ days. These clutter the account and should be paused
+
+**4. Search term quality** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | >40% of search terms are irrelevant. No negative keywords in place |
+| 1 | 30-40% irrelevant terms. Minimal negative keyword coverage |
+| 2 | 20-30% irrelevant terms. Some negatives but obvious gaps |
+| 3 | 10-20% irrelevant terms. Decent negative coverage. Some converting terms not yet added as keywords |
+| 4 | <10% irrelevant terms. Good negative lists. Most high-converting terms already added as keywords |
+| 5 | <5% irrelevant terms. Comprehensive negative lists at account and campaign level. Active search term mining program |
+
+- Score search term relevance using the methodology in `../ads/references/search-term-analysis-guide.md`
+- Calculate: spend on irrelevant search terms (relevance score < 2) as % of total spend
+- Flag converting search terms (2+ conversions) not yet added as keywords — these are free money
+- Flag obvious negative keyword gaps: competitor names, "free" variants, "jobs"/"careers" variants, wrong service types
+
+**5. Ad copy** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No active ads, or only legacy expanded text ads (no RSAs) |
+| 1 | RSAs exist but only 1 per ad group. Headline/description variety is poor (repetitive messaging) |
+| 2 | 1-2 RSAs per ad group. Some variety but headlines don't include keywords or location |
+| 3 | 2+ RSAs per major ad group. Headlines include keywords. Pinning used on H1. Some CTR variation suggests testing is happening |
+| 4 | 2-3 RSAs per ad group with distinct messaging angles. Good headline variety (service, value prop, trust, CTA). CTR above industry average |
+| 5 | Active A/B testing program. Multiple RSAs with measurably different angles. Regular losers paused, winners iterated. CTR consistently above benchmark |
+
+- Count RSAs per ad group: <2 means no testing is possible
+- Check headline diversity: are the 15 headlines actually different, or are they minor variations of the same message?
+- Check if keywords appear in headlines (direct QS and relevance impact)
+- Check pin strategy: H1 should typically be pinned to the most relevant service+location headline
+- Identify ad groups with CTR below industry benchmark — these need copy refresh
+
+**6. Impression share** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | Search IS < 20%. Missing >80% of potential traffic |
+| 1 | Search IS 20-35%. Budget-lost IS > 40% OR rank-lost IS > 60% |
+| 2 | Search IS 35-50%. Significant losses from both budget and rank |
+| 3 | Search IS 50-65%. Moderate losses — budget-lost IS < 25% and rank-lost IS < 40% |
+| 4 | Search IS 65-80%. Losses primarily from rank (fixable with QS improvements) |
+| 5 | Search IS > 80%. Brand campaign IS > 95%. Losses are marginal and strategic (intentionally not competing on some queries) |
+
+Use the Impression Share Interpretation Matrix to diagnose the root cause:
+
+| | Rank-Lost IS < 30% | Rank-Lost IS 30-50% | Rank-Lost IS > 50% |
+|---|---|---|---|
+| **Budget-Lost IS < 20%** | Healthy — optimize at margins | QS/Bid Problem — improve ads, landing pages, or raise bids on high-QS keywords | Quality Crisis — QS is the bottleneck. Fix ad relevance and landing page experience before spending more |
+| **Budget-Lost IS 20-40%** | Budget Problem — increase budget or narrow targeting. Check if the campaign is profitable enough to justify more spend | Mixed Problem — fix quality first (cheaper than adding budget), then reassess | Structural Problem — bidding on too-competitive keywords. Shift to long-tail and exact match |
+| **Budget-Lost IS > 40%** | Severe Budget Gap — if CPA is good, this is the highest-ROI fix in the account. Double budget or cut keyword count by 50% | Priority: fix rank issues to get more from existing budget, then add budget | Fundamental Misalignment — pause, restructure, then restart. Current approach is burning money |
+
+**7. Spend efficiency** (Score 0-5)
+
+| Score | Criteria |
+|-------|----------|
+| 0 | No conversion data available. Flying blind on efficiency |
+| 1 | CPA > 200% of industry average. >40% of spend on non-converting entities |
+| 2 | CPA 150-200% of industry avg. 25-40% wasted spend. Major budget misallocation between campaigns |
+| 3 | CPA 100-150% of industry avg. 15-25% wasted spend. Some misallocation |
+| 4 | CPA within industry norms. <15% wasted spend. Budget roughly proportional to conversion share per campaign |
+| 5 | CPA below industry avg. <5% wasted spend. Budget allocation optimized — each campaign's budget share matches its conversion share |
+
+- Calculate: % of spend going to converting keywords vs non-converting
+- Calculate: per-campaign CPA and compare to account average. Flag any campaign with CPA > 150% of account avg
+- Calculate: budget allocation efficiency — does each campaign's % of total budget match its % of total conversions?
+- If one campaign gets 60% of budget but delivers only 30% of conversions, that's a $X reallocation opportunity
+
+### Wasted Spend Deep Dive
+
+Calculate wasted spend using this formula (same as `/ads` skill for consistency):
+
+```
+WASTED SPEND =
+ Keyword Waste:
+ Sum of spend on keywords where (conversions = 0 AND clicks > 10)
+ + Search Term Waste:
+ Sum of spend on search terms where relevance_score < 2
+ (use the 1-5 relevance scoring from ../ads/references/search-term-analysis-guide.md)
+ + Structural Waste:
+ Spend on campaigns with Display Network enabled where display clicks > 20 AND display conversions = 0
+```
+
+Express as:
+1. Dollar amount (30 days)
+2. Percentage of total spend
+3. Annualized projection
+4. Breakdown by category with specific keywords/terms named
+
+## Phase 2.5: Persona Discovery
+
+Discover 2-3 customer personas from the ad data. This runs in parallel with Phase 3 (business context questions) — it uses only the data already pulled in Phase 1.
+
+### Data Sources for Persona Construction
+
+| Source | What it reveals | How to access |
+|--------|----------------|---------------|
+| Search terms | What customers actually search for — their language, pain points, urgency | `getSearchTermReport` from Phase 1 |
+| Converting keywords | What they buy — the terms that lead to conversions reveal purchase intent | `getKeywords` filtered to converting |
+| Ad group themes | How the business segments its services — each theme may serve a different persona | `listAdGroups` from Phase 1 |
+| Landing page URLs | Where they land — different pages suggest different customer journeys | `listAds` final URLs from Phase 1 |
+| Geographic data | Where they are — metro vs rural, specific cities | `getCampaignSettings` location targets |
+| Device split | How they search — mobile-heavy suggests on-the-go/urgent need | Infer from ad performance patterns |
+| Time-of-day patterns | When they search — business hours vs evenings vs weekends | `getCampaignPerformance` daily data |
+
+### Persona Template
+
+For each discovered persona:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **Name** | Descriptive label capturing their defining trait | "The Emergency Caller" |
+| **Demographics** | Role, context, location type | Homeowner, suburban, dual-income household |
+| **Primary goal** | What they're trying to accomplish RIGHT NOW | Fix a burst pipe before it damages the floor |
+| **Pain points** | What's driving them to search | Can't wait for regular business hours. Worried about cost. Doesn't know who to trust |
+| **Search language** | Actual search terms from the data that this persona uses | "emergency plumber near me", "plumber open now", "burst pipe repair cost" |
+| **Decision trigger** | What makes them click the ad and convert | Seeing "24/7" and "Same Day" in the headline. Phone number in the ad. Reviews mentioned |
+| **Value to business** | Estimated revenue or conversion value | High urgency = willing to pay premium. Avg ticket $350-800 |
+
+### Derivation Rules
+
+- Each persona MUST be grounded in actual search term clusters from the data. If you can't point to 5+ search terms that this persona would use, the persona is speculative — drop it
+- If all search terms look the same (single-intent account), identify 1-2 personas max. Don't force 3
+- Name personas by their dominant behavior, not demographics: "The Comparison Shopper" is more useful than "Female 35-44"
+- Include the actual search terms from the data that map to each persona — this directly informs ad copy decisions
+
+### Persist Personas
+
+Save to `~/.adsagent/personas/{accountId}.json`:
+
+```json
+{
+ "account_id": "1234567890",
+ "saved_at": "2024-01-15T10:30:00Z",
+ "personas": [
+ {
+ "name": "The Emergency Caller",
+ "demographics": "Homeowner, suburban, any age",
+ "primary_goal": "Fix an urgent problem right now",
+ "pain_points": ["Can't wait", "Worried about cost", "Doesn't know who's reliable"],
+ "search_terms": ["emergency plumber near me", "plumber open now", "burst pipe repair"],
+ "decision_trigger": "24/7 availability, phone number visible, reviews",
+ "value": "High — willing to pay premium for urgency"
+ }
+ ]
+}
+```
+
+These personas feed directly into `/ads-copy` for headline generation and `/ads` for keyword strategy.
+
+## Phase 3: Build Business Context
+
+Now that you understand the account, fill in the business context. Pull as much as possible from the data you already have — only ask the user for what you can't infer.
+
+### What to infer from account data
+
+| Field | Source |
+|-------|--------|
+| `business_name` | `getAccountInfo` |
+| `services` | Campaign and ad group names, keyword themes |
+| `locations` | Campaign geo-targeting, location extensions |
+| `brand_voice` | Existing ad copy tone and word choices |
+| `keyword_landscape.high_intent_terms` | Top-converting keywords |
+| `keyword_landscape.competitive_terms` | Low impression share keywords with high CPC |
+| `keyword_landscape.long_tail_opportunities` | Converting search terms not yet added as keywords |
+
+### What to ask the user
+
+Present what you inferred, then ask for what's missing. Frame it conversationally, not as a checklist.
+
+**Always ask:**
+- "What makes you different from competitors?" → `differentiators`
+- "Who are your main competitors?" → `competitors`
+- "Is your business seasonal? When's your busiest time?" → `seasonality`
+- "What's your website URL?" → for landing page context
+
+**Ask if not obvious from data:**
+- Industry (if campaign names don't make it clear)
+- Target audience (if search terms don't reveal it)
+- Current offers or promotions
+- Social proof (reviews, awards, years in business)
+
+### Website analysis
+
+If the user provides their website URL (or it's visible in ad final URLs):
+
+- Note the URL in `landing_pages`
+- Look at what the ads link to — do headlines match landing page content?
+- Note any offers, trust signals, or CTAs visible on the site that could inform ad copy
+
+### Save the context
+
+Write the complete business context to `~/.adsagent/business-context.json`:
+
+```json
+{
+ "business_name": "",
+ "industry": "",
+ "website": "",
+ "services": [],
+ "locations": [],
+ "target_audience": "",
+ "brand_voice": {
+ "tone": "",
+ "words_to_avoid": [],
+ "words_to_use": []
+ },
+ "differentiators": [],
+ "competitors": [],
+ "seasonality": {
+ "peak_months": [],
+ "slow_months": [],
+ "seasonal_hooks": []
+ },
+ "keyword_landscape": {
+ "high_intent_terms": [],
+ "competitive_terms": [],
+ "long_tail_opportunities": []
+ },
+ "social_proof": [],
+ "offers_or_promotions": [],
+ "landing_pages": {},
+ "notes": "",
+ "audit_date": "",
+ "account_id": ""
+}
+```
+
+Include `audit_date` (today's date) and `account_id` so future skills know when this was last refreshed.
+
+## Phase 4: Deliver the Audit Report
+
+Present findings as a concise, actionable report. No fluff — every line should either inform a decision or recommend an action.
+
+### Report format
+
+```
+# Google Ads Audit: [Business Name]
+**Account:** [ID] | **Period:** Last 30 days | **Date:** [today]
+
+## Scorecard
+| Dimension | Score (0-5) | Status | Key Finding |
+|----------------------|-------------|-----------|--------------------------------------|
+| Conversion tracking | X | [label] | [one line — the most important fact] |
+| Campaign structure | X | [label] | [one line] |
+| Keyword health | X | [label] | [one line] |
+| Search term quality | X | [label] | [one line] |
+| Ad copy | X | [label] | [one line] |
+| Impression share | X | [label] | [one line] |
+| Spend efficiency | X | [label] | [one line] |
+
+## Overall Health: [0-100] — [Critical / Needs Work / OK / Strong / Excellent]
+
+## Key Numbers
+- **Total spend (30d):** $X,XXX
+- **Conversions:** XX at $XX.XX CPA
+- **Top campaign:** [name] — XX% of spend, XX% of conversions
+- **Wasted spend (30d):** $X,XXX (XX% of total)
+- **Annualized waste:** ~$XX,XXX
+
+## Wasted Spend Analysis
+**Total wasted spend (30d):** $X,XXX (XX% of total spend)
+- Non-converting keywords: $X,XXX across N keywords
+ - [keyword 1]: $XXX spent, XX clicks, 0 conversions — [diagnosis]
+ - [keyword 2]: $XXX spent, XX clicks, 0 conversions — [diagnosis]
+ - ... (top 5 by spend)
+- Irrelevant search terms: ~$X,XXX estimated
+ - [term 1]: $XXX, XX clicks — [why it's irrelevant]
+ - [term 2]: $XXX, XX clicks — [why it's irrelevant]
+ - ... (top 5 by spend)
+- Display/structural waste: $XXX (if applicable)
+
+## Impression Share Analysis
+**Current Search IS:** XX% | **Budget-Lost:** XX% | **Rank-Lost:** XX%
+
+[Use the 2x2 matrix interpretation to diagnose]
+
+Diagnosis: [e.g., "This is primarily a budget problem — the campaign runs out of budget by 2pm daily.
+Increasing budget 30% would capture an estimated X additional conversions at similar CPA."]
+
+## Personas Discovered
+| Persona | Searches like... | Converts on... | Value |
+|---------|-----------------|----------------|-------|
+| [name] | [2-3 example search terms] | [converting keywords/services] | [high/med/low + why] |
+
+Personas saved to `~/.adsagent/personas/{accountId}.json` — used by `/ads-copy` for headline generation.
+
+## Top 3 Actions (do these first)
+1. **[Action]** — [why, expected impact in dollars or conversions]
+2. **[Action]** — [why, expected impact]
+3. **[Action]** — [why, expected impact]
+
+## Detailed Findings
+[Organized by dimension — only include dimensions that scored 0-3.
+For each, state the problem, show the data, recommend the fix.]
+
+### [Dimension Name] — Score X/5
+**Problem:** [specific issue with numbers]
+**Data:** [the evidence]
+**Fix:** [specific action, which tool/skill to use]
+**Impact:** [estimated improvement in dollars or conversions]
+
+## Business Context Saved
+Saved to `~/.adsagent/business-context.json` — other ads skills
+(/ads-copy, /ads-landing, /ads-compete) will use this automatically.
+[List any fields that are incomplete and need user input later.]
+```
+
+### What makes a good action item
+
+- **Specific:** "Pause keyword 'free dog food' — $847 spent, 0 conversions" not "Review underperforming keywords"
+- **Quantified:** Include the spend, impressions, or conversions at stake
+- **Prioritized:** Highest-impact items first. Stopping waste > starting new things
+- **Actionable with /ads:** Every recommendation should be something the user can execute immediately using the `/ads` skill
+- **Dollar-denominated:** Whenever possible, express impact as "save $X/month" or "gain X conversions/month at $Y CPA"
+
+### Scoring thresholds for action priority
+
+| Overall Score | Recommended Next Step |
+|---------------|----------------------|
+| 0-25 | "Your account has critical issues. I'd recommend pausing spend on the worst campaigns and fixing conversion tracking and structure before resuming." |
+| 26-50 | "There's significant waste to eliminate. Let's fix the top 3 issues — I estimate that saves $X/month. Run `/ads` to execute." |
+| 51-75 | "The account is functional but leaving money on the table. The optimizations below could improve CPA by 15-30%." |
+| 76-100 | "This is a well-managed account. The suggestions below are marginal improvements — focus on scaling what's working." |
+
+## Conditional Handoffs
+
+After delivering the report, proactively offer the right next step based on what the audit found.
+
+### Ad Copy Issues
+
+If ad copy scored 0-2 (low CTR, low headline variety, few RSAs per ad group):
+
+> "Your ad copy needs work — [N] ad groups have CTR below [X]% (industry average is [Y]%). Run `/ads-copy` to generate better RSA variants with A/B testing. It'll use the business context I just saved."
+
+### Impression Share / Bid Issues
+
+If impression share scored 0-2 (high budget-lost or rank-lost IS):
+
+> "You're losing [X]% of potential traffic to [budget/rank]. Run `/ads` to optimize bids on your best keywords — I estimate [N] additional conversions/month are available."
+
+### Keyword Gaps
+
+If search term analysis found 3+ converting terms not yet added as keywords:
+
+> "I found [N] search terms converting that aren't keywords yet. Want me to add them now via `/ads`? Here they are:
+> | Term | Conversions | CPA | Recommended Match Type |"
+
+### Waste Elimination
+
+If wasted spend > 15% of total:
+
+> "You're wasting ~$[X]/month ([Y]% of spend). Want me to pause the non-converting keywords and add the negative keywords? I'll show each change before making it. Run `/ads` to execute."
+
+### Landing Page Problems
+
+If CTR is healthy (>3%) but conversion rate is below 2% across multiple ad groups:
+
+> "Your ads get clicks but conversions are low — the landing pages likely don't match the ad promise. Run `/ads-landing` to audit keyword-to-landing-page alignment."
+
+### Competitive Intelligence
+
+If impression share is declining or the user asks about competitors:
+
+> "Run `/ads-compete` to monitor your competitive landscape — see who's bidding on your terms and how your share is trending."
+
+### Always Offer
+
+At the end of every audit:
+
+> "Run `/ads` to execute any of these recommendations. I've saved your business context and personas — all ads skills will use them automatically."
+
+## Rules
+
+1. **Data first, questions second.** Pull all account data before asking the user anything. Show up informed.
+2. **Infer before asking.** Don't ask "what industry are you in?" if the campaigns clearly say "plumbing services."
+3. **Be specific.** Name the campaigns, keywords, and dollar amounts. Vague advice is useless.
+4. **Prioritize by money.** The biggest waste or biggest opportunity comes first.
+5. **Save the context.** Always write `business-context.json` — this is the handoff to every other ads skill.
+6. **Don't fix things here.** This skill diagnoses and recommends. The user executes fixes with `/ads`. Offer to switch to `/ads` for implementation.
+7. **Score everything.** Every dimension gets a 0-5 score. The overall health score gives the user a single number to track over time. Re-auditing in 30 days should show improvement.
+8. **Name names.** Every finding should reference specific campaigns, keywords, ad groups, or search terms. "Some keywords are underperforming" is not an audit finding — "$423 spent on 'free plumbing advice' with 0 conversions" is.
diff --git a/skills/ads-audit/evals/evals.json b/skills/ads-audit/evals/evals.json
new file mode 100644
index 00000000..ed1182c6
--- /dev/null
+++ b/skills/ads-audit/evals/evals.json
@@ -0,0 +1,35 @@
+{
+ "skill_name": "ads-audit",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Run a full audit of my Google Ads account. Here's the data:\n\n```json\n{\"account\": {\"name\": \"Bay Area Dog Resort\", \"id\": \"9876543210\", \"currency\": \"USD\", \"timezone\": \"America/Los_Angeles\", \"auto_tagging\": true},\n\"campaigns\": [{\"name\": \"Brand\", \"spend\": 800, \"clicks\": 420, \"impressions\": 5200, \"conversions\": 38, \"cpa\": 21.05, \"ctr\": 8.1, \"budget_lost_is\": 5, \"rank_lost_is\": 10}, {\"name\": \"Dog Boarding\", \"spend\": 3200, \"clicks\": 580, \"impressions\": 14000, \"conversions\": 22, \"cpa\": 145.45, \"ctr\": 4.1, \"budget_lost_is\": 35, \"rank_lost_is\": 25}, {\"name\": \"Dog Grooming\", \"spend\": 1500, \"clicks\": 390, \"impressions\": 8800, \"conversions\": 28, \"cpa\": 53.57, \"ctr\": 4.4, \"budget_lost_is\": 12, \"rank_lost_is\": 15}],\n\"keywords\": [{\"campaign\": \"Dog Boarding\", \"keyword\": \"dog boarding near me\", \"spend\": 1100, \"clicks\": 180, \"conversions\": 12, \"qs\": 7}, {\"keyword\": \"luxury dog hotel\", \"campaign\": \"Dog Boarding\", \"spend\": 900, \"clicks\": 120, \"conversions\": 2, \"qs\": 4}, {\"keyword\": \"cheap dog boarding\", \"campaign\": \"Dog Boarding\", \"spend\": 650, \"clicks\": 140, \"conversions\": 0, \"qs\": 3}, {\"keyword\": \"dog kennel jobs\", \"campaign\": \"Dog Boarding\", \"spend\": 280, \"clicks\": 65, \"conversions\": 0, \"qs\": 2}, {\"keyword\": \"dog grooming san francisco\", \"campaign\": \"Dog Grooming\", \"spend\": 800, \"clicks\": 210, \"conversions\": 20, \"qs\": 9}],\n\"conversion_actions\": [{\"name\": \"Phone Call\", \"type\": \"PHONE_CALL\", \"status\": \"ENABLED\"}, {\"name\": \"Form Submit\", \"type\": \"WEBPAGE\", \"status\": \"ENABLED\"}],\n\"search_terms\": [{\"term\": \"dog boarding san francisco\", \"clicks\": 45, \"conversions\": 8, \"spend\": 270}, {\"term\": \"how to start a dog boarding business\", \"clicks\": 32, \"conversions\": 0, \"spend\": 190}, {\"term\": \"dog boarding prices\", \"clicks\": 28, \"conversions\": 3, \"spend\": 140}],\n\"ads_per_group\": {\"Dog Boarding - General\": 1, \"Dog Grooming - SF\": 3}}\n```",
+ "expected_output": "A comprehensive audit with a scorecard covering all 7 dimensions. Should identify: Dog Boarding campaign has 35% budget-lost IS (severe constraint) AND 25% rank-lost IS (both dimensions problematic). 'cheap dog boarding' and 'dog kennel jobs' are waste ($930 combined, 0 conversions). 'luxury dog hotel' has QS 4 and poor CPA. Dog Boarding ad group has only 1 RSA (needs more). Conversion tracking exists but is basic (no enhanced conversions). Should recommend adding 'dog boarding san francisco' as keyword (8 conversions). Should flag 'how to start a dog boarding business' as negative.",
+ "files": [],
+ "expectations": [
+ "Produces a scorecard table with all 7 health dimensions scored",
+ "Calculates an overall health score (numeric)",
+ "Identifies Dog Boarding campaign's impression share problem using the 2x2 matrix (budget-lost 35% + rank-lost 25%)",
+ "Identifies 'cheap dog boarding' ($650, 0 conv) and 'dog kennel jobs' ($280, 0 conv) as wasted spend with specific dollar amounts",
+ "Flags 'luxury dog hotel' QS 4 as needing quality improvement",
+ "Notes Dog Boarding ad group has only 1 RSA and recommends adding more",
+ "Recommends adding 'dog boarding san francisco' as a keyword (8 conversions from search terms)",
+ "Recommends adding 'how to start a dog boarding business' as a negative keyword",
+ "Top 3 actions section is present with dollar amounts and expected impact"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Audit my Google Ads account. Here's the data:\n\n```json\n{\"account\": {\"name\": \"Quick Print Co\", \"id\": \"1112223334\", \"currency\": \"USD\"},\n\"campaigns\": [{\"name\": \"All Services\", \"spend\": 2500, \"clicks\": 800, \"impressions\": 20000, \"conversions\": 0, \"cpa\": null, \"ctr\": 4.0}],\n\"conversion_actions\": [],\n\"keywords\": [{\"keyword\": \"printing services\", \"spend\": 800, \"clicks\": 260, \"conversions\": 0, \"qs\": 5}, {\"keyword\": \"business cards\", \"spend\": 600, \"clicks\": 200, \"conversions\": 0, \"qs\": 6}]}\n```",
+ "expected_output": "The audit should immediately flag that conversion tracking is completely missing (no conversion actions at all). This should be rated Critical (score 0) on the conversion tracking dimension. The entire $2500 in spend cannot be evaluated for ROI. The #1 recommendation must be to set up conversion tracking before any other optimization.",
+ "files": [],
+ "expectations": [
+ "Flags missing conversion tracking as the #1 critical issue",
+ "Scores conversion tracking dimension as 0 or Critical",
+ "States that the $2500 spend cannot be evaluated without conversion tracking",
+ "Recommends setting up conversion tracking as the first action before any keyword or bid optimization",
+ "Does not recommend bid or keyword changes since there's no conversion data to base decisions on"
+ ]
+ }
+ ]
+}
diff --git a/skills/ads-audit/references/account-health-scoring.md b/skills/ads-audit/references/account-health-scoring.md
new file mode 100644
index 00000000..62e69647
--- /dev/null
+++ b/skills/ads-audit/references/account-health-scoring.md
@@ -0,0 +1,332 @@
+# Account Health Scoring Framework
+
+Structured scoring methodology for Google Ads account audits. Seven health dimensions, each scored 0-5, with weighted rollup to a 0-100 overall score.
+
+---
+
+## Health Dimensions Overview
+
+| # | Dimension | Weight | What It Measures |
+|---|-----------|--------|-----------------|
+| 1 | Conversion Tracking | 20% | Tracking completeness and sophistication |
+| 2 | Campaign Structure | 15% | Organization, segmentation, budget logic |
+| 3 | Keyword Health | 20% | Quality scores, match types, zombie keywords |
+| 4 | Search Term Quality | 15% | Query relevance, negative coverage, mining |
+| 5 | Ad Copy | 10% | RSA quantity, variety, and performance |
+| 6 | Impression Share | 10% | Budget and rank signal interpretation |
+| 7 | Spend Efficiency | 10% | Wasted spend, CPA, concentration risk |
+
+---
+
+## Dimension 1: Conversion Tracking (Weight: 20%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | None | No conversion tracking installed |
+| 1 | Basic | Tag fires but no values assigned; only 1 conversion action |
+| 2 | Partial | Multiple conversion actions with values, but gaps: missing phone calls OR form submissions OR key pages |
+| 3 | Solid | All key actions tracked (form, phone, purchase); values assigned; conversion window set correctly |
+| 4 | Advanced | Score 3 + enhanced conversions enabled; conversion linker tag present; GCLID auto-tagging on |
+| 5 | Best-in-class | Score 4 + offline conversion import OR store visit tracking; Consent Mode v2 implemented; data-driven attribution model |
+
+### Conversion Tracking Red Flags
+
+| Signal | Severity | What It Means |
+|--------|----------|---------------|
+| 0 conversions in 30 days with spend >$500 | Critical | Tracking likely broken or missing |
+| Conversion rate >50% | Critical | Tag firing on page load, not actual conversions |
+| All conversions = "Website" (no action names) | High | Default tracking, no meaningful segmentation |
+| "Include in conversions" set to YES for micro-conversions | Medium | Inflated conversion counts, misleading CPA |
+| Last-click attribution on high-funnel campaigns | Medium | Under-crediting awareness campaigns |
+
+---
+
+## Dimension 2: Campaign Structure (Weight: 15%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | Chaotic | 1 campaign, 1 ad group, 200+ keywords of mixed intent |
+| 1 | Minimal | Multiple campaigns but no logical organization; ad groups have 50+ keywords spanning unrelated themes |
+| 2 | Basic | Campaigns organized by service/product line; ad groups still too broad (30-50 keywords) |
+| 3 | Good | Properly themed ad groups (10-20 keywords each); logical campaign splits by service/geo; match types considered |
+| 4 | Strong | Score 3 + separate brand campaign; geo-targeted campaigns where relevant; budget allocated by priority |
+| 5 | Excellent | Score 4 + funnel-stage separation (brand/non-brand/competitor/remarketing); proper budget allocation ratios; campaign experiments running |
+
+### Structure Assessment Checklist
+
+| Check | Passing Threshold | Failing Signal |
+|-------|------------------|----------------|
+| Keywords per ad group | 10-20 | >30 per ad group |
+| Ad groups per campaign | 5-15 | >25 or just 1 |
+| Brand vs. non-brand separation | Separate campaigns | Mixed in same campaign |
+| Campaign naming convention | Consistent pattern | No pattern (e.g., "Campaign 1", "test") |
+| Budget distribution | Proportional to priority | Equal across all campaigns regardless of performance |
+| Location targeting | Set per campaign need | All campaigns target same broad area |
+
+---
+
+## Dimension 3: Keyword Health (Weight: 20%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | Failing | Average QS <4; >50% zombie keywords; no match type strategy |
+| 1 | Poor | Average QS 4-5; 30-50% zombie keywords; all broad match |
+| 2 | Below Average | Average QS 5-6; 20-30% zombie keywords; mostly broad match with some phrase |
+| 3 | Good | Average QS 6-7; <20% zombie keywords; intentional match type strategy; negatives in place |
+| 4 | Strong | Average QS 7-8; <10% zombie keywords; match type tiering (exact for high-value, phrase/broad for discovery) |
+| 5 | Excellent | Average QS 8+; <5% zombie keywords; SKAGs or tightly themed groups; bid adjustments by match type |
+
+### Keyword Sub-Metric Thresholds
+
+| Sub-Metric | Critical | Needs Work | OK | Strong |
+|------------|----------|------------|----|---------|
+| Average Quality Score | <4 | 4-5 | 6-7 | 8+ |
+| Zombie keywords (0 impressions, 90 days) | >50% | 30-50% | 10-30% | <10% |
+| % Exact match keywords | 0% | <20% | 20-50% | 50%+ for top converters |
+| % Keywords with QS <5 | >40% | 25-40% | 10-25% | <10% |
+| Negative keyword count vs. active keywords | 0 negatives | <10% ratio | 10-30% ratio | 30%+ ratio |
+
+### Quality Score Component Diagnosis
+
+| QS Component | Below Average Fix | Average Fix |
+|-------------|-------------------|-------------|
+| Expected CTR | Rewrite ad copy; test new headlines | Minor headline tweaks; add extensions |
+| Ad Relevance | Tighten ad group themes; match headlines to keywords | Ensure primary keyword appears in headline |
+| Landing Page Experience | Improve page speed, mobile UX, content relevance | Minor content alignment to ad group theme |
+
+---
+
+## Dimension 4: Search Term Quality (Weight: 15%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | Unmonitored | Never reviewed; no negative keywords; broad match with no controls |
+| 1 | Neglected | Reviewed once; <10 negative keywords; relevance <60% |
+| 2 | Basic | Quarterly review; 10-30 negatives; relevance 60-75% |
+| 3 | Managed | Monthly review; 30-100 negatives; relevance 75-85%; obvious irrelevants blocked |
+| 4 | Active | Bi-weekly review; 100+ negatives organized in lists; relevance 85-90%; mining opportunities captured |
+| 5 | Optimized | Weekly review; comprehensive negative lists by theme; relevance >90%; all converting terms added as exact keywords; shared negative lists across campaigns |
+
+### Search Term Relevance Thresholds
+
+| Relevance % | Severity | Interpretation |
+|-------------|----------|---------------|
+| <60% | Critical | More than 40% of spend going to irrelevant queries |
+| 60-75% | Needs Work | Significant waste; negative keyword gaps |
+| 75-85% | OK | Normal for phrase/broad match campaigns |
+| 85-90% | Good | Well-managed negative keyword strategy |
+| >90% | Strong | Tight keyword control; mostly exact match or excellent negatives |
+
+### Mining Opportunity Assessment
+
+| Signal | Action |
+|--------|--------|
+| Search term converting at >2x avg. conversion rate, not added as keyword | Add as exact match keyword immediately |
+| Search term with 10+ clicks and 0 conversions | Add as negative keyword |
+| Search term cluster (3+ related terms) with good performance | Create new ad group targeting this theme |
+| Search term revealing new intent angle | Research and potentially create new campaign |
+
+---
+
+## Dimension 5: Ad Copy (Weight: 10%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | Missing | Ad groups with 0 or 1 active ad; no RSAs |
+| 1 | Minimal | 1 RSA per ad group; only 3-5 headlines; ad strength "Poor" |
+| 2 | Basic | 1 RSA per ad group; 6-8 headlines; ad strength "Average" |
+| 3 | Good | 1-2 RSAs per ad group; 8-11 headlines from 3+ angles; ad strength "Good" |
+| 4 | Strong | 2 RSAs per ad group for testing; 11-15 headlines; 5+ angles; ad strength "Good" to "Excellent" |
+| 5 | Excellent | Score 4 + active A/B tests running; performance data-driven pinning; CTR above position-adjusted benchmark |
+
+### Ad Copy Sub-Metrics
+
+| Sub-Metric | Poor | Average | Good | Excellent |
+|------------|------|---------|------|-----------|
+| RSAs per ad group | 0-1 | 1 | 2 | 2+ with experiment |
+| Headlines per RSA | 3-5 | 6-8 | 9-11 | 12-15 |
+| Distinct headline angles | 1-2 | 3 | 4-5 | 6+ |
+| Ad strength distribution | >50% Poor | >50% Average | >50% Good | >50% Excellent |
+| CTR vs. position benchmark | >30% below | 10-30% below | At benchmark | Above benchmark |
+| Descriptions with CTA | 0% | 25-50% | 50-75% | 75%+ |
+
+---
+
+## Dimension 6: Impression Share (Weight: 10%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | Invisible | Search IS <20%; losing >80% of eligible impressions |
+| 1 | Struggling | Search IS 20-40%; high losses on both budget and rank |
+| 2 | Below Average | Search IS 40-60%; one major loss driver (budget OR rank) |
+| 3 | Competitive | Search IS 60-75%; budget-lost IS <20% and rank-lost IS <30% |
+| 4 | Strong | Search IS 75-90%; budget-lost IS <10% and rank-lost IS <15% |
+| 5 | Dominant | Search IS >90%; minimal losses on both dimensions |
+
+### Budget-Lost IS Interpretation
+
+| Budget-Lost IS | Severity | Meaning |
+|---------------|----------|---------|
+| >30% | Severe | Budget exhausted early in day; missing 30%+ of qualified traffic |
+| 20-30% | Moderate | Noticeable budget constraint; consider increase or narrowing |
+| 10-20% | Acceptable | Minor constraint; may be intentional budget cap |
+| <10% | Good | Budget is not a limiting factor |
+
+### Rank-Lost IS Interpretation
+
+| Rank-Lost IS | Severity | Meaning |
+|-------------|----------|---------|
+| >50% | Crisis | Ads rarely showing in competitive positions; QS or bid fundamentally broken |
+| 30-50% | Needs Work | Consistently outranked; improve QS, bids, or ad relevance |
+| 15-30% | Competitive | Normal competitive loss; optimize incrementally |
+| <15% | Strong | Winning most eligible auctions |
+
+### Impression Share 2x2 Interpretation Matrix
+
+| | Rank-Lost IS LOW (<20%) | Rank-Lost IS HIGH (>20%) |
+|---|------------------------|--------------------------|
+| **Budget-Lost IS LOW (<15%)** | **Healthy** -- Optimizing at the margins. Focus on bid strategy and new keyword expansion. | **QS / Bid Problem** -- Ads not competitive. Improve ad relevance, landing pages, or increase bids. Check QS components. |
+| **Budget-Lost IS HIGH (>15%)** | **Pure Budget Problem** -- Ads are competitive when shown. Increase budget, narrow geo targeting, or daypart to stretch budget. | **Structural Problem** -- Wrong keywords entirely. Audience too broad, poor campaign structure. Rebuild targeting from scratch. |
+
+---
+
+## Dimension 7: Spend Efficiency (Weight: 10%)
+
+| Score | Level | Criteria |
+|-------|-------|----------|
+| 0 | Burning | >30% wasted spend; CPA >3x industry benchmark; no conversion data |
+| 1 | Poor | 20-30% wasted spend; CPA 2-3x benchmark; top spenders not converting |
+| 2 | Below Average | 15-20% wasted spend; CPA 1.5-2x benchmark |
+| 3 | Average | 10-15% wasted spend; CPA within 1-1.5x benchmark; top 20% keywords drive 50%+ conversions |
+| 4 | Good | 5-10% wasted spend; CPA at or below benchmark; strong conversion concentration |
+| 5 | Excellent | <5% wasted spend; CPA well below benchmark; top 20% keywords drive 60%+ conversions; no keyword spending >$200 with 0 conversions |
+
+### Wasted Spend Calculation
+
+```
+Wasted Spend % = (Spend on keywords with 0 conversions AND >10 clicks) / Total Spend x 100
+```
+
+| Wasted Spend % | Severity | Monthly Waste at $10k Spend |
+|---------------|----------|-----------------------------|
+| >30% | Critical | >$3,000/month burned |
+| 20-30% | High | $2,000-$3,000/month |
+| 10-20% | Medium | $1,000-$2,000/month |
+| 5-10% | Low | $500-$1,000/month |
+| <5% | Healthy | <$500/month |
+
+### Spend Concentration Analysis
+
+| Metric | Healthy | Warning | Critical |
+|--------|---------|---------|----------|
+| Top 20% keywords' share of conversions | >50% | 30-50% | <30% |
+| Top 20% keywords' share of spend | <50% | 50-70% | >70% with low conversion share |
+| Single keyword share of total spend | <15% | 15-30% | >30% (concentration risk) |
+| Keywords spending >$100 with 0 conversions | 0-2 | 3-5 | >5 |
+
+---
+
+## Overall Health Score Calculation
+
+### Formula
+
+```
+Overall Score = (D1 x 0.20 + D2 x 0.15 + D3 x 0.20 + D4 x 0.15 + D5 x 0.10 + D6 x 0.10 + D7 x 0.10) / 5 x 100
+```
+
+Where D1-D7 are the dimension scores (0-5).
+
+### Example Calculation
+
+| Dimension | Score | Weight | Weighted |
+|-----------|-------|--------|----------|
+| Conversion Tracking | 3 | 0.20 | 0.60 |
+| Campaign Structure | 2 | 0.15 | 0.30 |
+| Keyword Health | 4 | 0.20 | 0.80 |
+| Search Term Quality | 3 | 0.15 | 0.45 |
+| Ad Copy | 2 | 0.10 | 0.20 |
+| Impression Share | 3 | 0.10 | 0.30 |
+| Spend Efficiency | 3 | 0.10 | 0.30 |
+| **Total** | | | **2.95** |
+
+Overall Score = 2.95 / 5 x 100 = **59 / 100** (Needs Work)
+
+---
+
+## Severity Classification
+
+| Score Range | Classification | Typical Account Profile | Urgency |
+|-------------|---------------|------------------------|---------|
+| 0-30 | Critical | No tracking, chaotic structure, massive waste. Money is actively burning. | Fix this week. Every day costs money. |
+| 31-50 | Needs Significant Work | Basic tracking but major structural gaps. Likely 30-50% of spend is wasted. | Fix within 2 weeks. Prioritize highest-waste areas. |
+| 51-70 | Needs Work | Tracking works, structure is OK, but optimization gaps. Common for unmanaged or self-managed accounts. | Fix within 30 days. Methodical improvement plan. |
+| 71-85 | Good | Well-managed account with room for optimization. Typical of accounts with active management. | Ongoing optimization. Quarterly deep reviews. |
+| 86-100 | Strong | Well-optimized account. Marginal gains from here. | Maintain. Focus on scaling and expansion. |
+
+---
+
+## Priority Action Matrix
+
+For each dimension scored below 3, the single highest-impact fix:
+
+| Dimension | Score 0 Fix | Score 1 Fix | Score 2 Fix |
+|-----------|------------|------------|------------|
+| Conversion Tracking | Install Google Tag + at least 1 conversion action | Add conversion values; track all key actions (form, phone, purchase) | Fill coverage gaps; enable enhanced conversions |
+| Campaign Structure | Split into service-based campaigns with 10-20 keyword ad groups | Reorganize ad groups by theme; separate brand from non-brand | Tighten ad groups to 10-20 keywords; add geo targeting |
+| Keyword Health | Pause all QS <3 keywords; add negative keywords; reduce to 10-20 per ad group | Focus on QS 4-5 keywords: improve ad relevance and landing pages | Add exact match for top converters; pause zombie keywords |
+| Search Term Quality | Run first-ever search term review; add 20+ obvious negatives | Build negative keyword lists by theme; block top wasters | Set up bi-weekly review cadence; mine converting terms |
+| Ad Copy | Create RSA with 8+ headlines for every ad group | Add headlines to reach 8+; ensure 3+ distinct angles | Add second RSA for A/B testing; improve headline variety |
+| Impression Share | Check if budget is depleting before noon; adjust bids down or narrow targeting | Identify top budget-loss campaign; increase budget or narrow geo/schedule | Improve QS on rank-lost keywords; test bid strategies |
+| Spend Efficiency | Pause all keywords with >$100 spend and 0 conversions immediately | Set max CPC caps; pause keywords with >20 clicks and 0 conversions | Reallocate budget from low-efficiency to high-efficiency keywords |
+
+---
+
+## Quick-Reference: Audit Workflow
+
+```
+START
+|
+1. Check Conversion Tracking (Dimension 1)
+ +-- Score 0-1? --> STOP. Fix tracking before anything else.
+ | No point optimizing what you cannot measure.
+ +-- Score 2+? --> Continue
+|
+2. Assess Campaign Structure (Dimension 2)
+ +-- Score 0-1? --> Restructure before optimizing keywords/ads.
+ +-- Score 2+? --> Continue
+|
+3. Evaluate Keyword Health (Dimension 3) + Search Terms (Dimension 4)
+ +-- Run in parallel. These inform each other.
+|
+4. Review Ad Copy (Dimension 5)
+ +-- Only after keywords are stable. No point writing ads for bad keywords.
+|
+5. Analyze Impression Share (Dimension 6) + Spend Efficiency (Dimension 7)
+ +-- These are outcome metrics. Fix inputs (1-5) before worrying about outputs.
+|
+6. Calculate Overall Score
+7. Generate Priority Action Plan (top fix per dimension scoring <3)
+|
+END
+```
+
+---
+
+## Industry CPA Benchmarks
+
+Reference benchmarks for evaluating Dimension 7 (Spend Efficiency):
+
+| Industry | Avg CPA (Search) | Good CPA | Excellent CPA |
+|----------|-----------------|----------|---------------|
+| Legal | $85-$120 | <$70 | <$50 |
+| Home Services | $40-$65 | <$35 | <$25 |
+| Healthcare | $55-$85 | <$50 | <$35 |
+| B2B / SaaS | $75-$120 | <$65 | <$45 |
+| E-commerce | $30-$50 | <$25 | <$15 |
+| Finance / Insurance | $70-$110 | <$60 | <$40 |
+| Real Estate | $50-$80 | <$45 | <$30 |
+| Education | $45-$75 | <$40 | <$25 |
+| Travel | $35-$60 | <$30 | <$20 |
+| Automotive | $40-$65 | <$35 | <$25 |
+
+**Note**: These are directional benchmarks. Actual CPA varies by market, geography, competition, and offer. Use as a reference point, not an absolute target.
diff --git a/skills/ads-copy/SKILL.md b/skills/ads-copy/SKILL.md
new file mode 100644
index 00000000..08e5951f
--- /dev/null
+++ b/skills/ads-copy/SKILL.md
@@ -0,0 +1,384 @@
+---
+name: ads-copy
+description: Generate and A/B test Google Ads copy. Use when asked to write ad copy, headlines, descriptions, create ad variants, test ad messaging, improve CTR, or generate RSA (Responsive Search Ad) components. Trigger on "ad copy", "write ads", "headlines", "descriptions", "RSA", "responsive search ad", "ad text", "ad creative", "improve CTR", "ad A/B test", "ad variants", "write me an ad", or when the user wants to improve click-through rate on existing ads.
+---
+
+## MCP Server Detection
+
+Before calling any Google Ads tool, detect which MCP server is available:
+
+1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
+2. If not found, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*` in the available tools
+3. If neither exists, guide the user:
+
+> No Google Ads MCP server detected. The easiest setup:
+>
+> 1. Get a free API key at [adsagent.org](https://www.adsagent.org)
+> 2. Set the environment variable: `export ADSAGENT_API_KEY=your_key`
+> 3. Restart Claude Code (the toprank plugin's .mcp.json will auto-configure the server)
+>
+> Or configure any Google Ads MCP server manually in your MCP settings.
+
+Use whichever MCP server's tool prefix is available for all subsequent calls in this session.
+
+# Ad Copy Generator + A/B Tester
+
+Write Google Ads RSA copy and run structured A/B tests to find winning messaging.
+
+## Setup
+
+Follow the **MCP Server Detection** section above to verify a Google Ads MCP server is available.
+
+- **If no MCP server is found** → guide the user through setup per the MCP Server Detection instructions, or run `/ads-audit` which walks through full setup (MCP server, token, account selection, and business context).
+- **If the MCP server is available** → read `~/.adsagent/config.json` for `apiKey` and `accountId`. If missing, run `/ads-audit` for onboarding.
+
+## Reference Documents
+
+Before generating any copy, read these reference documents for expert-level context:
+
+- `references/rsa-best-practices.md` — Character limits, headline formulas, pinning strategy, A/B methodology, common mistakes
+- Read from ads skill: `../ads/references/industry-benchmarks.md` — Industry-specific CTR benchmarks to beat
+- Read from ads skill: `../ads/references/quality-score-framework.md` — How ad copy impacts Quality Score components
+
+These contain the specific formulas, character counts, and patterns that separate amateur ad copy from expert-level RSAs.
+
+## Business Context — Read First, Ask Once
+
+Every ad copy decision depends on understanding the business. This skill stores business context in `~/.adsagent/business-context.json` so it only needs to be gathered once.
+
+### On every invocation:
+
+1. **Read `~/.adsagent/business-context.json`**. If it exists and has content, use it — skip the intake interview.
+2. **If missing or empty**, run the intake interview below, then save the result.
+3. **If the user volunteers new info** (new service, changed positioning, seasonal update), merge it into the existing file.
+
+### Intake interview
+
+Gather these fields. Don't ask them as a rigid checklist — pull what you can from context (the account's existing ads, website, campaign names) and only ask what's missing.
+
+```json
+{
+ "business_name": "",
+ "industry": "",
+ "services": [""],
+ "locations": [""],
+ "target_audience": "",
+ "brand_voice": {
+ "tone": "",
+ "words_to_avoid": [""],
+ "words_to_use": [""]
+ },
+ "differentiators": [""],
+ "competitors": [""],
+ "seasonality": {
+ "peak_months": [""],
+ "slow_months": [""],
+ "seasonal_hooks": [""]
+ },
+ "keyword_landscape": {
+ "high_intent_terms": [""],
+ "competitive_terms": [""],
+ "long_tail_opportunities": [""]
+ },
+ "social_proof": [""],
+ "offers_or_promotions": [""],
+ "landing_pages": {},
+ "notes": ""
+}
+```
+
+**Why each field matters for copy:**
+
+| Field | How it shapes copy |
+|-------|-------------------|
+| `industry` | Sets baseline competitive intensity and CPC expectations |
+| `services` | Determines headline categories and description angles |
+| `locations` | Geo-specific headlines get higher quality scores and CTR |
+| `brand_voice` | Tone, forbidden words, preferred language |
+| `differentiators` | These ARE the value prop headlines — the reason someone picks you |
+| `competitors` | Knowing who you're against sharpens positioning (without naming them in ads) |
+| `seasonality` | Tells you WHEN to push urgency copy vs. evergreen, which months to bid up |
+| `keyword_landscape` | High-intent terms go in headlines; competitive terms need sharper differentiation; long-tail = cheaper, more specific copy angles |
+| `social_proof` | Reviews, awards, years in business — trust signal headlines and descriptions |
+| `offers_or_promotions` | Time-sensitive copy angles, CTA variations |
+| `landing_pages` | Copy must match the page or conversions drop — know what's there |
+
+### Bootstrapping from existing data
+
+Before asking the user anything, try to fill fields from what's already available:
+
+- `mcp__adsagent__getAccountInfo` → business name, location hints
+- `mcp__adsagent__listCampaigns` → service categories, geo targeting
+- `mcp__adsagent__listAds` → current voice, headlines in use
+- `mcp__adsagent__getKeywords` → keyword landscape
+- `mcp__adsagent__getSearchTermReport` → real user language, long-tail opportunities
+- `mcp__adsagent__getImpressionShare` → competitive pressure signals
+
+Present what you found and ask the user to confirm/correct/fill gaps. This is faster and more accurate than starting from zero.
+
+## Persona-Informed Copy
+
+Cross-reference `~/.adsagent/personas/{accountId}.json` (created by `/ads-audit`) and `~/.adsagent/business-context.json` to ground every piece of copy in real customer data.
+
+### How personas shape copy decisions
+
+| Persona Field | Copy Application |
+|---------------|-----------------|
+| `search_terms` | Use these exact words and phrases in headlines — they're the language real customers use |
+| `pain_points` | Lead descriptions with the pain point, then present the solution. Pain > features for click-through |
+| `decision_trigger` | This IS your CTA angle. If the trigger is "seeing reviews mentioned", put the review count in a headline |
+| `primary_goal` | Match H1 to this goal. The first headline should answer "will this page help me do X?" |
+| `demographics` | Adjust register: corporate buyer gets different language than homeowner. Technical user gets specs, consumer gets benefits |
+
+### Persona-to-headline mapping
+
+For each ad group, identify which persona(s) it serves:
+1. Look at the ad group's keywords and match to persona `search_terms`
+2. Write H1 using the persona's `primary_goal` language
+3. Write value prop headlines using the persona's `pain_points` (solution framing)
+4. Write CTA using the persona's `decision_trigger`
+
+If an ad group serves multiple personas (common in broad campaigns), create separate ad variants — one optimized per persona — and A/B test which performs better.
+
+## Ad Strength vs Actual Performance
+
+Google's ad strength score optimizes for Google's internal ad diversity goals, not your conversion rate. Treat it as a secondary signal, never a primary optimization target.
+
+### The hierarchy (most to least important)
+
+1. **Conversion rate** — does the ad produce customers?
+2. **CTR** — does the ad get clicks from the right people?
+3. **CPA** — what does each conversion cost?
+4. **Ad strength** — does Google think there's enough variety?
+
+### Specific rules
+
+| Situation | Action |
+|-----------|--------|
+| "Excellent" ad strength, CTR < 2% | Ad strength is misleading. The headlines are varied but not compelling. Rewrite for relevance over diversity |
+| "Good" ad strength, CTR > 5% | Do not touch this ad to chase "Excellent". The ad is working. Ad strength is a vanity metric here |
+| "Poor" ad strength, CTR > industry avg | Add more headline/description variety to satisfy Google's diversity requirement, but don't change the winning headlines |
+| "Poor" ad strength, CTR < industry avg | Both signals agree — the ad needs a rewrite. Start with headline relevance to keywords |
+| Ad strength drops after headline edit | If CTR improved, ignore the ad strength drop. If CTR also dropped, revert |
+
+### When ad strength IS useful
+
+- Ensuring you have 8+ distinct headlines (not minor variations of the same message)
+- Ensuring at least 1 headline per category (service, value prop, trust, CTA)
+- Flagging when all descriptions say the same thing in different words
+- Catching missing keyword insertion opportunities
+
+## Competitive Differentiation
+
+Read `~/.adsagent/business-context.json` `competitors` and `differentiators` fields. If empty, infer competitors from auction overlap (high impression share keywords where rank-lost IS is elevated suggest active competitors).
+
+### Rules for competitive copy
+
+| Rule | Rationale |
+|------|-----------|
+| NEVER name competitors in ad copy | Policy violation risk with Google Ads. Also sends brand awareness to competitors. Even "Better than [Competitor]" is dangerous |
+| NEVER use "best" or "#1" without qualification | Google requires substantiation for superlative claims. "Best-Rated on Google" is OK if verifiable. "Best Plumber" is not |
+| DO use specific features competitors lack | "Same-Day Service" beats "Better Service". Specificity implies superiority without claiming it |
+| DO use pricing advantage if real | "Flat-Rate Pricing" or "From $99" differentiates against competitors with opaque pricing |
+| DO use trust signals aggressively | "25+ Years", "4.9★ Google Rating", "500+ 5-Star Reviews" — these are verifiable and powerful |
+| DO use location specificity | "Seattle's Own [Service]" or "Locally Owned Since 1998" differentiates against national chains |
+| DO use speed/convenience | "Same-Day", "24/7", "Book Online in 60 Seconds" — operational advantages competitors may not match |
+| DO use guarantees | "Satisfaction Guaranteed", "Free Re-Service", "No Fix, No Fee" — risk reversal converts |
+
+### Differentiation angle selection
+
+Based on the competitive landscape, choose the strongest angle:
+
+| Business Situation | Best Differentiation Angle | Example Headline |
+|-------------------|---------------------------|-----------------|
+| Competing against national chains | Local ownership, personal service, community ties | "Family-Owned Since 2005" |
+| Competing against cheaper alternatives | Quality, guarantees, reviews, expertise | "Licensed & Insured Pros" |
+| Competing against premium alternatives | Value, transparent pricing, same quality for less | "Premium Service, Fair Prices" |
+| Unique service offering | The specific feature itself | "Same-Day Emergency Visits" |
+| Crowded market, no clear advantage | Speed, convenience, or customer experience | "Book Online — Arrive in 1hr" |
+
+## Workflow
+
+### 1. Understand the brief
+
+Detect or ask:
+- What product/service is this ad for?
+- Target audience or segment?
+- Which campaign/ad group? (pull with `mcp__adsagent__listCampaigns` → `mcp__adsagent__listAdGroups`)
+- Landing page URL?
+- Any geographic targeting?
+
+Cross-reference against the business context — if the user says "write copy for boarding" and context has boarding details, you already know the angles.
+
+### 2. Research what's working
+
+Pull data before writing — copy should be grounded in what converts, not guesses.
+
+**Current ad performance:**
+- `mcp__adsagent__listAds` — existing headlines/descriptions and their metrics
+- `mcp__adsagent__getKeywords` — active keywords
+- `mcp__adsagent__getSearchTermReport` — actual user queries (reveals real language and intent)
+- `mcp__adsagent__getCampaignPerformance` — CTR/conversion benchmarks to beat
+
+**Use seasonality context.** If business context shows peak months, factor that into copy urgency. During slow months, lean on evergreen value props. During peaks, lean on scarcity and timeliness.
+
+**Use keyword landscape context.** For competitive terms (high CPC, many bidders), copy must differentiate harder — lead with what's unique, not what everyone says. For long-tail terms, match the specific intent closely.
+
+**If the user has a database with lead/conversion data**, query it to find which keywords and messaging actually convert. The language paying customers use is the language your ads should mirror.
+
+### 3. Generate RSA components
+
+Google RSA: up to **15 headlines** (30 chars max) and **4 descriptions** (90 chars max). Google's AI mixes and matches them.
+
+**Always count characters. Flag any that exceed limits. A single character over = rejected by Google.**
+
+#### Headline Formulas by Category
+
+Use these formulas to generate varied, high-performing headlines. Each formula is battle-tested across thousands of accounts. Adapt the template to the specific business.
+
+| # | Category | Formula | Template | Example | Chars |
+|---|----------|---------|----------|---------|-------|
+| 1 | Service+Location | [Service] in [City] | `___ in ___` | Dog Boarding in Seattle | 23 |
+| 2 | Service+Location | [City] [Service] Provider | `___ ___ Provider` | Austin Plumbing Experts | 24 |
+| 3 | Service+Location | [Neighborhood] [Service] | `___ ___` | Capitol Hill Dog Boarding | 26 |
+| 4 | Value Prop | [Benefit] [Service] | `___ ___` | Same-Day AC Repair | 18 |
+| 5 | Value Prop | [Adj] [Service] [Qualifier] | `___ ___ ___` | Affordable Pet Grooming | 24 |
+| 6 | Value Prop | [Service] You Can Trust | `___ You Can Trust` | Plumbing You Can Trust | 22 |
+| 7 | Trust Signal | [N]+ Years Experience | `___+ Years Experience` | 25+ Years Experience | 20 |
+| 8 | Trust Signal | [Rating]★ Rated [Service] | `___★ Rated ___` | 4.9★ Rated Dog Boarding | 24 |
+| 9 | Trust Signal | [N]+ [Reviews/Clients] | `___+ 5-Star Reviews` | 500+ 5-Star Reviews | 21 |
+| 10 | CTA | Get [Benefit] Today | `Get ___ Today` | Get Your Free Quote Today | 25 |
+| 11 | CTA | Book [Service] Now | `Book ___ Now` | Book Your Cleaning Now | 22 |
+| 12 | CTA | Call Now — [Benefit] | `Call Now — ___` | Call Now — Free Estimate | 24 |
+| 13 | Urgency | [Offer] — Limited Time | `___ — Limited Time` | 20% Off — Limited Time | 23 |
+| 14 | Urgency | [N] Spots Left [Period] | `___ Spots Left ___` | 5 Spots Left This Week | 23 |
+| 15 | Price/Offer | [Service] From $[Price] | `___ From $___` | Teeth Cleaning From $99 | 24 |
+| 16 | Price/Offer | Free [Offer] Included | `Free ___ Included` | Free Consultation Included | 27 |
+| 17 | Question | Need [Service]? | `Need ___?` | Need Emergency Plumbing? | 24 |
+| 18 | Question | Looking for [Service]? | `Looking for ___?` | Looking for Dog Boarding? | 25 |
+| 19 | Benefit | [Result] Guaranteed | `___ Guaranteed` | Satisfaction Guaranteed | 23 |
+| 20 | Benefit | [Outcome] in [Timeframe] | `___ in ___` | Results in 30 Days | 19 |
+| 21 | Social Proof | Trusted by [N]+ [Clients] | `Trusted by ___+ ___` | Trusted by 500+ Families | 25 |
+| 22 | Social Proof | [City]'s Top-Rated [Service] | `___'s Top-Rated ___` | Seattle's Top-Rated Vet | 24 |
+| 23 | Differentiator | [Unique Feature] [Service] | `___ ___` | Licensed & Insured Pros | 23 |
+| 24 | Differentiator | [Guarantee] or [Refund] | `___ or ___` | On Time or It's Free | 20 |
+
+**Headline selection rules:**
+- Generate 3-4 headlines per category for a total of 12-15
+- Pin 1 Service+Location headline to Position 1 (highest relevance impact)
+- Pin 1 CTA headline to Position 3 (Google shows H3 less often — make it count when shown)
+- Leave Position 2 unpinned to let Google test Value Prop, Trust, and Differentiator headlines
+- Never pin more than 3 headlines total — over-pinning reduces Google's optimization ability
+
+#### Description Formulas
+
+| # | Angle | Template | Example | Chars |
+|---|-------|----------|---------|-------|
+| 1 | Core Value + Location | [Primary benefit] for [audience] in [location]. [Secondary benefit]. [CTA]. | Professional dog boarding for Seattle pet parents. Cage-free play all day. Book online today. | 88 |
+| 2 | Differentiator + CTA | [What makes you different]. [Proof point]. [CTA with urgency]. | Family-owned since 2005 with 500+ 5-star reviews. Schedule your free estimate — limited availability. | 90 |
+| 3 | Trust + Social Proof | [Trust signal]. [Social proof]. [Outcome promise]. | Licensed, bonded & insured. Rated 4.9★ by 300+ homeowners. Your satisfaction guaranteed. | 85 |
+| 4 | Urgency + Offer | [Time-sensitive hook]. [Offer detail]. [CTA]. | This week only — 20% off your first visit. New clients save on [service]. Call now to claim. | 87 |
+| 5 | Problem + Solution | [Pain point]? [Solution]. [Proof]. [CTA]. | Tired of unreliable contractors? We show up on time, every time. 25+ years trusted. Get a quote. | 90 |
+| 6 | Feature Stack | [Feature 1]. [Feature 2]. [Feature 3]. [CTA]. | Same-day service. Transparent pricing. No hidden fees. Request your free quote online today. | 86 |
+| 7 | Persona-Targeted | [Persona pain point]. [How you solve it]. [Decision trigger]. | Busy schedule? We offer evening & weekend appointments. Book online in 60 seconds. | 80 |
+| 8 | Seasonal/Timely | [Seasonal hook]. [Relevant service]. [Urgency CTA]. | Spring is peak pest season — protect your home now. Licensed exterminators. Book this week. | 87 |
+
+**Description selection rules:**
+- Always generate 4 descriptions (the RSA maximum)
+- D1 should be the strongest all-around description (core value + location) — it shows most often
+- D2 should emphasize the primary differentiator
+- D3 should lead with trust/social proof
+- D4 should be seasonal or offer-based (swap this out when promotions change)
+- Every description must end with a CTA verb: Call, Book, Get, Schedule, Request, Visit, Contact
+- Character count is STRICT: 90 chars max. Measure before finalizing. It's better to be 85 chars and punchy than 90 chars and cramped
+
+### 4. Present variants
+
+Show 2-3 variants, each with a distinct messaging angle. Name the angle so it's clear what's being tested.
+
+```
+VARIANT A: "[Angle Name — e.g., Trust & Experience]"
+ Target persona: [persona name from ~/.adsagent/personas/]
+ H1 [Pin 1]: [Service] in [Location] (XX chars)
+ H2: [Value prop headline] (XX chars)
+ H3: [Trust headline] (XX chars)
+ H4: [CTA headline] (XX chars)
+ ... (up to 15 headlines)
+ D1: [Core value + location — max 90 chars] (XX chars)
+ D2: [Differentiator + CTA — max 90 chars] (XX chars)
+ D3: [Trust + proof — max 90 chars] (XX chars)
+ D4: [Urgency/offer — max 90 chars] (XX chars)
+
+VARIANT B: "[Different Angle — e.g., Price & Value]"
+ Target persona: [persona name]
+ H1 [Pin 1]: ...
+ ...
+```
+
+Always show character counts. Always show pin positions. Always name the target persona.
+
+**Variant differentiation rules:**
+- Each variant must test a meaningfully different angle — not minor word swaps
+- Good test: "Trust & Expertise" vs "Speed & Convenience" vs "Price & Value"
+- Bad test: "Call Today" vs "Call Now" vs "Call Us" (not different enough to learn from)
+- If the account has multiple personas, create one variant per persona
+
+### 5. Deploy
+
+After user approves a variant, push it live:
+
+- **New ad:** `mcp__adsagent__createAd` — create the RSA in the target ad group (created paused)
+- **Update existing:** `mcp__adsagent__updateAdAssets` — replace headlines/descriptions on a live ad
+- **Enable when ready:** `mcp__adsagent__enableAd`
+
+Always confirm before any write operation. Note the `changeId` returned — user can undo within 7 days via `mcp__adsagent__undoChange`.
+
+### 6. A/B test (if running one)
+
+1. **Identify the variable** — messaging angle, CTA style, emotional vs. practical
+2. **Deploy both variants** as separate ads in the same ad group (both paused, enable together)
+3. **Minimum run:** 2 weeks or 100 clicks per variant, whichever comes first
+4. **Success metric:** CTR for awareness campaigns, conversion rate for bottom-funnel
+
+**Statistical significance rules:**
+- Do not call a winner with <100 clicks per variant — the data isn't reliable
+- A "winner" needs at least 20% relative CTR or conversion rate difference to be meaningful
+- If the difference is <20% after 200+ clicks each, the variants are functionally equivalent — pick the one with better conversion rate, or run a bolder test
+- If one variant has 2x+ the conversion rate, call it immediately — don't wait for click minimums
+
+### 7. Check results
+
+After the test period, pull results:
+
+```
+mcp__adsagent__listAds → compare metrics for each variant
+```
+
+| Variant | Impressions | Clicks | CTR | Conversions | Conv Rate | CPA | Winner? |
+|---------|------------|--------|-----|-------------|-----------|-----|---------|
+| A | | | | | | | |
+| B | | | | | | | |
+
+**Interpretation matrix:**
+
+| CTR | Conv Rate | Diagnosis | Action |
+|-----|-----------|-----------|--------|
+| A higher | A higher | Clear winner | Pause B. Iterate on A's angle with fresh headlines |
+| A higher | B higher | A attracts more clicks but B converts better | Keep B as primary. Test A's headlines on B's landing page — the click-through message may need landing page alignment. Offer `/ads-landing` |
+| Similar | Similar | No meaningful difference | Need a bolder test — the variants were too similar. Change the core messaging angle, not just word choice |
+| Both low | Both low | Neither variant works | The problem isn't A vs B — it's the overall approach. Check: keyword intent match, landing page quality, offer strength. May need `/ads-audit` to diagnose |
+
+After deciding a winner: pause the loser with `mcp__adsagent__pauseAd`, keep the winner running. Then create a new variant to test against the winner — continuous improvement, never stop testing.
+
+## Rules
+
+1. **Business context first.** Read `~/.adsagent/business-context.json` before doing anything. If it doesn't exist, build it.
+2. **Research before writing.** Always pull current performance data. Don't write copy in a vacuum.
+3. **Character limits are hard.** Count every headline (<=30) and description (<=90). No exceptions. When in doubt, count again.
+4. **Never deploy without confirmation.** Show the exact copy, get a yes, then create/update.
+5. **Note changeIds.** Every write returns one. Tell the user they can undo within 7 days.
+6. **Ground copy in conversion data.** If conversion data is available, use the language that converts. Customer language > marketing language.
+7. **Seasonal awareness.** Check the business context for peak/slow months. Adjust urgency and messaging accordingly.
+8. **Defer to /ads for account management.** This skill writes copy and deploys ads. For bid/budget/keyword work, use `/ads`.
+9. **Personas over guesses.** If personas exist, every headline should trace back to a persona's language or triggers. If they don't exist, recommend `/ads-audit` to build them.
+10. **Differentiate, don't imitate.** Read the competitors field and write copy that stands apart. Generic copy that could belong to any competitor is a waste of an ad slot.
diff --git a/skills/ads-copy/evals/evals.json b/skills/ads-copy/evals/evals.json
new file mode 100644
index 00000000..6cd78f3d
--- /dev/null
+++ b/skills/ads-copy/evals/evals.json
@@ -0,0 +1,36 @@
+{
+ "skill_name": "ads-copy",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Write ad copy for a dog grooming business in Seattle called 'Pawfect Grooming'. They offer full grooming, nail trims, and teeth cleaning. They have 4.8 stars on Google with 200+ reviews. They've been in business for 12 years. Target ad group: 'Dog Grooming - Seattle'.",
+ "expected_output": "RSA copy with 2-3 variants, each with a distinct messaging angle. Every headline must show character count and be <= 30 chars. Every description must show character count and be <= 90 chars. Pin positions should be indicated. Variants should be named by their angle (e.g., 'Trust & Experience', 'Value & Convenience').",
+ "files": [],
+ "expectations": [
+ "Generates at least 2 distinct RSA variants with named messaging angles",
+ "Every headline shows a character count",
+ "All headlines are <= 30 characters",
+ "Every description shows a character count",
+ "All descriptions are <= 90 characters",
+ "At least one headline includes Seattle (location specificity)",
+ "At least one headline references the 4.8 star rating or 200+ reviews (social proof)",
+ "At least one headline references 12 years in business (trust signal)",
+ "Pin positions are indicated (at least H1 pinned to position 1)"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "I want to A/B test my ad copy for the 'Roof Repair' ad group. Current ad has 2.1% CTR over 500 clicks. Here's the current ad:\nH1: Roof Repair Services\nH2: Licensed & Insured\nH3: Call Now for a Quote\nD1: Professional roof repair services for residential and commercial properties. Fast, reliable service.\nD2: Licensed, bonded, and insured. Over 20 years of experience. Free estimates available.\n\nCan you create a challenger variant?",
+ "expected_output": "Creates a challenger variant with a clearly different messaging angle. Specifies the test methodology: run both ads in the same ad group, minimum 100 clicks per variant or 2 weeks. Names the variable being tested. Recommends deploying both paused and enabling simultaneously.",
+ "files": [],
+ "expectations": [
+ "Creates a challenger variant with a distinctly different angle from the current ad",
+ "Names the variable being tested (e.g., 'urgency vs trust', 'benefit-led vs feature-led')",
+ "Specifies minimum test duration (2 weeks or clicks threshold)",
+ "Recommends deploying both ads in the same ad group",
+ "Specifies the success metric (CTR and/or conversion rate)",
+ "Character counts shown for all new headlines and descriptions"
+ ]
+ }
+ ]
+}
diff --git a/skills/ads-copy/references/rsa-best-practices.md b/skills/ads-copy/references/rsa-best-practices.md
new file mode 100644
index 00000000..2b1ebb72
--- /dev/null
+++ b/skills/ads-copy/references/rsa-best-practices.md
@@ -0,0 +1,302 @@
+# RSA Best Practices Reference
+
+Expert knowledge for writing, testing, and optimizing Responsive Search Ads. Specific character limits, formula tables, pinning strategies, and performance benchmarks.
+
+---
+
+## Character Limits
+
+| Component | Max Characters | Notes |
+|-----------|---------------|-------|
+| Headline | 30 | Up to 15 headlines per RSA |
+| Description | 90 | Up to 4 descriptions per RSA |
+| Display Path 1 | 15 | Appears after domain in display URL |
+| Display Path 2 | 15 | Second segment after slash |
+| Final URL | 2048 | Landing page URL |
+| Business Name | 25 | Shown in some ad formats |
+
+### Minimum Asset Requirements
+
+| Asset | Minimum Required | Recommended | Maximum |
+|-------|-----------------|-------------|---------|
+| Headlines | 3 | 11-15 | 15 |
+| Descriptions | 2 | 3-4 | 4 |
+| Unique headline angles | 3 | 5+ | -- |
+
+---
+
+## Headline Formula Table
+
+### Service + Location Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 1 | Service in City | [Service] in [City] | Plumbing in Austin | 18 |
+| 2 | City + Service | [City] [Service] Experts | Denver Roofing Experts | 22 |
+| 3 | Near You | [Service] Near You | AC Repair Near You | 18 |
+| 4 | Local + Service | Local [Service] in [City] | Local HVAC in Dallas | 20 |
+
+### Value Proposition Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 5 | Differentiator | [Unique Benefit] [Service] | Same-Day Emergency Repair | 25 |
+| 6 | Result Promise | Get [Result] [Timeframe] | Get More Leads in 30 Days | 26 |
+| 7 | Save + Metric | Save [Amount] on [Service] | Save 40% on Insurance | 22 |
+| 8 | Award/Rank | #1 Rated [Service] in [City] | #1 Rated Dentist in Miami | 25 |
+
+### Trust Signal Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 9 | Years in Business | [N]+ Years of Experience | 25+ Years of Experience | 23 |
+| 10 | Reviews | [N]-Star Rated on Google | 5-Star Rated on Google | 22 |
+| 11 | Customers Served | [N]+ Satisfied Customers | 10,000+ Happy Customers | 24 |
+| 12 | Licensed/Certified | Licensed & Insured [Trade] | Licensed & Insured HVAC | 24 |
+
+### CTA Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 13 | Get + Offer | Get Your Free [Offer] | Get Your Free Estimate | 22 |
+| 14 | Action + Today | [Action] Today | Book a Consultation Today | 26 |
+| 15 | Call Now | Call Now for [Benefit] | Call Now for Free Quote | 22 |
+| 16 | Start + Action | Start [Action] Today | Start Saving Today | 18 |
+
+### Urgency / Scarcity Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 17 | Limited Time | Limited Time: [Offer] | Limited Time: 20% Off | 22 |
+| 18 | Ending Soon | [Offer] Ends [Date] | Spring Sale Ends Friday | 23 |
+| 19 | Spots Left | Only [N] Spots Left | Only 5 Spots Left | 18 |
+
+### Price / Offer Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 20 | Starting At | [Service] From $[Price] | Websites From $499 | 18 |
+| 21 | Discount | [N]% Off [Service] | 30% Off First Month | 20 |
+| 22 | Free Offer | Free [Deliverable] | Free Roof Inspection | 20 |
+
+### Question Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 23 | Need + Service? | Need [Service]? | Need a New Roof? | 16 |
+| 24 | Looking for? | Looking for [Solution]? | Looking for Fast WiFi? | 22 |
+
+### Benefit Headlines
+
+| # | Formula | Template | Example | Chars |
+|---|---------|----------|---------|-------|
+| 25 | Adjective + Benefit | [Adjective] [Service] | Affordable Web Design | 21 |
+| 26 | No + Pain Point | No [Pain Point] | No Hidden Fees Ever | 19 |
+| 27 | Fast + Outcome | Fast [Outcome] Guaranteed | Fast Turnaround Guaranteed | 27 |
+
+---
+
+## Description Formula Table
+
+| # | Category | Formula | Template | Example | Chars |
+|---|----------|---------|----------|---------|-------|
+| 1 | Core Benefit + Location | [Benefit] for [audience] in [City]. [CTA]. | Professional plumbing services for homes in Austin. Call today for a free estimate. | 82 |
+| 2 | Differentiator + CTA | [What makes you different]. [Proof]. [CTA]. | Same-day service with no overtime charges. Serving 10,000+ homes. Book online now. | 85 |
+| 3 | Trust + Social Proof | [Trust signal]. [Social proof]. [CTA]. | Licensed & insured since 1998. Rated 4.9/5 on Google. Schedule your free consultation. | 89 |
+| 4 | Urgency + Offer | [Time limit]. [Offer details]. [CTA]. | Spring special ends March 31st. Save 25% on all AC installations. Call now to lock in rates. | 90 |
+| 5 | Problem + Solution | [Pain point]? [Your solution]. [CTA]. | Tired of slow WiFi? We install enterprise-grade networks for homes. Get a free site survey. | 90 |
+| 6 | Feature + Benefit | [Feature] so you [benefit]. [CTA]. | 24/7 emergency support so you never wait for help. Request service online in 60 seconds. | 88 |
+| 7 | Comparison + Advantage | Unlike [alternative], we [advantage]. [CTA]. | Unlike big-box stores, we custom-build every cabinet. Visit our showroom or request a quote. | 90 |
+| 8 | Risk Reversal + Guarantee | [Guarantee]. [Risk removal]. [CTA]. | 100% satisfaction guarantee or your money back. No contracts, cancel anytime. Start free today. | 90 |
+| 9 | Credentials + Expertise | [Credential]. [Years/experience]. [CTA]. | Board-certified surgeons with 15,000+ procedures performed. Book your consultation today. | 88 |
+| 10 | Process + Ease | [How it works in N steps]. [CTA]. | 3 simple steps: request a quote, approve the plan, we handle the rest. Get started in minutes. | 90 |
+
+---
+
+## Pinning Strategy Decision Tree
+
+```
+Should I pin this headline?
+|
++-- Is it a legal/compliance requirement?
+| +-- YES --> Pin to Position 1 or 2 (mandatory)
+| +-- NO --> Continue
+|
++-- Is it a brand name headline?
+| +-- YES --> Pin to Position 1 (brand consistency)
+| +-- NO --> Continue
+|
++-- Is it a price/offer that MUST appear?
+| +-- YES --> Pin to Position 1 or 2
+| +-- NO --> Continue
+|
++-- Does the ad group have a single clear intent?
+| +-- YES --> Leave unpinned (let Google optimize)
+| +-- NO --> Continue
+|
++-- Do you have 100+ conversions/month in this ad group?
+| +-- YES --> Leave unpinned (enough data for Google to optimize)
+| +-- NO --> Consider pinning your best 2-3 headlines to Positions 1-2
+|
+DEFAULT --> Leave unpinned. Google's ML needs freedom to test combinations.
+```
+
+### Pinning Impact on Ad Strength
+
+| Pins Used | Impact on Ad Strength | Impact on Impressions |
+|-----------|----------------------|----------------------|
+| 0 pins | Neutral to positive | Maximum reach |
+| 1-2 pins | Minor reduction | Minimal impact |
+| 3-5 pins | Moderate reduction | 10-15% fewer impressions |
+| 6+ pins | Significant reduction | 20-40% fewer impressions |
+| All pinned | Severe; ad strength drops to "Poor" | 40-70% fewer impressions |
+
+### Pinning Rules
+
+| Rule | Rationale |
+|------|-----------|
+| Never pin more than 2 headlines to the same position | Gives Google at least 2 options per slot |
+| If you pin Position 1, provide 3+ headlines pinned there | Ensures variety even with pinning |
+| Never pin all 15 headlines | Defeats the purpose of RSA entirely |
+| Pin descriptions less often than headlines | Descriptions have less positional impact |
+
+---
+
+## Ad Strength Scoring
+
+### What Google's Ad Strength Actually Measures
+
+| Ad Strength | What It Means | What It Does NOT Mean |
+|-------------|---------------|----------------------|
+| Poor | Too few assets or too similar | Your ads will not convert |
+| Average | Minimum diversity met | Adequate for conversions |
+| Good | Solid headline/description variety | You are optimized |
+| Excellent | Maximum asset diversity | Maximum conversion rate |
+
+### Ad Strength vs. Performance Reality
+
+| Scenario | Ad Strength | CTR | Conv. Rate | Verdict |
+|----------|------------|-----|------------|---------|
+| Highly targeted ad group, 5 specific headlines | Average | High | High | Keep it. Ad strength is wrong. |
+| Broad ad group, 15 generic headlines | Excellent | Low | Low | Ad strength is misleading. Fix targeting. |
+| Brand campaign, 3 pinned headlines | Poor | Very High | Very High | Ignore ad strength for brand. |
+
+**When to ignore Ad Strength**: Brand campaigns, single-product ad groups with very specific intent, accounts with <50 conversions/month where Google's ML has insufficient data.
+
+**When to respect Ad Strength**: Broad campaigns with mixed intent, new campaigns with no performance data, campaigns spending >$5k/month where impressions matter.
+
+---
+
+## CTR Benchmarks by Ad Position
+
+| Ad Position | Avg CTR (Search) | Top Quartile CTR | Bottom Quartile CTR |
+|-------------|-----------------|-------------------|---------------------|
+| Position 1 (top) | 6-7% | 10-12% | 3-4% |
+| Position 2 | 4-5% | 7-8% | 2-3% |
+| Position 3 | 2-3% | 4-5% | 1-2% |
+| Position 4+ (bottom of page) | 1-2% | 2-3% | <1% |
+
+### CTR Benchmarks by Industry (Position 1)
+
+| Industry | Avg CTR | Good CTR | Excellent CTR |
+|----------|---------|----------|---------------|
+| Legal | 4.4% | 6% | 8%+ |
+| Home Services | 5.2% | 7% | 10%+ |
+| Healthcare | 3.6% | 5% | 7%+ |
+| B2B / SaaS | 3.2% | 5% | 7%+ |
+| E-commerce | 2.8% | 4% | 6%+ |
+| Finance / Insurance | 3.8% | 5.5% | 8%+ |
+| Real Estate | 3.7% | 5% | 7%+ |
+| Education | 4.1% | 6% | 8%+ |
+| Travel | 4.7% | 6.5% | 9%+ |
+| Automotive | 4.0% | 5.5% | 7%+ |
+
+---
+
+## A/B Testing Methodology
+
+### Minimum Sample Requirements
+
+| Metric | Minimum Threshold | Ideal Threshold |
+|--------|------------------|-----------------|
+| Clicks per variant | 100 | 250+ |
+| Duration | 14 days | 30 days |
+| Conversions per variant | 30 | 50+ |
+| Impressions per variant | 1,000 | 5,000+ |
+
+### When to Call a Winner Early
+
+| Condition | Can Call Early? | Confidence |
+|-----------|---------------|------------|
+| 3x CTR difference, 50+ clicks each | Yes | High |
+| 2x CTR difference, 100+ clicks each | Yes | High |
+| Stat sig >99%, 75+ clicks each | Yes | High |
+| <20% CTR difference, <200 clicks | No | Wait |
+| Conv. rate difference <10%, <50 conversions | No | Wait |
+
+### What to Test (Priority Order)
+
+| Priority | Test Variable | Expected CTR Impact | Min. Test Duration |
+|----------|--------------|--------------------|--------------------|
+| 1 | Headline angle (benefit vs. feature) | 15-30% | 14 days |
+| 2 | CTA phrasing (Get vs. Book vs. Call) | 10-20% | 14 days |
+| 3 | Price/offer inclusion vs. exclusion | 10-25% | 14 days |
+| 4 | Urgency language vs. none | 5-15% | 21 days |
+| 5 | Question vs. statement headline | 5-15% | 21 days |
+| 6 | Description CTA variation | 5-10% | 21 days |
+| 7 | Display path text | 3-8% | 14 days |
+
+### Interpreting Test Results
+
+| Result | Interpretation | Action |
+|--------|---------------|--------|
+| CTR up, Conv. Rate up | Clear winner | Adopt immediately |
+| CTR up, Conv. Rate flat | More clicks, same quality | Adopt if CPA is acceptable |
+| CTR up, Conv. Rate down | Attracting wrong clicks | Revert; tighten targeting |
+| CTR down, Conv. Rate up | Fewer but better clicks | Keep if total conversions increase |
+| CTR flat, Conv. Rate flat | No meaningful difference | Test a bolder variation |
+
+---
+
+## Headline Variation Requirements
+
+### Minimum Diversity Rules
+
+| Rule | Minimum | Recommended |
+|------|---------|-------------|
+| Total unique headlines | 8 | 11-15 |
+| Distinct angles/themes | 3 | 5+ |
+| Headlines with CTA | 2 | 3 |
+| Headlines with location | 1-2 | 2-3 (if local) |
+| Headlines with numbers | 2 | 3-4 |
+| Character length spread | 3 different lengths | Mix of 15-20, 21-25, 26-30 |
+
+### Angle Distribution for 12-Headline RSA
+
+| Angle | Count | Examples |
+|-------|-------|---------|
+| Service/Product | 2-3 | "Professional Roof Repair", "Complete Roofing Solutions" |
+| Value Proposition | 2-3 | "Same-Day Service Available", "No Hidden Fees" |
+| Trust/Proof | 2 | "25+ Years Experience", "4.9-Star Google Rating" |
+| CTA | 2 | "Get a Free Quote Today", "Book Online in Minutes" |
+| Offer/Price | 1-2 | "Spring Sale: 20% Off", "Free Inspection Included" |
+| Location | 1-2 | "Serving All of Austin", "Dallas Roofing Experts" |
+
+---
+
+## Common RSA Mistakes
+
+| Mistake | Why It Hurts | Fix |
+|---------|-------------|-----|
+| Too many similar headlines | Google shows redundant combinations; wastes ad slots | Write from 5+ distinct angles |
+| All headlines same length | Looks repetitive; Google prefers mixing short + long | Vary between 15-30 chars |
+| No CTA headlines | Misses click intent when Google picks non-CTA combination | Include 2-3 CTA headlines |
+| Pinning everything | Reduces Google's optimization ability by 40-70% | Pin only what is legally or brand-required |
+| Ignoring ad strength entirely | Missing easy wins from insufficient asset diversity | Aim for "Good" minimum unless justified |
+| Only 3 headlines provided | Minimum assets = minimum reach and no testing | Always provide 8+ headlines |
+| Duplicate keywords in headlines | Wastes headline slots repeating same keyword | Each headline should add new info |
+| No description CTA | Descriptions without CTA have 10-15% lower CTR | End every description with an action verb |
+| Display paths left empty | Wastes free keyword real estate in ad | Always fill both display path segments |
+| Same ad copy across all ad groups | Ignores intent differences between ad groups | Tailor headlines to each ad group's keyword theme |
+| Testing too many variables at once | Cannot isolate what caused improvement | Change one angle per test cycle |
+| Not reviewing Search Terms Report | Ad copy may not match actual queries | Check STR monthly; adapt headlines to real queries |
diff --git a/skills/ads/SKILL.md b/skills/ads/SKILL.md
new file mode 100644
index 00000000..e4f34aad
--- /dev/null
+++ b/skills/ads/SKILL.md
@@ -0,0 +1,545 @@
+---
+name: ads
+description: Manage Google Ads campaigns — read performance, optimize keywords, adjust bids and budgets, add negatives, pause/enable campaigns, manage ads/ad groups, tracking templates, location targeting, network settings, rename campaigns/ad groups, bulk operations, and undo changes. Use this skill whenever the user mentions Google Ads, campaigns, keywords, ad spend, CPA, ROAS, search terms, negative keywords, bids, budgets, ads performance, location targeting, geo targeting, or campaign settings — even if they don't say "ads" explicitly.
+version: 2.0.0
+triggers:
+ - google ads
+ - campaigns
+ - keywords
+ - ad spend
+ - CPA
+ - ROAS
+ - search terms
+ - negative keywords
+ - bid
+ - budget
+ - pause campaign
+ - ads performance
+ - location targeting
+ - geo targeting
+ - campaign settings
+ - rename campaign
+ - rename ad group
+ - bulk keywords
+---
+
+## MCP Server Detection
+
+Before calling any Google Ads tool, detect which MCP server is available:
+
+1. Check for AdsAgent tools: try calling `mcp__adsagent__listConnectedAccounts`
+2. If not found, check for Google's official MCP: look for tools matching `mcp__google_ads_mcp__*` in the available tools
+3. If neither exists, guide the user:
+
+> No Google Ads MCP server detected. The easiest setup:
+>
+> 1. Get a free API key at [adsagent.org](https://www.adsagent.org)
+> 2. Set the environment variable: `export ADSAGENT_API_KEY=your_key`
+> 3. Restart Claude Code (the toprank plugin's .mcp.json will auto-configure the server)
+>
+> Or configure any Google Ads MCP server manually in your MCP settings.
+
+Use whichever MCP server's tool prefix is available for all subsequent calls in this session.
+
+# AdsAgent — Google Ads Management
+
+Manage Google Ads campaigns via the MCP server.
+
+## Configuration
+
+All persistent config lives in `~/.adsagent/config.json`. This file survives across sessions and works in every context — Claude Code, Claude Desktop, MCP servers, etc.
+
+The config file has this shape:
+
+```json
+{
+ "apiKey": "asa_...",
+ "accountId": "1234567890"
+}
+```
+
+## Onboarding
+
+Before doing anything else, check whether the user is set up. Follow these steps in order — stop at the first issue and resolve it before continuing.
+
+### Step 0: Check for the AdsAgent MCP server
+
+Follow the **MCP Server Detection** section above. If no MCP server is found, guide the user through setup before continuing.
+
+### Step 1: Check for token
+
+Read `~/.adsagent/config.json` (create `~/.adsagent/` if it doesn't exist).
+
+Look for `apiKey` (the token) in the config file. If it's present, skip to Step 2.
+
+If it's missing, tell the user:
+
+> To use AdsAgent, you need a free token. You can get one from [adsagent.org](https://www.adsagent.org).
+> Once you have it, paste it here and I'll save it for you.
+
+When the user provides the key, save it to `~/.adsagent/config.json`.
+
+Then continue to Step 2.
+
+### Step 2: Select a Google Ads account
+
+Look for `accountId` in the config file. If it's present, proceed to fulfil the user's request.
+
+If `accountId` is not set:
+
+1. Run `listConnectedAccounts` to get all connected Google Ads accounts.
+2. **If there is exactly one account**, save it automatically — no need to bother the user. Write `accountId` to `~/.adsagent/config.json` and tell the user which account was selected (show account name and ID).
+3. **If there are multiple accounts**, present them as a numbered list showing account name and ID, then ask the user to pick one. Save their choice to `~/.adsagent/config.json`.
+4. **If there are zero accounts**, tell the user they don't have any Google Ads accounts connected yet and direct them to [adsagent.org](https://www.adsagent.org) to connect one.
+
+### Switching accounts
+
+If the user wants to switch accounts, run `listConnectedAccounts`, let them pick, and update `accountId` in `~/.adsagent/config.json`.
+
+## Calling tools
+
+Tools are available directly via the MCP server. Call them using the detected prefix (see MCP Server Detection above).
+
+**With AdsAgent MCP (default):**
+- `mcp__adsagent__listCampaigns` with `accountId` parameter
+- `mcp__adsagent__getKeywords` with `accountId` and `campaignId`
+- etc.
+
+**With Google's official MCP:**
+- Tool names follow the `mcp__google_ads_mcp__*` pattern
+- Consult the server's tool list for exact names
+
+Always pass `accountId` from `~/.adsagent/config.json` to every tool call (except `listConnectedAccounts`). All responses are JSON.
+
+## Available Tools
+
+### Read (safe, no side effects)
+- **getAccountInfo** — Account name, currency, timezone, test status
+- **listCampaigns** — All campaigns with impressions, clicks, cost, conversions
+- **getCampaignPerformance** — Daily metrics over a date range
+- **getKeywords** — Top keywords with quality scores
+- **getSearchTermReport** — Actual search queries triggering ads
+- **runGaqlQuery** — Run a custom read-only GAQL SELECT query (max 50 rows)
+- **getChanges** — Recent AdsAgent changes with `changeId`s for undo
+- **listConnectedAccounts** — All connected Google Ads accounts
+- **getTrackingTemplate** — Current tracking template at account/campaign/ad-group/ad level
+- **listAdGroups** — Ad groups in a campaign with metrics
+- **listAds** — Ads in a campaign/ad group with copy, URLs, status, metrics
+- **getImpressionShare** — Search/top/abs-top IS and budget/rank-lost IS
+- **getConversionActions** — Conversion actions and settings
+- **getAccountSettings** — Auto-tagging, tracking template, conversion tracking IDs
+- **getCampaignSettings** — Bidding, network, locations, schedule
+- **getNegativeKeywords** — List negative keywords for a campaign (check before adding new negatives to avoid duplicates)
+- **getRecommendations** — Google optimization recommendations
+
+### Write (mutates the account — always confirm with user first)
+All write tools return a `changeId` on success. Use this with `undoChange` to reverse the operation within 7 days.
+- **pauseKeyword** — Stop a keyword
+- **enableKeyword** — Re-enable a paused keyword
+- **addKeyword** — Add a new keyword to an ad group
+- **updateBid** — Change CPC bid (manual/enhanced CPC only, max 25% change)
+- **addNegativeKeyword** — Block irrelevant search terms (phrase match)
+- **removeNegativeKeyword** — Remove a negative keyword
+- **updateCampaignBudget** — Change daily budget (max 50% change)
+- **createCampaign** — Create a full paused search campaign
+- **pauseCampaign** — Pause all ads in a campaign
+- **enableCampaign** — Re-enable a paused campaign
+- **setTrackingTemplate** — Set/clear tracking template
+- **createAdGroup** — Create a new ad group
+- **createAd** — Create a new Responsive Search Ad
+- **pauseAd** — Pause an ad
+- **enableAd** — Re-enable an ad
+- **updateAdFinalUrl** — Change an ad's landing page URL
+- **updateAdAssets** — Replace an RSA's headlines/descriptions (complete replacement — provide every asset, not just changed ones; optionally pin assets to positions)
+- **bulkUpdateBids** — Update up to 50 keyword bids in one call (each capped at 25% change)
+- **bulkPauseKeywords** — Pause up to 100 keywords in one call (partial success possible)
+- **bulkAddKeywords** — Add up to 100 keywords to an ad group in one call (partial success possible)
+- **moveKeywords** — Move keywords between ad groups in the same campaign (adds to destination first, pauses source on success, rolls back on failure)
+- **renameCampaign** — Rename a campaign
+- **renameAdGroup** — Rename an ad group
+- **updateCampaignSettings** — Update network targeting (Google Search, Search Partners, Display Network) and/or location targeting (add/remove geo targets by geo target constant ID, e.g. '2840' for US, '200840' for Seattle-Tacoma DMA). Also supports negative location targeting (exclusions).
+- **undoChange** — Reverse a previous write by `changeId`
+
+## Rules
+
+1. **Never make write changes without explicit user confirmation.** Always show what you plan to change, the current value, and the new value before executing.
+2. **Start with reads.** When the user asks about ads, begin with `getAccountInfo` and `listCampaigns` to build context.
+3. **Show numbers clearly.** Format cost as dollars, show CTR as percentages, include date ranges.
+4. **Recommend before acting.** When you spot waste (high-spend zero-conversion keywords, irrelevant search terms), recommend the action and wait for approval.
+5. **Guardrails are server-side.** Bid changes >25% and budget changes >50% will be rejected by the server. Don't try to circumvent this.
+6. **After every write, note the `changeId`.** Tell the user they can undo the change within 7 days. Use `getChanges` to review recent operations.
+
+## Reference Documents
+
+Before performing any analysis, read the following reference documents for expert-level context:
+
+- `references/quality-score-framework.md` — QS diagnostics and optimization playbook
+- `references/bid-strategy-decision-tree.md` — When to use which bidding strategy
+- `references/industry-benchmarks.md` — Industry-specific CPA, CTR, CPC benchmarks
+- `references/search-term-analysis-guide.md` — Search term interpretation and negative keyword strategy
+- `references/campaign-structure-guide.md` — Account structure best practices
+
+Read these at the start of any analysis or optimization session. They contain the numeric thresholds, decision trees, and industry context that separate generic advice from expert recommendations.
+
+## Analysis Heuristics
+
+When interpreting Google Ads data, apply these specific rules. Every recommendation must reference a threshold — never give vague "optimize this" advice.
+
+### Quality Score
+
+| QS Range | Monthly Spend | Action | Priority |
+|----------|--------------|--------|----------|
+| 1-4 | >$100/month | Priority fix — read `references/quality-score-framework.md` for diagnostic tree | Critical |
+| 1-4 | <$100/month | Fix if keyword is strategically important, otherwise pause and reallocate budget | Medium |
+| 5-6 | Any | Monitor — improve landing page relevance and ad copy match. Check QS subcomponents (expected CTR, ad relevance, landing page experience) to identify the bottleneck | Low |
+| 7-8 | Any | Healthy — focus on scaling. Small QS gains here have diminishing returns | None |
+| 9-10 | Any | Excellent — do not touch QS factors. Focus entirely on bid and budget optimization | None |
+
+**QS component diagnosis:**
+- Expected CTR "Below Average" → ad copy doesn't match search intent. Headlines need the keyword or a closer synonym
+- Ad Relevance "Below Average" → keyword doesn't belong in this ad group. Move it to a tighter ad group or write ad copy that matches the keyword theme
+- Landing Page Experience "Below Average" → page load speed, mobile friendliness, or content relevance issue. This is the hardest to fix from within Google Ads — flag for website team
+
+### Keyword Performance
+
+Evaluate every keyword against the account's average CPA. If the account has no conversions, use CTR and cost thresholds instead.
+
+**Accounts WITH conversion data:**
+
+| Condition | Action | Rationale |
+|-----------|--------|-----------|
+| CPA < 50% of account avg | Increase bid 15-25%. Expand to broader match types if exact-only | High performer being underleveraged |
+| CPA 50-100% of account avg | Maintain current bid. Monitor weekly | Healthy, contributing keyword |
+| CPA 100-150% of account avg | Review search terms for this keyword. Tighten match type or add negatives | Borderline — often fixable with better targeting |
+| CPA > 150% of account avg | Decrease bid 15-25%. If CPA > 200% avg after 2 weeks, pause | Underperformer dragging down account |
+| 0 conversions, >$200 spend | Pause immediately OR move to exact match with 25% lower bid | Enough data to conclude this keyword doesn't convert at current targeting |
+| 0 conversions, $100-200 spend, QS > 6 | Give 2 more weeks. Check landing page alignment and search term relevance | May need more data — QS suggests the ad/page are relevant |
+| 0 conversions, $100-200 spend, QS < 5 | Pause. QS + no conversions = wrong keyword or wrong landing page | Two signals pointing the same direction |
+| 0 conversions, <$100 spend | Too early to judge on conversions. Evaluate CTR and search term quality instead | Insufficient data for conversion-based decisions |
+| 0 impressions for 30+ days | Pause — this is a zombie keyword. Check: is the bid too low? Match type too restrictive? Keyword paused at ad group level? | Dead weight cluttering the account |
+
+**Accounts WITHOUT conversion data (no conversion tracking or <10 total conversions):**
+
+| Condition | Action |
+|-----------|--------|
+| CTR > 5% and CPC < account avg | Likely high-intent — prioritize for conversion tracking setup |
+| CTR < 1% after 500+ impressions | Poor relevance — pause or rewrite ad copy |
+| Spend > $500 total with no conversion tracking | Flag as critical: "You're spending $X with no way to measure results. Set up conversion tracking before any optimization." |
+
+### Search Terms
+
+Analyze every search term report with these rules. Cross-reference `references/search-term-analysis-guide.md` for the full relevance scoring methodology.
+
+| Condition | Action | Match Type |
+|-----------|--------|------------|
+| 3+ conversions, not already a keyword | Add as keyword | Phrase match initially — let it prove itself before going broad |
+| 1-2 conversions, relevant to business | Flag for review — add if CPA is acceptable | Exact match to control spend |
+| 0 conversions, 10+ clicks | Add as negative | Phrase match at campaign level |
+| 0 conversions, 5-9 clicks | Flag for review — check: is it relevant? Is the landing page right? | May need more data OR a landing page fix, not a negative |
+| 0 conversions, <5 clicks | Too early — skip unless clearly irrelevant | — |
+| Clearly irrelevant (competitor name, wrong service, wrong location) | Add as negative immediately regardless of click count | Exact match for competitor names, phrase match for wrong services |
+| Contains "free", "DIY", "jobs", "salary" (non-commercial intent) | Add as negative unless the business serves that intent | Phrase match at account level (shared negative list) |
+| Brand misspelling or variation | Add as keyword if not already covered | Exact match |
+
+### Impression Share
+
+Impression share tells you WHY you're not showing for searches. The combination of budget-lost and rank-lost IS reveals the root cause.
+
+**Diagnostic Matrix:**
+
+| | Rank-Lost IS < 30% | Rank-Lost IS 30-50% | Rank-Lost IS > 50% |
+|---|---|---|---|
+| **Budget-Lost IS < 20%** | Healthy — optimize at margins. Focus on bid adjustments and ad copy testing | Mixed signal — QS or bid gap on some keywords. Identify which ad groups have low QS and fix those first | QS/bid problem — ads aren't competitive enough. Check avg QS; if < 5, fix quality. If QS > 6, bids are too low |
+| **Budget-Lost IS 20-40%** | Budget constraint — campaign runs out of budget partway through the day. Increase budget 20-30% or narrow keyword targeting to focus spend on best performers | Both problems present — fix the quality/bid issue first (it's cheaper than adding budget), then reassess budget needs | Structural problem — likely bidding on keywords that are too competitive for current QS and budget. Narrow to higher-QS keywords |
+| **Budget-Lost IS > 40%** | Severe budget constraint — must address before any other optimization. Either double the budget or cut keyword count by 50%+ | Priority: fix rank issues first to get more value from existing budget, then increase budget | Account is fundamentally misaligned — targeting too many expensive keywords with too little budget and too low quality. Restructure: pick 10-20 best keywords, pause everything else, fix QS, then expand |
+
+**Campaign-level impression share rules:**
+- Search IS < 50% on a campaign spending >$1,000/month → this campaign is underserving demand. Investigate why before increasing budget
+- Abs Top IS < 10% on brand campaigns → competitors are outbidding on your brand. Increase brand campaign bids or improve brand ad QS
+- Top IS dropped >15 points month-over-month → new competitor or QS degradation. Check auction insights if available
+
+### CTR Benchmarks
+
+CTR varies dramatically by industry, match type, and ad position. Always compare against the right benchmark from `references/industry-benchmarks.md`.
+
+| Condition | Diagnosis | Action |
+|-----------|-----------|--------|
+| Search CTR < 2% (any industry) | Ad copy relevance problem — the ad doesn't match what the searcher expects | Rewrite headlines to include the keyword or closest synonym. Check if ad group is too broad (mixed intent keywords) |
+| Search CTR 2-4% | Acceptable for most industries. Check industry benchmark — some industries (legal, B2B SaaS) index higher | Compare to `references/industry-benchmarks.md`. If below industry avg, test new ad copy |
+| Search CTR > 5% but conversion rate < 2% | Ad attracts clicks but landing page doesn't deliver on the ad's promise | Audit landing page: does the headline match the ad? Is the CTA clear? Is the page mobile-friendly? Offer `/ads-landing` |
+| Search CTR > 8% | Excellent — but verify this isn't inflated by brand terms mixing with non-brand in the same campaign | Segment brand vs non-brand. If non-brand CTR is also >8%, this is genuinely strong copy |
+| Display CTR < 0.5% | Normal for display. Only flag if display is eating significant budget with no conversions | Consider pausing display network in campaign settings if it's not converting |
+| CTR declining month-over-month on stable keywords | Ad fatigue or new competitor in auction | Test new ad variants with `/ads-copy`. Check auction insights for new entrants |
+
+### Budget Allocation
+
+| Condition | Diagnosis | Action |
+|-----------|-----------|--------|
+| Daily budget < $10 with 20+ active keywords | Budget spread too thin — each keyword gets pennies | Reduce to 5-10 highest-performing keywords OR increase budget to give each keyword $0.50-1.00/day minimum |
+| Daily budget < $10 with <10 keywords | Acceptable for testing or very low-CPC niches | Monitor — ensure at least 10-15 clicks/day for meaningful data |
+| One campaign consuming >60% of budget with <40% of conversions | Budget misallocation — money flowing to the wrong campaign | Shift 20-30% of that campaign's budget to the higher-converting campaign. If no other campaign converts better, the problem is the campaign itself, not the budget split |
+| Campaign with conversions hitting budget limit daily (budget-lost IS > 30%) | Proven campaign being starved | Increase budget 25-50% (within server guardrail). This is the lowest-risk budget increase |
+| Campaign with 0 conversions after $500+ total spend | Not a budget problem — it's a targeting or conversion tracking problem | Do NOT increase budget. Audit keywords, search terms, landing pages, and conversion tracking first |
+| Account spending <$50/day total across all campaigns | Low-data environment — statistical significance takes weeks | Consolidate into fewer campaigns/ad groups. Avoid A/B tests until daily volume supports them (min 30 clicks/day per variant) |
+
+## Wasted Spend Calculation
+
+Calculate and report wasted spend on every performance review. This is the single most important metric for most accounts — it tells the user exactly how much money is being burned.
+
+### Formula
+
+```
+WASTED SPEND =
+ Keyword Waste:
+ Sum of spend on keywords where (conversions = 0 AND clicks > 10)
+ + Search Term Waste:
+ Sum of spend on search terms where relevance_score < 2
+ (use the 1-5 relevance scoring from references/search-term-analysis-guide.md)
+ + Structural Waste:
+ Spend on campaigns with Display Network enabled where display clicks > 20 AND display conversions = 0
+```
+
+### Presentation
+
+Always express wasted spend as:
+1. **Dollar amount** — "$1,247 wasted in the last 30 days"
+2. **Percentage of total spend** — "That's 23% of your $5,400 total spend"
+3. **Annualized projection** — "At this rate, ~$14,964/year"
+
+Break down by category so the user knows where to focus:
+
+```
+Wasted Spend Breakdown (Last 30 Days):
+ Non-converting keywords (8 keywords): $623 (12%)
+ Irrelevant search terms (~35 terms): $412 (8%)
+ Display network bleed (2 campaigns): $212 (4%)
+ ─────────────────────────────────────────────────
+ Total wasted: $1,247 (23% of spend)
+```
+
+## Common Workflows
+
+### "How are my ads doing?" — Performance Summary
+
+**Step 1: Pull data (parallel)**
+- `getAccountInfo` — business name, currency
+- `listCampaigns` — all campaigns with spend, clicks, conversions
+- `getImpressionShare` — traffic coverage
+- `getCampaignPerformance` — daily trends (last 30 days)
+
+**Step 2: Analyze**
+- Calculate account-level CPA, CTR, conversion rate
+- Compare each campaign's CPA to account average — flag any >150% of avg
+- Check impression share using the diagnostic matrix above
+- Identify the best performer (lowest CPA, highest conversion volume) and worst performer
+- Compare metrics to industry benchmarks from `references/industry-benchmarks.md`
+
+**Step 3: Deliver using the Report Template below**
+
+### "Find wasted spend" — Waste Audit
+
+**Step 1: Pull data (parallel)**
+- `listCampaigns` → identify top 3-5 campaigns by spend
+- `getKeywords` for each top campaign → all keywords with spend, conversions, QS
+- `getSearchTermReport` for each top campaign → actual queries
+- `getCampaignSettings` for each → check if Display Network is enabled
+- `getNegativeKeywords` for each → current negative coverage
+
+**Step 2: Analyze**
+- Apply the Wasted Spend Calculation above
+- For each non-converting keyword: check QS, check spend, check days active. Apply the keyword performance heuristics
+- For each irrelevant search term: score relevance using `references/search-term-analysis-guide.md`, calculate spend attributed
+- Check for Display Network bleed: display clicks with no conversions
+- Check for negative keyword gaps: obvious irrelevant terms not yet blocked
+
+**Step 3: Present waste breakdown with specific actions**
+For each waste source, show:
+- The keyword/term, its spend, clicks, and why it's wasteful
+- The recommended action (pause, add negative, tighten match type)
+- Expected savings if the action is taken
+
+**Step 4: Offer to execute**
+"I found $X in wasted spend. Want me to pause the non-converting keywords and add the negative keywords? I'll show you each change before making it."
+
+### "Optimize bids" — Bid Optimization
+
+**Step 1: Pull data (parallel)**
+- `getKeywords` → all keywords with CPA, CPC, conversions, QS
+- `getImpressionShare` → identify where bid increases would capture more traffic
+- `getCampaignSettings` → confirm bid strategy (manual/enhanced CPC — bid changes only work with these)
+
+**Step 2: Analyze using keyword performance heuristics**
+- Segment keywords into tiers:
+ - **Scale** (CPA < 50% avg): increase bid 15-25%
+ - **Maintain** (CPA 50-100% avg): no change
+ - **Reduce** (CPA 100-150% avg): decrease bid 10-15%, add negatives
+ - **Pause** (CPA > 200% avg or $200+ spend with 0 conversions): pause
+- Cross-reference with impression share: only increase bids on keywords where rank-lost IS > 20% (there's traffic to capture)
+- Check bid strategy compatibility: if using Target CPA or Maximize Conversions, manual bid changes are blocked — recommend bid strategy adjustment instead (see `references/bid-strategy-decision-tree.md`)
+
+**Step 3: Present bid change plan as a table**
+
+| Keyword | Current Bid | New Bid | CPA | Conv | Rationale |
+|---------|-------------|---------|-----|------|-----------|
+| ... | $2.50 | $3.00 | $18 | 12 | CPA 40% below avg, rank-lost IS 35% |
+
+**Step 4: Execute with `bulkUpdateBids` after user approval**
+
+### "Scale winning keywords" — Growth Optimization
+
+**Step 1: Pull data (parallel)**
+- `getKeywords` → find keywords with: conversions > 2, CPA < account avg, QS > 6
+- `getSearchTermReport` → find converting search terms not yet added as keywords
+- `getImpressionShare` → check how much more traffic is available
+- `getCampaignSettings` → check budget headroom
+
+**Step 2: Identify scaling opportunities**
+- **Bid increases**: Keywords with CPA < 50% avg AND rank-lost IS > 20% — room to grow
+- **Match type expansion**: Keywords converting on exact match → test phrase match to capture variations
+- **Search term mining**: Converting search terms not yet keywords → add as phrase match
+- **Budget reallocation**: Move budget from worst-performing campaign to the campaign containing these winners
+
+**Step 3: Present scaling plan with projected impact**
+For each action, estimate the impact:
+- Bid increase: "Increasing bid 20% on [keyword] could capture ~X% more impression share, estimating Y additional conversions/month at similar CPA"
+- New keyword: "Search term '[term]' converted X times at $Y CPA — adding as keyword gives you direct control over bids"
+
+### "Fix quality scores" — QS Diagnostic
+
+**Step 1: Pull data (parallel)**
+- `getKeywords` → all keywords with QS and QS subcomponents
+- `listAdGroups` → ad group structure (keyword count per group)
+- `listAds` → ad copy per ad group
+- `getSearchTermReport` → search term relevance to ad groups
+
+**Step 2: Diagnose using `references/quality-score-framework.md`**
+- Group keywords by QS: count in each 1-4, 5-6, 7-8, 9-10 bucket
+- For QS 1-4 keywords, check which subcomponent is "Below Average":
+ - Expected CTR below avg → ad copy doesn't resonate. Need `/ads-copy`
+ - Ad Relevance below avg → keyword is in the wrong ad group. Need restructure
+ - Landing Page below avg → page doesn't match intent. Need `/ads-landing`
+- Check ad group sizes: any ad group with >25 keywords likely has QS problems from mixed intent
+
+**Step 3: Present action plan prioritized by spend**
+Fix high-spend, low-QS keywords first — they waste the most money. A QS improvement from 4 to 6 typically reduces CPC by 15-25%.
+
+### "Restructure campaigns" — Account Restructure
+
+**Step 1: Pull data (parallel)**
+- `listCampaigns` → all campaigns
+- `listAdGroups` for each → ad group count and themes
+- `getKeywords` for top campaigns → keyword count and themes per ad group
+- `getCampaignSettings` → current targeting and bid strategies
+- `getNegativeKeywords` → current negative coverage
+
+**Step 2: Diagnose structural issues using `references/campaign-structure-guide.md`**
+Common problems:
+- **Mega ad groups** (>30 keywords): mixed intent kills QS. Split by keyword theme
+- **Single campaign, multiple services**: can't control budget per service. Split into service-based campaigns
+- **No geographic structure** for multi-location businesses: create location-specific campaigns
+- **Brand and non-brand mixed**: brand keywords inflate metrics, hide non-brand problems. Separate into brand vs. non-brand campaigns
+
+**Step 3: Present restructure plan**
+Show the proposed new structure as a tree:
+```
+Account
+├── [Brand] Brand Campaign ($X/day)
+│ └── Brand Terms (exact match)
+├── [Service A] [Location] ($X/day)
+│ ├── AG: Core Terms (5-10 keywords)
+│ └── AG: Long-tail (5-10 keywords)
+├── [Service B] [Location] ($X/day)
+│ └── ...
+```
+
+**Step 4: Execute incrementally**
+Use `createCampaign`, `createAdGroup`, `moveKeywords`, `bulkAddKeywords`. Always create new structure FIRST (paused), then move keywords from old to new, then enable new and pause old. This prevents any gap in ad serving.
+
+## Report Template
+
+Use this structure for every performance summary. Consistent formatting helps users compare reports over time.
+
+```
+# Google Ads Performance: [Account Name]
+**Account:** [ID] | **Period:** [date range] | **Date:** [today]
+
+## Key Metrics
+| Metric | Value | vs Prior Period | vs Industry Avg |
+|--------|-------|-----------------|-----------------|
+| Spend | $X,XXX | +X% / -X% | — |
+| Clicks | X,XXX | +X% / -X% | — |
+| Conversions | XX | +X% / -X% | — |
+| CPA | $XX.XX | +X% / -X% | $XX (industry) |
+| CTR | X.XX% | +X.X pp | X.XX% (industry) |
+| Conv Rate | X.XX% | +X.X pp | X.XX% (industry) |
+| Search Impression Share | XX% | +X pp / -X pp | — |
+
+## Campaign Breakdown
+| Campaign | Spend | Conv | CPA | CTR | Imp Share | Status |
+|----------|-------|------|-----|-----|-----------|--------|
+| [name] | $X,XXX | XX | $XX | X.X% | XX% | [Healthy/Needs Work/Critical] |
+
+## Wasted Spend (30 days)
+**Total:** $X,XXX (XX% of spend) — Annualized: ~$XX,XXX
+- Non-converting keywords: $XXX across N keywords
+- Irrelevant search terms: ~$XXX across N terms
+- Display bleed: $XXX (if applicable)
+
+## Top Issues (ranked by dollar impact)
+1. **[Specific issue]** — $XXX impact — [Root cause]
+2. **[Specific issue]** — $XXX impact — [Root cause]
+3. **[Specific issue]** — $XXX impact — [Root cause]
+
+## Recommended Actions
+| # | Action | Expected Impact | Effort | Skill |
+|---|--------|-----------------|--------|-------|
+| 1 | [Specific action] | Save $XXX/month or gain X conversions | Low/Med/High | /ads |
+| 2 | [Specific action] | ... | ... | ... |
+| 3 | [Specific action] | ... | ... | ... |
+
+## What's Working (keep doing this)
+- [Specific positive finding with numbers]
+- [Specific positive finding with numbers]
+```
+
+**Rules for the report:**
+- Every issue must have a dollar amount or conversion count attached
+- Every action must reference a specific campaign, keyword, or ad group by name
+- "vs Industry Avg" column uses benchmarks from `references/industry-benchmarks.md` — leave blank if industry is unknown
+- "vs Prior Period" compares current 30 days to previous 30 days. Use `getCampaignPerformance` with a 60-day range and split
+
+## Conditional Handoffs
+
+After any analysis, check whether another skill would better serve the user's needs. Offer handoffs proactively — the user may not know these skills exist.
+
+### Ad Copy Problems
+
+If you find CTR issues in 2+ ad groups (CTR below industry benchmark or declining month-over-month):
+
+> "I found CTR problems in [N] ad groups — [list the ad groups and their CTR]. The ad copy likely needs refreshing. Run `/ads-copy` to generate better headline and description variants with A/B testing."
+
+### Missing Business Context
+
+If `~/.adsagent/business-context.json` doesn't exist or `audit_date` is more than 90 days old:
+
+> "I don't have business context for this account (or it's stale). Run `/ads-audit` first — it builds your business profile, which improves all recommendations. I can still work without it, but recommendations will be more generic."
+
+### Keyword Gaps
+
+If the search term report shows 3+ converting search terms that aren't already keywords:
+
+> "I found [N] search terms that are converting but aren't added as keywords yet. Want me to add them? Adding them as keywords gives you direct bid control and typically improves CPA."
+
+Present the terms with their conversion data and let the user approve before adding.
+
+### Landing Page Misalignment
+
+If CTR is strong (>4%) but conversion rate is below 2% on multiple ad groups:
+
+> "Your ads are getting clicks but conversions are low — this usually means the landing page doesn't match what the ad promises. Run `/ads-landing` to audit keyword-to-landing-page alignment."
+
+### Competitive Intelligence
+
+If impression share is declining or new competitor patterns appear in auction insights:
+
+> "Your impression share dropped [X] points this period. Run `/ads-compete` to see who's entering your auctions and how to respond."
diff --git a/skills/ads/evals/evals.json b/skills/ads/evals/evals.json
new file mode 100644
index 00000000..3dc1745e
--- /dev/null
+++ b/skills/ads/evals/evals.json
@@ -0,0 +1,45 @@
+{
+ "skill_name": "ads",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Can you help me manage my Google Ads?",
+ "expected_output": "The skill checks for the AdsAgent MCP server connection, then checks for a token in ~/.adsagent/config.json, then checks for an accountId. It should not attempt to pull campaign data before completing the onboarding flow.",
+ "files": [],
+ "expectations": [
+ "The skill attempts to verify MCP server connectivity before pulling data",
+ "The skill checks for apiKey in ~/.adsagent/config.json",
+ "The skill checks for accountId before making campaign API calls",
+ "If any setup step is missing, the skill guides the user through resolution before proceeding"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Here's my Google Ads data. I have 3 campaigns:\n\n```json\n{\"campaigns\": [{\"name\": \"Brand - Acme Plumbing\", \"id\": \"111\", \"status\": \"ENABLED\", \"spend_30d\": 2400, \"clicks\": 890, \"impressions\": 12000, \"conversions\": 45, \"cpa\": 53.33, \"ctr\": 7.4}, {\"name\": \"Non-Brand - Emergency Plumbing\", \"id\": \"222\", \"status\": \"ENABLED\", \"spend_30d\": 4800, \"clicks\": 620, \"impressions\": 18000, \"conversions\": 12, \"cpa\": 400.00, \"ctr\": 3.4}, {\"name\": \"Non-Brand - Drain Cleaning\", \"id\": \"333\", \"status\": \"ENABLED\", \"spend_30d\": 1800, \"clicks\": 410, \"impressions\": 9500, \"conversions\": 18, \"cpa\": 100.00, \"ctr\": 4.3}],\n\"keywords\": [{\"campaign\": \"Non-Brand - Emergency Plumbing\", \"keyword\": \"emergency plumber near me\", \"spend\": 1200, \"clicks\": 180, \"conversions\": 8, \"cpa\": 150, \"qs\": 7}, {\"keyword\": \"24 hour plumbing service\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 1800, \"clicks\": 220, \"conversions\": 0, \"cpa\": null, \"qs\": 3}, {\"keyword\": \"plumber salary\", \"campaign\": \"Non-Brand - Emergency Plumbing\", \"spend\": 450, \"clicks\": 95, \"conversions\": 0, \"cpa\": null, \"qs\": 2}, {\"keyword\": \"drain cleaning service\", \"campaign\": \"Non-Brand - Drain Cleaning\", \"spend\": 900, \"clicks\": 210, \"conversions\": 14, \"cpa\": 64.29, \"qs\": 8}],\n\"search_terms\": [{\"term\": \"how to become a plumber\", \"clicks\": 42, \"conversions\": 0, \"spend\": 180}, {\"term\": \"plumbing apprenticeship\", \"clicks\": 28, \"conversions\": 0, \"spend\": 120}, {\"term\": \"emergency plumber seattle\", \"clicks\": 35, \"conversions\": 6, \"spend\": 210}]}\n```\n\nHow are my ads doing? What should I fix?",
+ "expected_output": "A performance analysis that identifies specific waste: the 'plumber salary' keyword ($450 spent, 0 conversions, QS 2) should be paused immediately; '24 hour plumbing service' ($1800, 0 conversions, QS 3) needs urgent attention; 'how to become a plumber' and 'plumbing apprenticeship' should be added as negative keywords. The Emergency Plumbing campaign has a $400 CPA which is far above the Drain Cleaning campaign's $100 CPA. Should recommend adding 'emergency plumber seattle' as a keyword since it has 6 conversions.",
+ "files": [],
+ "expectations": [
+ "Identifies 'plumber salary' keyword as waste — names it specifically with the $450 spend and 0 conversions",
+ "Identifies '24 hour plumbing service' as problematic — $1800 spend, 0 conversions, QS 3",
+ "Recommends adding 'how to become a plumber' and 'plumbing apprenticeship' as negative keywords",
+ "Recommends adding 'emergency plumber seattle' as a keyword since it has 6 conversions",
+ "Flags the Emergency Plumbing campaign's $400 CPA as significantly worse than Drain Cleaning's $100 CPA",
+ "Calculates or estimates wasted spend with a dollar amount",
+ "Recommendations include specific keyword names and campaign names, not generic advice"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "I have these keywords and want to optimize bids:\n\n```json\n{\"account_avg_cpa\": 85,\n\"keywords\": [{\"keyword\": \"roof repair austin\", \"bid\": 8.50, \"cpa\": 35, \"conversions\": 22, \"qs\": 9, \"imp_share\": 45}, {\"keyword\": \"roofing contractor\", \"bid\": 12.00, \"cpa\": 140, \"conversions\": 5, \"qs\": 6, \"imp_share\": 30}, {\"keyword\": \"metal roof installation\", \"bid\": 6.00, \"cpa\": 70, \"conversions\": 8, \"qs\": 7, \"imp_share\": 55}, {\"keyword\": \"roof inspection free\", \"bid\": 4.00, \"cpa\": null, \"conversions\": 0, \"clicks\": 45, \"spend\": 180, \"qs\": 4, \"imp_share\": 70}]}\n```",
+ "expected_output": "Bid optimization recommendations grounded in heuristics: 'roof repair austin' is a star performer (CPA $35 vs $85 avg, QS 9) — increase bid by 15-25% to capture more impression share (currently 45%). 'roofing contractor' has CPA 65% above average — decrease bid or fix QS. 'metal roof installation' is healthy. 'roof inspection free' has $180 spend with 0 conversions and QS 4 — pause or significantly reduce bid.",
+ "files": [],
+ "expectations": [
+ "Recommends increasing bid for 'roof repair austin' — references its CPA being well below account average",
+ "Recommends decreasing bid or pausing 'roofing contractor' — references its CPA being above account average",
+ "Identifies 'roof inspection free' as waste — $180 spend, 0 conversions, QS 4",
+ "Bid change recommendations stay within the 25% maximum guardrail",
+ "References impression share data in the analysis"
+ ]
+ }
+ ]
+}
diff --git a/skills/ads/references/bid-strategy-decision-tree.md b/skills/ads/references/bid-strategy-decision-tree.md
new file mode 100644
index 00000000..a9a37e70
--- /dev/null
+++ b/skills/ads/references/bid-strategy-decision-tree.md
@@ -0,0 +1,248 @@
+# Bid Strategy Decision Tree
+
+Systematic framework for selecting, migrating between, and troubleshooting Google Ads bidding strategies. Every recommendation includes data thresholds and concrete transition criteria.
+
+---
+
+## Master Decision Tree
+
+```
+START: What is your optimization goal?
+|
++-- Goal: Maximize conversions within a budget
+| |
+| +-- Conversion volume >= 50/month AND stable CPA (< 20% variance)
+| | --> Target CPA (tCPA)
+| |
+| +-- Conversion volume 30-49/month
+| | --> Maximize Conversions (budget-capped) — transition to tCPA once 50+/mo
+| |
+| +-- Conversion volume 15-29/month
+| | --> Enhanced CPC (eCPC) — build conversion history
+| |
+| +-- Conversion volume < 15/month
+| --> Manual CPC — gather data before automating
+|
++-- Goal: Maximize conversion value / ROAS
+| |
+| +-- Conversion value tracking in place AND 50+ conv/month
+| | --> Target ROAS (tROAS)
+| |
+| +-- Conversion value tracking in place AND 30-49 conv/month
+| | --> Maximize Conversion Value — transition to tROAS once 50+/mo
+| |
+| +-- No conversion value tracking
+| --> Set up value tracking first, use tCPA in the meantime
+|
++-- Goal: Drive traffic / brand awareness
+| |
+| +-- Brand campaign (own brand terms)
+| | --> Manual CPC or Target Impression Share (target: 95%+ top of page)
+| |
+| +-- New market / awareness play
+| | --> Maximize Clicks (with max CPC cap)
+| |
+| +-- Competitor conquesting
+| --> Manual CPC (tight control on spend) or Target Impression Share
+|
++-- Goal: Testing / new campaign launch
+ |
+ +-- Existing conversion data from other campaigns
+ | --> Maximize Conversions for 2-4 weeks, then transition
+ |
+ +-- No conversion history at all
+ --> Manual CPC for first 30 days to establish baselines
+```
+
+---
+
+## Strategy-by-Strategy Reference
+
+### Manual CPC
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | New campaigns, < 15 conversions/month, testing keyword viability, competitor campaigns needing tight spend control |
+| **Prerequisites** | None — works with zero historical data |
+| **Typical use case** | Campaign launch, niche B2B with low volume, brand defense |
+| **Pros** | Full control over every keyword bid; no learning period; predictable spend |
+| **Cons** | Time-intensive to manage; cannot react to real-time auction signals; misses user-level optimization |
+| **Key setting** | Set bids at keyword level; use ad schedule and device bid adjustments |
+| **Exit criteria** | 15+ conversions/month accumulated over 30 days --> move to eCPC |
+
+### Enhanced CPC (eCPC)
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | 15-29 conversions/month; transitioning from Manual CPC; want some automation with guardrails |
+| **Prerequisites** | Conversion tracking active; 15+ conversions in last 30 days |
+| **Typical use case** | Mid-volume lead gen, local services, building toward full automation |
+| **Pros** | Adjusts bids up/down based on conversion likelihood while respecting your base bid; lower risk than full automation |
+| **Cons** | Limited optimization ceiling; Google can raise bids beyond your manual bid; less effective than tCPA at scale |
+| **Key setting** | Set a manual base bid; Google adjusts up or down at auction time |
+| **Exit criteria** | 30+ conversions/month sustained for 60 days --> move to tCPA |
+
+### Target CPA (tCPA)
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | 30+ conversions/month (Google recommendation: 50+ for best results); stable CPA over 60 days; known target CPA |
+| **Prerequisites** | Conversion tracking active; 30+ conversions in last 30 days; CPA variance < 20% week-over-week |
+| **Typical use case** | Mature lead gen, SaaS trials, service bookings, e-commerce with uniform AOV |
+| **Pros** | Fully automated bidding optimized for conversions at your target cost; learns from auction signals you cannot access |
+| **Cons** | Needs learning period (1-2 weeks); aggressive targets = zero spend; requires sufficient conversion volume |
+| **Key settings** | Set target CPA at or slightly above (10-15%) your current average CPA to start |
+| **Common pitfalls** | Setting tCPA 30%+ below current average --> campaign stops spending. Setting tCPA too high --> overspending on low-quality conversions |
+
+**tCPA Setup Checklist:**
+- [ ] Minimum 30 conversions in last 30 days
+- [ ] Set initial tCPA = current average CPA (do NOT set aspirational target)
+- [ ] Reduce tCPA by no more than 10-15% per 2-week period
+- [ ] Do not make changes during the 1-2 week learning period
+- [ ] Ensure daily budget is at least 10x your tCPA target
+
+### Target ROAS (tROAS)
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | E-commerce with variable order values; 50+ conversions/month with value tracking; known ROAS target |
+| **Prerequisites** | Conversion value tracking (revenue per conversion); 50+ conversions in last 30 days; ROAS variance < 25% week-over-week |
+| **Typical use case** | E-commerce, multi-product retailers, travel bookings, real estate leads with scored values |
+| **Pros** | Optimizes for revenue/profit not just conversion count; smart for variable AOV businesses |
+| **Cons** | Needs more data than tCPA; sensitive to conversion value accuracy; can ignore low-value but important conversions |
+| **Key setting** | Set target ROAS at or slightly below (10%) your current average ROAS to start |
+| **When tROAS beats tCPA** | When conversion values vary 3x+ between transactions (e.g., $50 order vs. $500 order); tCPA would treat these equally, tROAS will prioritize the $500 order |
+
+### Maximize Conversions
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | Budget-constrained campaigns; new campaigns with some conversion history; when the goal is "spend this budget, get as many conversions as possible" |
+| **Prerequisites** | Conversion tracking active; defined daily budget you are willing to fully spend |
+| **Typical use case** | Campaign launch with $50-200/day budget; seasonal pushes; clearing remaining budget at end of month |
+| **Pros** | Simple setup; spends full budget; good for learning what CPA is achievable |
+| **Cons** | No CPA control — will spend entire budget regardless of CPA; can overspend early in the day; may pursue low-quality conversions |
+| **Key setting** | Set daily budget carefully — the system WILL spend it all. Optionally set a max CPA bid limit |
+| **Learning period** | 1-2 weeks. Do not judge results until 2 full weeks of data |
+
+### Maximize Clicks
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | Brand awareness campaigns; new market entry; traffic-focused goals; when you have no conversion tracking yet |
+| **Prerequisites** | None — works with zero conversion data |
+| **Typical use case** | Brand awareness, content promotion, filling top of funnel, market research |
+| **Pros** | Maximizes traffic within budget; no conversion tracking needed |
+| **Cons** | No conversion optimization; attracts clicks regardless of quality; can burn budget on low-intent queries |
+| **Key setting** | ALWAYS set a max CPC bid cap (start at 50% of your target CPC); without it, Google may pay $15+ per click |
+| **Exit criteria** | Once conversion tracking is active and 15+ conversions accumulated --> switch to Manual CPC or eCPC |
+
+### Target Impression Share
+
+| Attribute | Detail |
+|-----------|--------|
+| **When to use** | Brand campaigns (target 95%+ IS); competitive positioning; when visibility matters more than CPA |
+| **Prerequisites** | None, but works best with known competitive landscape |
+| **Typical use case** | Brand defense, competitor conquesting, product launches |
+| **Placement options** | Anywhere on page / Top of page / Absolute top of page |
+| **Pros** | Guarantees visibility; protects brand terms from competitors |
+| **Cons** | Expensive if targeting high IS on competitive terms; no conversion optimization |
+| **Key setting** | Set max CPC cap to prevent runaway costs; target IS: 95% for brand, 50-70% for competitive |
+
+---
+
+## Migration Paths
+
+### Standard Migration Ladder
+
+| Step | From | To | Minimum Data Threshold | Timeline |
+|------|------|----|----------------------|----------|
+| 1 | Manual CPC | Enhanced CPC | 15+ conversions in 30 days | After 30-60 days of data |
+| 2 | Enhanced CPC | Target CPA | 30+ conversions in 30 days, CPA variance < 20% | After 60 days on eCPC |
+| 3 | Target CPA | Target ROAS | 50+ conversions in 30 days + value tracking active | When conversion values vary 3x+ |
+| Alt | Manual CPC | Maximize Conversions | Conversion tracking active, fixed budget | When budget is set and you want to skip eCPC |
+| Alt | Maximize Conversions | Target CPA | 30+ conversions in 30 days from Max Conv data | After 2-4 weeks of Max Conv data |
+
+### Migration Safety Rules
+
+| Rule | Why |
+|------|-----|
+| Never skip more than one step in the ladder (e.g., Manual --> tROAS) | Insufficient data leads to erratic bidding and wasted spend |
+| Never change bid strategy AND campaign settings simultaneously | Impossible to diagnose what caused performance change |
+| Allow 2 full weeks after any strategy change before evaluating | Learning period needs time; early data is unreliable |
+| Never change bid strategy during seasonal peaks (Black Friday, etc.) | Algorithm relearns during your highest-value period |
+| Set initial automated targets at or above current performance | Aggressive targets cause campaigns to stop serving |
+| Keep daily budget >= 10x target CPA when using tCPA | Insufficient budget constrains the algorithm and hurts performance |
+
+---
+
+## Common Pitfalls by Strategy
+
+| Strategy | Pitfall | Symptom | Fix |
+|----------|---------|---------|-----|
+| tCPA | Target set 30%+ below current CPA | Spend drops to near zero; few impressions | Raise tCPA to current average CPA, then decrease 10% per 2 weeks |
+| tCPA | Daily budget < 5x tCPA target | Inconsistent daily spend; algorithm cannot optimize | Increase budget to 10-15x tCPA target |
+| tROAS | Inaccurate conversion values | ROAS looks great but revenue doesn't match | Audit conversion tracking; verify values match actual revenue |
+| tROAS | Target set 50%+ above current ROAS | Zero spend, similar to tCPA with too-low target | Set tROAS at 90% of current average, increase 10% per 2 weeks |
+| Max Conversions | No budget cap awareness | Entire monthly budget spent in first week | Set daily budget = monthly budget / 30; monitor daily spend |
+| Max Conversions | Low-quality conversions | High conversion count but poor lead quality | Add a max CPA bid limit; consider switching to tCPA |
+| Max Clicks | No max CPC cap set | Single clicks costing $10-20+ | Always set max CPC cap at 50-75% of target CPC |
+| eCPC | Ad groups with mixed intent keywords | Google overbids on irrelevant close variants | Tighten ad groups; add negative keywords |
+| Manual CPC | Bids not updated in 30+ days | Missing auction changes, losing impression share | Review bids weekly or switch to automated strategy |
+| Target IS | No max CPC cap on competitive terms | CPC spirals to 3-5x normal | Set max CPC cap; accept lower IS on expensive terms |
+
+---
+
+## Portfolio vs. Standard Bid Strategies
+
+| Attribute | Standard (Campaign-level) | Portfolio (Shared across campaigns) |
+|-----------|--------------------------|-------------------------------------|
+| **Scope** | One campaign | Multiple campaigns share one strategy |
+| **When to use** | Campaign has 50+ conversions/month alone | Individual campaigns have < 30 conversions/month but combined total is 50+ |
+| **Data pooling** | Campaign data only | Pools conversion data across all campaigns in the portfolio |
+| **Budget** | Per-campaign budget | Per-campaign budgets still; strategy optimizes across them |
+| **Best for** | High-volume campaigns | Low-volume campaigns that share a common goal (same CPA target, same ROAS target) |
+| **Avoid when** | N/A | Campaigns have very different CPAs/ROAS targets; different business goals; different conversion types |
+| **Example** | Single e-commerce campaign doing 100 conversions/month on tROAS | 5 service-area campaigns each doing 10 conversions/month, combined into a tCPA portfolio at $50 |
+
+### Portfolio Strategy Decision Rule
+
+```
+IF single campaign conversions >= 50/month
+ --> Use standard (campaign-level) strategy
+
+IF single campaign conversions < 30/month
+ AND multiple campaigns share the same conversion goal
+ AND combined conversions across those campaigns >= 50/month
+ --> Use portfolio strategy
+
+IF total conversions across all candidates < 30/month
+ --> Use Manual CPC or eCPC until volume builds
+```
+
+---
+
+## Bid Strategy Performance Evaluation
+
+### What to Measure (By Strategy)
+
+| Strategy | Primary Metric | Secondary Metric | Evaluation Window |
+|----------|---------------|-----------------|-------------------|
+| Manual CPC | CPA or ROAS | Impression share, avg. position | Weekly |
+| eCPC | CPA vs. pre-eCPC baseline | Conversion volume change | Bi-weekly |
+| tCPA | Actual CPA vs. target CPA | Conversion volume, search IS | 2-week rolling average |
+| tROAS | Actual ROAS vs. target ROAS | Revenue, conversion value | 2-week rolling average |
+| Max Conversions | CPA trend | Total conversions, budget utilization | Weekly |
+| Max Clicks | CPC trend, traffic volume | Click quality (bounce rate, time on site) | Weekly |
+| Target IS | Actual IS vs. target IS | CPC trend, budget utilization | Weekly |
+
+### When to Intervene
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| CPA > target by 20%+ for 2+ weeks | Sustained overshoot past learning period | Raise tCPA target by 10%; check for conversion tracking issues |
+| Conversion volume drops > 30% | Algorithm may be too constrained | Raise target CPA/lower target ROAS; check for budget limits |
+| "Learning" status persists > 3 weeks | Not enough conversion data | Broaden targeting; increase budget; consider less aggressive strategy |
+| "Learning limited" status | Budget or targeting too restrictive | Increase budget to 10x+ tCPA; expand audience/keywords |
+| CPA < target by 30%+ | Potential to scale | Decrease tCPA by 10% to improve volume; or increase budget |
+| Impression share < 50% on brand terms | Competitors bidding on your brand | Switch brand campaign to Target IS at 95% |
diff --git a/skills/ads/references/campaign-structure-guide.md b/skills/ads/references/campaign-structure-guide.md
new file mode 100644
index 00000000..0d56d4ac
--- /dev/null
+++ b/skills/ads/references/campaign-structure-guide.md
@@ -0,0 +1,255 @@
+# Campaign Structure Guide
+
+Account structure best practices for Google Ads. Covers campaign organization, ad group design, naming conventions, budget allocation, and settings. Every recommendation includes concrete thresholds and decision criteria.
+
+---
+
+## Ad Group Strategy: SKAG vs. STAG vs. Themed
+
+### Evolution of Ad Group Strategy
+
+| Era | Strategy | Keywords per Ad Group | Rationale | Current Status |
+|-----|----------|-----------------------|-----------|----------------|
+| 2012-2017 | **SKAG** (Single Keyword Ad Groups) | 1 | Maximize ad relevance; exact control over which ad shows for which keyword | **Deprecated** — close variants and smart bidding made this counterproductive |
+| 2017-2020 | **STAG** (Single Theme Ad Groups) | 3-7 | Group close variants; reduce account complexity while maintaining relevance | **Transitional** — still viable but often too granular |
+| 2020-present | **Themed Ad Groups** | 10-20 | Leverage smart bidding; consolidate conversion data; match Google's AI-driven auction system | **Current best practice** |
+
+### Why SKAGs No Longer Work
+
+| Problem | Explanation |
+|---------|------------|
+| Close variants eliminated keyword-level control | Google matches exact match keywords to synonyms, paraphrases, and implied-intent queries regardless of ad group structure |
+| Data fragmentation kills smart bidding | A SKAG with 5 conversions/month cannot feed tCPA effectively; the same 50 conversions consolidated into one themed ad group can |
+| Account management overhead | 500 SKAGs = 500 ad groups to manage, each needing unique ads; 25 themed groups covers the same keywords with 95% less maintenance |
+| Google rewards consolidation | Google's recommendation engine and smart bidding algorithms perform better with fewer, larger ad groups |
+
+### Current Recommendation: Themed Ad Groups
+
+| Parameter | Guideline |
+|-----------|-----------|
+| Keywords per ad group | 10-20 closely themed keywords |
+| Theme definition | Keywords should share the same intent AND could be answered by the same landing page |
+| Ads per ad group | 2-3 RSAs (Responsive Search Ads) |
+| Landing page | 1 primary landing page per ad group (all keywords should be relevant to that page) |
+| Match types | Mix of exact and phrase match within the same ad group is fine; broad match only with smart bidding |
+
+### Theme Grouping Examples
+
+| Business | Theme | Keywords in Ad Group | Landing Page |
+|----------|-------|---------------------|-------------|
+| Plumbing | Emergency repair | emergency plumber, 24 hour plumber, plumber emergency service, urgent plumbing repair, after hours plumber | /emergency-plumbing |
+| Plumbing | Drain cleaning | drain cleaning service, clogged drain repair, drain unclogging, sewer line cleaning, blocked drain plumber | /drain-cleaning |
+| SaaS | Free trial | [brand] free trial, try [brand] free, [brand] demo, test [brand], [brand] trial account | /free-trial |
+| SaaS | Pricing | [brand] pricing, [brand] cost, [brand] plans, how much is [brand], [brand] subscription price | /pricing |
+| E-commerce | Running shoes men | men's running shoes, running shoes for men, male running shoes, men's jogging shoes, athletic running shoes men | /mens-running-shoes |
+
+---
+
+## Campaign Organization Patterns
+
+### When to Create Separate Campaigns
+
+Create a new campaign when you need any of these to differ:
+
+| Reason to Split | Example | Why It Requires a Separate Campaign |
+|----------------|---------|-------------------------------------|
+| **Different daily budgets** | Brand ($50/day) vs. Non-brand ($200/day) | Budget is set at campaign level |
+| **Different bid strategies** | Brand (Target IS) vs. Non-brand (tCPA) | Bid strategy is set at campaign level |
+| **Different geographic targets** | New York vs. Los Angeles | Location targeting is campaign-level |
+| **Different ad schedules** | B2B (Mon-Fri 8am-6pm) vs. B2C (all hours) | Ad schedule is campaign-level |
+| **Different networks** | Search Only vs. Search + Display | Network targeting is campaign-level |
+| **Different languages** | English vs. Spanish | Language targeting is campaign-level |
+| **Fundamentally different services** | Plumbing vs. HVAC | Different landing pages, ads, and conversion goals |
+
+### When NOT to Split Campaigns
+
+| Scenario | Why Splitting Hurts | Better Approach |
+|----------|-------------------|-----------------|
+| Splitting by match type (Exact campaign, Phrase campaign, Broad campaign) | Fragments conversion data; smart bidding needs all data in one place | Mix match types within ad groups |
+| Splitting every service into its own campaign | 20 campaigns with 5 conversions/month each = too thin for smart bidding | Group related services into one campaign with themed ad groups |
+| Splitting brand + non-brand into 10+ campaigns each | Management overhead; inconsistent settings | 1 brand campaign + 2-4 non-brand campaigns organized by service line |
+| Splitting by device (mobile campaign, desktop campaign) | Fragments data; smart bidding adjusts bids by device automatically | Use device bid adjustments within one campaign if needed |
+
+**Rule of thumb**: Fewer campaigns with more data each > more campaigns with less data each. Only split when there is a structural reason (budget, bid strategy, geo, schedule).
+
+### Standard Campaign Architecture
+
+| Campaign | Purpose | Bid Strategy | Budget Allocation |
+|----------|---------|-------------|-------------------|
+| **Brand** | Own brand terms | Target IS (95% top of page) or Manual CPC | 5-10% of total budget |
+| **Non-Brand Core** | Highest-value services/products | tCPA or tROAS | 50-60% of total budget |
+| **Non-Brand Secondary** | Lower-priority or newer services | tCPA or Maximize Conversions | 15-20% of total budget |
+| **Competitor** | Competitor brand terms (optional) | Manual CPC (tight control) | 5-10% of total budget |
+| **Testing** | New keywords, audiences, ad copy tests | Maximize Conversions or Manual CPC | 10-15% of total budget |
+| **Remarketing (Display/Search)** | Re-engage past visitors | tCPA | 5-10% of total budget |
+
+---
+
+## Naming Conventions
+
+### Convention Format
+
+```
+[Network]-[Product/Service]-[Location]-[Audience/Targeting]-[Match/Strategy]
+```
+
+### Campaign Naming Examples
+
+| Campaign Name | What It Tells You |
+|--------------|-------------------|
+| `SRC-Plumbing-Emergency-NYC-tCPA` | Search, Emergency Plumbing, New York City, Target CPA bidding |
+| `SRC-Brand-National-TargetIS` | Search, Brand terms, National targeting, Target Impression Share |
+| `SRC-HVAC-Install-Chicago-MaxConv` | Search, HVAC Installation, Chicago, Maximize Conversions |
+| `DSP-Remarketing-AllServices-National` | Display, Remarketing, All Services, National |
+| `SHP-RunningShoes-Mens-US` | Shopping, Running Shoes, Men's, United States |
+| `VID-Brand-Awareness-National` | Video (YouTube), Brand Awareness, National |
+| `PFM-LeadGen-HomeSvc-TX-tCPA` | Performance Max, Lead Gen, Home Services, Texas, tCPA |
+
+### Network Prefixes
+
+| Prefix | Network |
+|--------|---------|
+| `SRC` | Search |
+| `DSP` | Display |
+| `SHP` | Shopping |
+| `VID` | Video (YouTube) |
+| `PFM` | Performance Max |
+| `DSA` | Dynamic Search Ads |
+| `APP` | App campaigns |
+
+### Ad Group Naming Examples
+
+| Ad Group Name | Parent Campaign |
+|--------------|-----------------|
+| `Emergency-Plumber-General` | SRC-Plumbing-Emergency-NYC-tCPA |
+| `Emergency-Plumber-24Hour` | SRC-Plumbing-Emergency-NYC-tCPA |
+| `Emergency-Plumber-Burst-Pipe` | SRC-Plumbing-Emergency-NYC-tCPA |
+| `Brand-Exact` | SRC-Brand-National-TargetIS |
+| `Brand-Phrase` | SRC-Brand-National-TargetIS |
+| `Competitor-AcmePlumbing` | SRC-Competitor-NYC-ManualCPC |
+
+---
+
+## Budget Allocation Framework
+
+### The 70/20/10 Model
+
+| Tier | Allocation | Purpose | Campaign Types |
+|------|-----------|---------|----------------|
+| **Proven (70%)** | 70% of total budget | Campaigns with established CPA/ROAS that consistently deliver | Brand, core non-brand with 60+ days of data |
+| **Testing (20%)** | 20% of total budget | Campaigns being optimized or scaling into new areas | New service lines, new geo expansions, bid strategy tests |
+| **Experimental (10%)** | 10% of total budget | High-risk, high-reward experiments | Competitor campaigns, new match types, new networks, DSA |
+
+### Budget Allocation by Campaign Type
+
+| Campaign Type | % of Total Budget | Minimum Daily Budget | Rationale |
+|--------------|-------------------|---------------------|-----------|
+| Brand | 5-10% | $10/day or 10x brand CPC | Protect brand; high ROAS; don't underfund |
+| Non-Brand Core | 50-60% | 10x target CPA | Main revenue driver; needs scale |
+| Non-Brand Secondary | 15-20% | 5x target CPA | Growth channel; needs enough to learn |
+| Competitor | 5-10% | 5x competitor CPC | Higher CPC; cap spend tightly |
+| Testing / Experimental | 10-15% | 10x expected CPC | Enough to gather statistically meaningful data |
+| Remarketing | 5-10% | $20/day minimum | High ROI; often underfunded |
+
+### Budget Sufficiency Test
+
+```
+Minimum daily budget per campaign = Target CPA x 10
+
+If budget < CPA x 5:
+ Campaign is critically underfunded. Smart bidding cannot learn.
+ Action: Increase budget or consolidate into another campaign.
+
+If budget = CPA x 5-10:
+ Campaign is minimally funded. Results will be inconsistent.
+ Action: Acceptable for testing phase; increase for scaling.
+
+If budget >= CPA x 10:
+ Campaign is properly funded. Smart bidding can optimize.
+ Action: Monitor performance; scale if CPA is at target.
+
+If budget >= CPA x 20:
+ Campaign has headroom. Smart bidding has room to explore.
+ Action: Best scenario for automated bidding; expect stable results.
+```
+
+---
+
+## Ad Group Structure Checklist
+
+| Element | Guideline | Why |
+|---------|-----------|-----|
+| Keywords per ad group | 10-20 tightly themed | Enough data for smart bidding; tight enough for ad relevance |
+| RSAs per ad group | 2-3 | Google recommends 1+ RSA; 2-3 gives testing variety. More than 3 fragments impressions |
+| Unique headlines per RSA | 8-15 (Google's maximum) | More headlines = more combinations for Google to test |
+| Unique descriptions per RSA | 4 (Google's maximum) | Include keyword, benefits, CTA, and social proof |
+| Landing page per ad group | 1 primary URL | All keywords in the group should be relevant to this page |
+| Extensions | At minimum: 4 sitelinks, 4 callouts, 1 structured snippet | Extensions increase ad real estate and CTR by 10-20% |
+
+### RSA Best Practices
+
+| Element | Requirements |
+|---------|-------------|
+| Headline 1 | Must contain the primary keyword or close variant |
+| Headline 2 | Unique value proposition or benefit |
+| Headline 3 | CTA or trust signal |
+| Headlines 4-15 | Variations: numbers, questions, urgency, different benefits, brand name |
+| Description 1 | Expand on the value prop; include keyword naturally |
+| Description 2 | CTA + differentiator (guarantee, free quote, years in business) |
+| Pin sparingly | Only pin Headline 1 (for keyword relevance) and Description 1 (for primary message). Pinning reduces Google's ability to optimize combinations |
+
+---
+
+## Campaign Settings Checklist
+
+Review these settings for every new campaign. Incorrect defaults waste budget.
+
+| Setting | Recommended Value | Default (Beware) | Why It Matters |
+|---------|-------------------|-------------------|----------------|
+| **Networks** | Search only (uncheck Display and Search Partners) | Search + Display + Partners (checked) | Display and Partners have very different performance; run them as separate campaigns |
+| **Location targeting** | "Presence: People in or regularly in your targeted locations" | "Presence or interest" (default) | "Interest" shows ads to people searching ABOUT your location but not IN it; wastes budget for local businesses |
+| **Location exclusion** | "Presence: People in your excluded locations" | Same as targeting | Ensure excluded locations are actually excluded |
+| **Language** | Target your audience's language(s) only | All languages (sometimes default) | Prevent ads showing for queries in languages you don't serve |
+| **Ad rotation** | "Optimize: Prefer best performing ads" | Optimize (default is fine) | Let Google's algorithm pick the best ad combination |
+| **Start / end dates** | Set end dates for promotions; no end date for evergreen | No end date (default) | Promotional campaigns should auto-stop |
+| **Ad schedule** | Set to business hours if B2B; 24/7 if B2C with online conversion | 24/7 (default) | B2B: Why pay for 2am clicks? B2C: online conversions happen at all hours |
+| **Device targeting** | All devices (use bid adjustments if needed) | All devices (default is fine) | Smart bidding adjusts by device; manual campaigns may need mobile bid adjustment |
+| **Brand exclusions** | Exclude own brand from non-brand campaigns | None (default) | Prevent brand queries from inflating non-brand campaign performance metrics |
+| **Dynamic search ads** | Off unless intentionally using DSA | Sometimes on by default | DSA can match to unexpected pages; use only when deliberately set up |
+
+### Location Targeting Detail
+
+| Business Type | Location Setting | Target Radius / Areas |
+|--------------|-----------------|----------------------|
+| Local service (plumber, dentist) | Presence only | 15-30 mile radius around service area |
+| Regional business | Presence only | State or metro area |
+| National e-commerce | Presence only | Entire country |
+| International | Presence only | Specific countries; separate campaigns per country/language |
+| Local + willing to travel | Presence only | Primary area (tight radius) + Secondary area (wider radius, separate campaign with lower bids) |
+
+---
+
+## When to Restructure an Account
+
+### Red Flags That Indicate Structural Problems
+
+| Signal | Likely Structural Issue | Restructure Action |
+|--------|------------------------|-------------------|
+| 50% of campaigns have < 10 conversions/month | Over-segmentation; data too thin for smart bidding | Consolidate campaigns with same goal into fewer campaigns |
+| Ad groups have 50+ keywords each | Under-segmentation; ads cannot be relevant to all keywords | Split into themed groups of 10-20 keywords |
+| Same keyword appears in 3+ campaigns | Keyword cannibalization; campaigns compete against each other | Deduplicate; assign each keyword to one campaign/ad group |
+| Brand and non-brand mixed in same campaign | Inflated performance metrics; budget allocation unclear | Separate brand into its own campaign |
+| Display network checked on Search campaigns | Display traffic mixed with search; metrics are muddled | Uncheck Display; run Display as separate campaign if needed |
+| Location set to "Presence or interest" for local business | Paying for out-of-area clicks | Change to "Presence" only |
+| No negative keyword lists applied | Wasting spend on irrelevant queries | Build and apply universal negative lists |
+| Campaign names are inconsistent | Impossible to filter, sort, or analyze by dimension | Rename all campaigns using consistent naming convention |
+
+### Restructure Priority Order
+
+1. **Fix campaign settings** (networks, locations, language) -- immediate impact, zero cost
+2. **Separate brand from non-brand** -- clarifies performance data
+3. **Build and apply negative keyword lists** -- stops wasted spend within days
+4. **Consolidate thin campaigns** -- feeds smart bidding with better data
+5. **Reorganize ad groups** -- improves ad relevance and QS
+6. **Rewrite ad copy** -- matches new structure with relevant messaging
+7. **Update landing pages** -- align with new ad group themes
diff --git a/skills/ads/references/industry-benchmarks.md b/skills/ads/references/industry-benchmarks.md
new file mode 100644
index 00000000..c9a4de24
--- /dev/null
+++ b/skills/ads/references/industry-benchmarks.md
@@ -0,0 +1,211 @@
+# Google Ads Industry Performance Benchmarks
+
+Industry-specific benchmarks for Google Ads performance evaluation. Data ranges based on widely-published WordStream, Google, and LOCALiQ industry reports (2024-2025). Use these as diagnostic baselines, not absolute targets.
+
+---
+
+## Important Caveat
+
+These benchmarks represent **averages across all advertisers**, including poorly optimized accounts. Well-managed accounts typically outperform these benchmarks by **30-50%** on CPA and CTR. If your performance exactly matches these averages, there is significant room for improvement. If your performance is worse than these averages, treat it as an urgent signal.
+
+---
+
+## Search Network Benchmarks by Industry
+
+| Industry | Avg CPC | Avg CTR | Avg Conv Rate | Avg CPA | Notes |
+|----------|---------|---------|---------------|---------|-------|
+| **Legal** | $6.75 | 4.4% | 7.5% | $90.00 | Highest CPC vertical; personal injury drives the average up |
+| **Insurance** | $5.50 | 4.0% | 6.0% | $92.00 | Auto and health insurance are most competitive |
+| **Finance & Banking** | $4.50 | 4.2% | 6.5% | $69.00 | Includes credit cards, loans, financial planning |
+| **B2B / Industrial** | $3.75 | 3.5% | 5.0% | $75.00 | Long sales cycles; conversion = lead, not sale |
+| **SaaS / Technology** | $4.20 | 3.8% | 4.5% | $93.00 | High CPA offset by high LTV; free trial conversions |
+| **Healthcare** | $3.25 | 4.5% | 5.5% | $59.00 | Includes dental, dermatology, urgent care |
+| **Home Services** | $3.00 | 5.0% | 8.0% | $37.50 | Plumbers, electricians, HVAC; high intent searches |
+| **Real Estate** | $2.50 | 4.8% | 3.5% | $71.00 | Low conversion rate; long consideration cycle |
+| **Education** | $3.50 | 4.2% | 5.5% | $64.00 | Online courses, degree programs, tutoring |
+| **E-commerce** | $1.50 | 4.5% | 4.0% | $37.50 | Broad range; niche e-commerce can be much cheaper |
+| **Travel & Hospitality** | $1.75 | 5.5% | 4.5% | $39.00 | Seasonal; OTAs drive up competition |
+| **Automotive** | $2.75 | 4.0% | 6.0% | $46.00 | Dealers, parts, service; local intent strong |
+
+### How to Use This Table
+
+| Your CPA vs. Industry Avg | Diagnosis | Priority Action |
+|--------------------------|-----------|-----------------|
+| CPA < 50% of industry avg | Excellent — look for scaling opportunities | Increase budget; expand keywords |
+| CPA 50-80% of industry avg | Good — optimize for incremental gains | Test new ad copy; refine landing pages |
+| CPA 80-120% of industry avg | Average — room for improvement | Audit QS; review search terms; test bid strategies |
+| CPA 120-200% of industry avg | Below average — investigate root cause | Check QS (likely < 5); audit keyword relevance; review landing pages |
+| CPA > 200% of industry avg | Critical — structural issues likely | Full account audit: conversion tracking, keyword match types, landing pages, ad relevance |
+
+---
+
+## Display Network Benchmarks by Industry
+
+| Industry | Avg CPC (Display) | Avg CTR (Display) | Avg Conv Rate (Display) | Notes |
+|----------|-------------------|-------------------|------------------------|-------|
+| **Legal** | $0.85 | 0.60% | 1.8% | Display is rarely primary channel for legal |
+| **Insurance** | $0.75 | 0.50% | 1.2% | Remarketing performs best |
+| **Finance & Banking** | $0.90 | 0.55% | 1.5% | Display for awareness; retarget converters |
+| **B2B / Industrial** | $0.70 | 0.40% | 1.0% | Low CTR is normal; focus on impression quality |
+| **SaaS / Technology** | $0.65 | 0.45% | 1.2% | Remarketing to free trial abandoners |
+| **Healthcare** | $0.55 | 0.65% | 1.5% | Managed placements on health sites perform best |
+| **Home Services** | $0.50 | 0.70% | 1.8% | Local display targeting effective |
+| **Real Estate** | $0.60 | 0.55% | 0.8% | Low conversion; use for brand building |
+| **Education** | $0.45 | 0.60% | 1.3% | Awareness campaigns for enrollment periods |
+| **E-commerce** | $0.55 | 0.70% | 1.5% | Dynamic remarketing is the primary use case |
+| **Travel & Hospitality** | $0.40 | 0.75% | 1.0% | Inspirational imagery; seasonal targeting |
+| **Automotive** | $0.50 | 0.65% | 1.2% | Dealer inventory display ads; local targeting |
+
+**Display baseline rule**: Display CTR is typically 8-12x lower than Search CTR. Display CPC is typically 3-5x lower than Search CPC. Display conversion rates are typically 3-4x lower than Search. This is normal. Display is an awareness and remarketing channel, not a direct response channel.
+
+---
+
+## Impression Share Benchmarks
+
+| Campaign Type | Target Impression Share | Acceptable IS | Red Flag IS |
+|--------------|----------------------|---------------|-------------|
+| **Brand (own brand terms)** | 90-95%+ | 80-90% | < 80% (competitors stealing your brand traffic) |
+| **Non-brand competitive** | 40-60% | 25-40% | < 25% (underspending or low QS) |
+| **Non-brand long-tail** | 60-80% | 40-60% | < 40% |
+| **Competitor terms** | 20-40% | 10-20% | N/A (low IS is expected and acceptable) |
+| **Shopping (branded products)** | 70-85% | 50-70% | < 50% |
+| **Shopping (generic terms)** | 30-50% | 15-30% | < 15% |
+
+### Impression Share Loss Diagnosis
+
+| IS Loss Type | What It Means | Fix |
+|-------------|--------------|-----|
+| **Lost IS (Budget)** > 20% | Budget runs out before end of day | Increase daily budget or reduce keyword scope |
+| **Lost IS (Budget)** 5-20% | Mild budget constraint | Acceptable if intentional; increase budget for high-ROI campaigns |
+| **Lost IS (Rank)** > 30% | Ad Rank too low (QS or bid issue) | Improve QS first (free); increase bids second (costs money) |
+| **Lost IS (Rank)** 10-30% | Moderate rank issues | Focus QS improvement on highest-volume keywords |
+| **Lost IS (Rank)** < 10% | Healthy competitive position | Monitor; no urgent action needed |
+
+---
+
+## CTR Benchmarks by Ad Position (Search Network)
+
+| Ad Position | Avg CTR (All Industries) | High-Performing Accounts | Low-Performing Accounts |
+|-------------|-------------------------|--------------------------|-------------------------|
+| Position 1 (Absolute Top) | 6.0-7.5% | 8.0-12.0% | 3.0-5.0% |
+| Position 2 (Top) | 4.0-5.5% | 6.0-8.0% | 2.0-3.5% |
+| Position 3 (Top) | 2.5-3.5% | 4.0-5.5% | 1.5-2.0% |
+| Position 4+ (Other) | 1.0-2.0% | 2.0-3.0% | 0.5-1.0% |
+
+**Interpretation**: If your ads are in Position 1 but CTR is < 5%, your ad copy is underperforming. If your CTR is 8%+ in Position 1, your ad copy is strong; focus optimization on CPA and conversion rate instead.
+
+---
+
+## Conversion Rate Benchmarks by Landing Page Type
+
+| Landing Page Type | Avg Conv Rate | Top 25% Conv Rate | Top 10% Conv Rate |
+|------------------|--------------|-------------------|-------------------|
+| Lead gen form (short, < 4 fields) | 5.0% | 8.0% | 12.0%+ |
+| Lead gen form (long, 5+ fields) | 3.0% | 5.0% | 8.0% |
+| E-commerce product page | 3.5% | 6.0% | 10.0%+ |
+| E-commerce category page | 2.0% | 3.5% | 5.5% |
+| SaaS free trial page | 4.0% | 7.0% | 11.0% |
+| SaaS demo request page | 2.5% | 4.5% | 7.0% |
+| Click-to-call (mobile) | 6.0% | 10.0% | 15.0%+ |
+| Appointment booking | 4.5% | 7.5% | 12.0% |
+
+---
+
+## Seasonal Adjustment Notes by Industry
+
+| Industry | Peak Seasons | CPC Increase During Peak | Recommendation |
+|----------|-------------|-------------------------|----------------|
+| **E-commerce** | Nov-Dec (holiday), Prime Day (Jul) | +30-60% CPC | Increase budgets 50%+ in Oct; pre-build QS in Sep |
+| **Legal** | Jan (New Year resolutions, accidents) | +10-20% CPC | Front-load January budget |
+| **Home Services** | Mar-Jun (spring), Sep-Oct (fall prep) | +20-40% CPC | Scale up in Feb; reduce Jan/Dec spend |
+| **Travel** | Jan-Feb (booking), Jun-Aug (travel) | +25-45% CPC | Bid on booking intent in Dec; travel intent in May |
+| **Education** | Aug-Sep (enrollment), Jan (spring semester) | +20-30% CPC | Campaign launch in Jul and Nov |
+| **Finance** | Jan-Apr (tax season), Oct-Dec (planning) | +15-35% CPC | Tax-related campaigns peak Jan-Mar |
+| **Healthcare** | Jan (new insurance), Sep-Oct (flu season) | +10-25% CPC | Benefits season in Q4; New Year health in Q1 |
+| **Real Estate** | Mar-Jun (spring market) | +20-35% CPC | Scale up in Feb; maintain through Jun |
+| **B2B / SaaS** | Jan-Mar (new budgets), Sep-Oct (Q4 planning) | +15-25% CPC | Align campaigns with buyer budget cycles |
+| **Insurance** | Oct-Jan (AEP/OEP for health), Mar-May (auto/home) | +30-50% CPC | Open enrollment = highest competition |
+| **Automotive** | Mar-May (spring buying), Nov-Dec (year-end deals) | +15-30% CPC | Year-end clearance campaigns |
+
+### Seasonal Budgeting Rule
+
+```
+Monthly budget = Annual budget x Seasonal weight factor
+
+Seasonal weight factor:
+ Peak month: 1.3 - 1.6x (allocate 30-60% more than average month)
+ Normal month: 0.9 - 1.1x
+ Off-peak month: 0.5 - 0.8x (reduce spend, not pause)
+
+Example: $120K annual budget, e-commerce
+ Nov: $120K x 1.5 / 12 = $15,000 (vs. $10K average)
+ Dec: $120K x 1.6 / 12 = $16,000
+ Jan: $120K x 0.7 / 12 = $7,000
+```
+
+---
+
+## Cost-Per-Conversion Benchmarks by Conversion Type
+
+Different conversion types have inherently different values. Compare your CPA to the right benchmark.
+
+| Conversion Type | Typical CPA Range | Top Performers | Notes |
+|----------------|------------------|----------------|-------|
+| Phone call (from ad) | $15-40 | $8-15 | Highest intent; best for local services |
+| Form submission (short form) | $20-60 | $10-25 | 3-5 fields; name, email, phone |
+| Form submission (long form) | $35-90 | $15-40 | 6+ fields; qualification questions reduce volume but improve lead quality |
+| E-commerce purchase | $25-75 | $10-30 | Highly variable by AOV; $25 CPA on $200 AOV is great, on $30 AOV is terrible |
+| Free trial signup | $30-100 | $15-45 | SaaS primary metric; back into this from LTV |
+| Demo request | $50-150 | $25-70 | B2B SaaS; lower volume, higher quality than free trial |
+| App install | $2-8 | $1-3 | Mobile-first businesses; quality varies widely |
+| Newsletter signup | $3-12 | $1-5 | Top of funnel; cheap but low immediate value |
+| Click-to-call (mobile) | $10-30 | $5-15 | Mobile-specific; track call duration for quality |
+| Store visit | $5-20 | $2-10 | Requires location extensions and sufficient foot traffic data |
+
+### CPA-to-LTV Ratio Guideline
+
+| Ratio (CPA / Customer LTV) | Assessment | Action |
+|---------------------------|------------|--------|
+| < 10% | Excellent — scale aggressively | Increase budget; expand keywords; test new campaigns |
+| 10-20% | Good — healthy acquisition cost | Optimize for incremental gains |
+| 20-33% | Acceptable — depends on margins | Ensure margins support this; optimize CPA down |
+| 33-50% | Caution — thin margins | Reduce CPA through QS improvement, landing page optimization |
+| > 50% | Unsustainable — acquisition cost too high | Pause low-performers; restructure; consider if paid search is the right channel |
+
+---
+
+## Mobile vs. Desktop Performance Benchmarks
+
+| Metric | Mobile Avg | Desktop Avg | Ratio | Implications |
+|--------|-----------|-------------|-------|-------------|
+| CTR | 4.1% | 3.8% | Mobile 8% higher | Mobile gets more clicks due to fewer visible results |
+| CPC | 15-25% lower than desktop | Baseline | Mobile cheaper | Opportunity for budget-constrained advertisers |
+| Conversion Rate | 2.5-3.5% | 4.0-5.5% | Desktop 40-60% higher | Desktop converts better for complex purchases |
+| CPA | 10-30% higher than desktop | Baseline | Mobile more expensive per conversion | Despite cheaper clicks, lower conv rate drives CPA up |
+| Bounce Rate | 55-65% | 35-45% | Mobile 50% higher | Mobile pages must load fast and be thumb-friendly |
+
+### Device Strategy Decision
+
+| Scenario | Recommended Device Strategy |
+|----------|---------------------------|
+| E-commerce with mobile-optimized checkout | Bid equally on all devices; mobile can perform well |
+| Lead gen with complex forms (5+ fields) | Reduce mobile bid adjustment by 10-20%; or simplify mobile form |
+| Click-to-call business (locksmith, towing) | Increase mobile bid adjustment by 20-30%; mobile is primary |
+| B2B with long consideration cycle | Reduce mobile bid adjustment by 15-25%; desktop is primary |
+| Local services with Google Maps presence | Increase mobile bid adjustment by 10-20%; "near me" is mobile-dominant |
+
+---
+
+## Quick Diagnostic: Is My Account Healthy?
+
+Score your account against these benchmarks. 4+ "At or above benchmark" = healthy. 3+ "Below benchmark" = needs immediate work.
+
+| Metric | Check Against | Your Status |
+|--------|--------------|-------------|
+| Search CTR | Industry avg CTR table | At / Above / Below benchmark |
+| Search CPA | Industry avg CPA table | At / Above / Below benchmark |
+| Brand IS | 90%+ target | At / Above / Below benchmark |
+| Non-brand IS | 40-60% target | At / Above / Below benchmark |
+| QS distribution | 30%+ at QS 7+ | At / Above / Below benchmark |
+| Conversion rate | Landing page type table | At / Above / Below benchmark |
+| Wasted spend (irrelevant search terms) | < 15% of total spend | At / Above / Below benchmark |
diff --git a/skills/ads/references/quality-score-framework.md b/skills/ads/references/quality-score-framework.md
new file mode 100644
index 00000000..5aaa9769
--- /dev/null
+++ b/skills/ads/references/quality-score-framework.md
@@ -0,0 +1,228 @@
+# Quality Score Diagnostics & Optimization Playbook
+
+Systematic framework for diagnosing, prioritizing, and improving Quality Score across Google Ads accounts. Every recommendation includes concrete thresholds and specific actions.
+
+---
+
+## Quality Score Component Breakdown
+
+Quality Score (QS) is a 1-10 keyword-level metric composed of three sub-components, each rated independently:
+
+| Component | Weight (approx.) | Rating Scale | What Google Evaluates |
+|-----------|------------------|--------------|----------------------|
+| **Expected CTR** | ~39% | Below Average / Average / Above Average | Historical CTR of the keyword normalized for ad position, extensions, and format |
+| **Ad Relevance** | ~22% | Below Average / Average / Above Average | How closely your ad copy matches the intent and language of the keyword |
+| **Landing Page Experience** | ~39% | Below Average / Average / Above Average | Page load speed, mobile-friendliness, content relevance, navigation clarity, trust signals |
+
+**Key insight**: Landing Page Experience and Expected CTR together account for ~78% of QS. Ad Relevance is the smallest factor but often the easiest to fix.
+
+---
+
+## QS Impact on Cost-Per-Click
+
+Quality Score directly modifies your actual CPC through the Ad Rank formula. Below are the approximate CPC modifiers relative to QS 5 (the neutral baseline):
+
+| Quality Score | CPC Modifier vs. QS 5 Baseline | Effective CPC at $2.00 Benchmark | Impact on Budget |
+|--------------|-------------------------------|----------------------------------|-----------------|
+| 10 | -50% discount | $1.00 | Budget stretches 2x |
+| 9 | -44% discount | $1.12 | Significant savings |
+| 8 | -37% discount | $1.26 | Strong savings |
+| 7 | -28% discount | $1.44 | Moderate savings |
+| 6 | -17% discount | $1.66 | Slight savings |
+| **5** | **Baseline (0%)** | **$2.00** | **No modifier** |
+| 4 | +25% premium | $2.50 | Noticeable waste |
+| 3 | +67% premium | $3.34 | Severe waste |
+| 2 | +150% premium | $5.00 | Critical — pause or fix |
+| 1 | +400% premium | $10.00 | Bleeding budget — immediate action |
+
+**Rule of thumb**: Every 1-point QS increase above 5 saves ~16% on CPC. Every 1-point decrease below 5 costs ~50% more on CPC.
+
+---
+
+## Diagnostic Decision Tree
+
+```
+START: Keyword Quality Score
+|
++-- QS >= 7
+| Action: Monitor. Maintain current performance. Look for QS 10 opportunities.
+|
++-- QS 5-6
+| Action: Identify the Below Average component and fix it.
+| |
+| +-- Expected CTR = Below Average
+| | Go to: Expected CTR Improvement Playbook (below)
+| |
+| +-- Ad Relevance = Below Average
+| | Go to: Ad Relevance Improvement Playbook (below)
+| |
+| +-- Landing Page Experience = Below Average
+| | Go to: Landing Page Improvement Playbook (below)
+| |
+| +-- All components = Average
+| Action: Test new ad copy with stronger CTAs and more specific headlines.
+| Target: Move one component from Average to Above Average.
+|
++-- QS 3-4
+| Action: Urgent fix. Likely 2+ components Below Average.
+| Priority: Fix Landing Page Experience first (highest weight),
+| then Expected CTR, then Ad Relevance.
+|
++-- QS 1-2
+ Action: Critical. Consider pausing the keyword.
+ Check: Is this keyword even relevant to your business?
+ If yes: Rebuild — new ad group, new ad copy, new landing page.
+ If no: Pause immediately. You are paying 2-5x market rate.
+```
+
+---
+
+## Expected CTR Improvement Playbook
+
+Expected CTR is position-adjusted, meaning Google accounts for your average position. A "Below Average" rating means your ads get fewer clicks than competitors in similar positions.
+
+### Position-Adjusted CTR Benchmarks (Search Network)
+
+| Average Position | Expected CTR Floor (Below Average threshold) | Good CTR | Excellent CTR |
+|-----------------|---------------------------------------------|----------|---------------|
+| 1.0 - 1.5 | < 4.0% | 5.0-8.0% | > 8.0% |
+| 1.5 - 2.5 | < 2.5% | 3.5-6.0% | > 6.0% |
+| 2.5 - 3.5 | < 1.5% | 2.5-4.5% | > 4.5% |
+| 3.5+ | < 1.0% | 1.5-3.0% | > 3.0% |
+
+### Fix Actions (Priority Order)
+
+| # | Action | Expected Impact | Effort |
+|---|--------|----------------|--------|
+| 1 | Add the keyword (or close variant) to Headline 1 or 2 | +15-30% CTR | Low |
+| 2 | Add sitelink extensions (minimum 4) | +10-20% CTR | Low |
+| 3 | Add callout extensions with specific benefits | +5-10% CTR | Low |
+| 4 | Add structured snippet extensions | +3-8% CTR | Low |
+| 5 | Include a number in the headline (price, percentage, count) | +10-20% CTR | Low |
+| 6 | Add urgency or scarcity language ("Limited", "Today Only") | +5-15% CTR | Low |
+| 7 | Test a question-format headline matching the search query | +5-12% CTR | Medium |
+| 8 | Review search terms — if irrelevant terms are diluting CTR, add negatives | +10-40% CTR | Medium |
+| 9 | Break the ad group into tighter themes (fewer keywords, more specific ads) | +15-25% CTR | High |
+
+### Historical CTR Analysis Checklist
+
+- [ ] Pull 90-day CTR trend — is it declining, stable, or improving?
+- [ ] Compare CTR across match types — broad match often drags down CTR via irrelevant queries
+- [ ] Check device-level CTR — mobile CTR is typically 15-25% lower than desktop
+- [ ] Review auction insights — new competitors entering can suppress CTR
+- [ ] Check if ad extensions are showing — extension eligible rate < 50% means lost CTR opportunity
+
+---
+
+## Ad Relevance Improvement Playbook
+
+Ad Relevance measures how well your ad copy matches the keyword's intent and language.
+
+### Keyword-to-Headline Alignment Rules
+
+| Scenario | Problem | Fix |
+|----------|---------|-----|
+| Keyword not in any headline | Google sees weak topical match | Add keyword or close synonym to Headline 1 or 2 |
+| Keyword in headline but different intent | Ad promises something the keyword doesn't seek | Rewrite headline to match the search intent (informational, commercial, transactional) |
+| Ad group has 30+ keywords | Impossible for 1 ad to be relevant to all keywords | Split into ad groups of 10-20 tightly themed keywords |
+| Generic ad copy across all ad groups | Same ads everywhere = low relevance for specific terms | Write unique RSAs per ad group with keyword-specific headlines |
+| Using only broad match keywords | Google matches queries far from original keyword | Review search terms; add phrase/exact match for high-value terms |
+
+### Dynamic Keyword Insertion (DKI) Guidelines
+
+| Use DKI When | Avoid DKI When |
+|-------------|---------------|
+| Ad group has 5-15 closely related keywords | Keywords are long (> 25 chars) — will truncate |
+| Keywords are grammatically clean in headline context | Keywords contain competitor brand names |
+| You want to quickly test relevance improvement | Keywords have mixed intent within the ad group |
+| Landing page is genuinely relevant to all keyword variants | Industry requires careful language (medical, legal, financial) |
+
+**DKI syntax**: `{KeyWord:Default Headline Text}` — capitalizes each word. Use `{keyword:default}` for sentence case.
+
+### Close Variant Handling
+
+Google matches exact and phrase match keywords to close variants including:
+- Misspellings, singular/plural, stemming
+- Abbreviations, acronyms
+- Implied words, paraphrases, same-intent queries
+
+**Impact on Ad Relevance**: If Google matches your keyword "running shoes" to the query "jogging sneakers," your ad copy must also cover that intent. Write headlines and descriptions that address the broader intent, not just the literal keyword.
+
+---
+
+## Landing Page Experience Improvement Playbook
+
+### Landing Page Checklist by Industry
+
+| Factor | Target (All Industries) | E-commerce Specific | Lead Gen / Services | SaaS / B2B |
+|--------|------------------------|--------------------|--------------------|------------|
+| **Page Load (LCP)** | < 2.5 seconds | < 2.0 seconds (product images) | < 2.0 seconds | < 1.5 seconds |
+| **Mobile Responsive** | 100% functional on mobile | Tap targets > 48px, cart accessible | Form auto-fills, click-to-call | Demo CTA visible without scroll |
+| **Content Relevance** | Headline mirrors ad headline | Product matches keyword exactly | Service matches keyword exactly | Feature/benefit matches keyword |
+| **Trust Signals** | HTTPS required, privacy policy visible | Reviews, ratings, security badges | Testimonials, certifications, BBB | Logos, case studies, SOC2 badge |
+| **Navigation** | Clear path to conversion | Breadcrumbs, related products | Simple form (< 5 fields) | Clear pricing, FAQ section |
+| **Interstitials** | No intrusive popups on mobile | Exit-intent only, delayed 30s+ | No popup before form completion | Gated content OK if value clear |
+| **Above-the-fold CTA** | Primary CTA visible without scroll | "Add to Cart" or "Buy Now" | "Get Quote" or "Call Now" | "Start Free Trial" or "Book Demo" |
+| **Unique Content** | Original, substantial content on page | Unique product descriptions (not mfr copy) | Unique service descriptions | Feature explanations, not just bullets |
+
+### Page Speed Quick Wins
+
+| Fix | Typical LCP Improvement | Effort |
+|-----|------------------------|--------|
+| Compress images to WebP/AVIF | -0.5 to -2.0 seconds | Low |
+| Lazy-load below-fold images | -0.3 to -1.0 seconds | Low |
+| Remove unused CSS/JS | -0.2 to -0.5 seconds | Medium |
+| Add CDN for static assets | -0.3 to -1.5 seconds | Medium |
+| Server-side render above-fold content | -0.5 to -2.0 seconds | High |
+| Upgrade hosting (shared → dedicated/cloud) | -0.5 to -3.0 seconds | High |
+
+### Landing Page Relevance Scoring
+
+Score your landing page 1-5 on each factor. Total < 15 = immediate rebuild needed.
+
+| Factor | Score 1 (Poor) | Score 3 (Acceptable) | Score 5 (Excellent) |
+|--------|---------------|---------------------|-------------------|
+| **Headline Match** | No relation to ad/keyword | Contains keyword in subhead | Exact keyword/intent in H1 |
+| **Content Depth** | Thin page (< 200 words) | Adequate content (300-500 words) | Comprehensive (500+ words, structured) |
+| **CTA Clarity** | No clear next step | CTA exists but buried | Above-fold CTA with clear value prop |
+| **Trust Elements** | No trust signals | Basic (HTTPS only) | Reviews + certifications + guarantees |
+| **Mobile UX** | Broken on mobile | Functional but clunky | Fast, thumb-friendly, optimized forms |
+
+---
+
+## QS Optimization Priority Matrix
+
+When you have limited time, prioritize fixes by impact and effort:
+
+| Priority | Component | Condition | Action | Expected QS Impact |
+|----------|-----------|-----------|--------|-------------------|
+| P0 | Landing Page | LCP > 4 seconds | Fix page speed immediately | +1 to +3 QS points |
+| P0 | Ad Relevance | Keyword not in any headline | Add keyword to Headline 1 | +1 to +2 QS points |
+| P1 | Expected CTR | CTR < position-adjusted floor | Rewrite headlines, add extensions | +1 to +2 QS points |
+| P1 | Landing Page | No HTTPS or broken mobile layout | Fix technical issues | +1 to +2 QS points |
+| P2 | Ad Relevance | Ad group has 30+ keywords | Split into tighter ad groups | +1 to +2 QS points |
+| P2 | Expected CTR | Broad match diluting CTR | Add negative keywords from search terms | +1 QS point |
+| P3 | Landing Page | Generic trust signals | Add reviews, certifications, guarantees | +0.5 to +1 QS point |
+| P3 | Expected CTR | Ad extensions not showing | Enable all relevant extension types | +0.5 to +1 QS point |
+
+---
+
+## QS Monitoring Cadence
+
+| Frequency | Action | Tool |
+|-----------|--------|------|
+| Weekly | Review keywords with QS < 5 (sorted by spend) | Keyword report, QS column |
+| Bi-weekly | Check component-level ratings for top 50 keywords by spend | Keyword report with QS sub-columns |
+| Monthly | Audit landing page speeds for all active landing pages | Google PageSpeed Insights or Lighthouse |
+| Monthly | Review search term report for irrelevant queries diluting CTR | Search terms report |
+| Quarterly | Full QS distribution analysis (% of keywords at each QS level) | Custom report or script |
+
+### QS Distribution Health Benchmarks
+
+| QS Range | Healthy Account | Needs Work | Critical |
+|----------|----------------|------------|----------|
+| QS 8-10 | > 30% of keywords | 15-30% | < 15% |
+| QS 5-7 | 50-60% of keywords | 40-50% | < 40% |
+| QS 1-4 | < 10% of keywords | 10-25% | > 25% |
+
+**Target**: A well-managed account should have 30%+ of keywords (by impression volume) at QS 7+, and fewer than 10% at QS 4 or below.
diff --git a/skills/ads/references/search-term-analysis-guide.md b/skills/ads/references/search-term-analysis-guide.md
new file mode 100644
index 00000000..894a5798
--- /dev/null
+++ b/skills/ads/references/search-term-analysis-guide.md
@@ -0,0 +1,255 @@
+# Search Term Analysis Guide
+
+Systematic framework for interpreting search term reports, mining keywords, building negative keyword lists, and maximizing paid search relevance. Every recommendation includes concrete thresholds and actionable workflows.
+
+---
+
+## Match Type Behavior Reference
+
+Understanding what Google actually matches to each match type is the foundation of search term analysis.
+
+### Match Type Definitions (Current Behavior, 2024-2025)
+
+| Match Type | Syntax | What It Matches | Example Keyword | Example Matched Queries |
+|-----------|--------|----------------|-----------------|------------------------|
+| **Broad Match** | `keyword` | Themes, intent, related concepts; uses AI to determine relevance | `plumber services` | "plumber near me", "fix leaky faucet", "emergency pipe repair", "plumbing contractor reviews" |
+| **Phrase Match** | `"keyword"` | Queries that include the meaning of the keyword; word order matters for meaning | `"plumber services"` | "plumber services near me", "affordable plumber services in austin", "residential plumber services" |
+| **Exact Match** | `[keyword]` | Queries that match the exact meaning including close variants | `[plumber services]` | "plumber services", "plumber service", "plumbing services", "services plumber" |
+
+### Close Variants (All Match Types)
+
+Google applies close variants to ALL match types. These include:
+
+| Close Variant Type | Example Keyword | Matched Query | Risk Level |
+|-------------------|-----------------|---------------|------------|
+| Misspellings | `plumber` | "plumer", "plummber" | Low — usually helpful |
+| Singular / Plural | `running shoe` | "running shoes" | Low — usually helpful |
+| Stemming | `running` | "run", "runner" | Low-Medium — check intent |
+| Abbreviations | `california` | "CA", "calif" | Low — usually helpful |
+| Accents | `cafe` | "cafe" | Low — usually helpful |
+| Implied words | `daytime tv` | "tv shows during the day" | Medium — may shift intent |
+| Synonyms | `cheap hotels` | "affordable hotels", "budget hotels" | Medium — check relevance |
+| Paraphrases | `how to fix a faucet` | "faucet repair steps" | Medium — usually OK |
+| **Same intent (broad)** | `plumber services` | "fix leaky pipe" | **High — can be very far from keyword** |
+
+### Close Variant Gotchas
+
+| Gotcha | Example | Impact | Mitigation |
+|--------|---------|--------|------------|
+| Google matches exact match to synonyms you didn't intend | `[luxury hotel]` matches "5 star resort" | May not match your landing page | Add exact negative `[5 star resort]` if landing page is hotel-specific |
+| Broad match picks up tangentially related queries | `plumber` matches "DIY pipe repair youtube" | Wasted spend on informational, non-commercial queries | Add negative keywords: "DIY", "youtube", "how to" |
+| Phrase match reorders words when Google determines same meaning | `"new york plumber"` matches "plumber in new york" | Usually fine, but check | Monitor search terms weekly |
+| Exact match singular/plural shifts intent | `[glass]` matches "glasses" (eyewear vs. material) | Completely different intent | Add negative `[glasses]` if selling glass material |
+
+---
+
+## Relevance Scoring Framework
+
+Score every search term on a 1-5 scale to prioritize actions.
+
+| Score | Label | Definition | Example (for keyword "emergency plumber") | Action |
+|-------|-------|------------|-------------------------------------------|--------|
+| **5** | Perfect Match | Query exactly matches keyword intent and is high-converting | "emergency plumber near me" | Add as keyword if not already targeted |
+| **4** | Strong Relevant | Related to keyword, clear commercial intent, likely converter | "24 hour plumber service" | Add as keyword if 2+ conversions |
+| **3** | Moderately Relevant | Related but broader intent or lower purchase signals | "plumber cost estimate" | Monitor; add as keyword if converting consistently |
+| **2** | Weakly Relevant | Tangentially related; unlikely to convert at acceptable CPA | "plumber salary", "plumber apprenticeship" | Add as negative if 10+ clicks with zero conversions |
+| **1** | Irrelevant | No relation to business or search intent | "mario plumber game", "plumber meme" | Add as negative immediately |
+
+---
+
+## Search Term Mining Workflow
+
+### Decision Rules
+
+```
+FOR EACH search term in the report:
+|
++-- Has 3+ conversions at acceptable CPA?
+| YES --> Add as keyword (exact match) in the most relevant ad group
+| NO --> Continue evaluation
+|
++-- Has 10+ clicks with 0 conversions?
+| YES --> Add as negative keyword (exact negative if one bad term;
+| phrase negative if a pattern)
+| NO --> Continue evaluation
+|
++-- Has 50+ impressions with 0 clicks?
+| YES --> Check: is the ad relevant to this query?
+| | Ad is relevant --> Query may be too broad/informational; monitor
+| | Ad is NOT relevant --> Likely in wrong ad group; check keyword/ad group mapping
+| NO --> Continue evaluation
+|
++-- Has 1-2 conversions at acceptable CPA?
+| YES --> Monitor for 30 more days; add as keyword if conversions continue
+| NO --> Continue evaluation
+|
++-- Relevance score 1-2?
+ YES --> Add as negative even without click data (proactive hygiene)
+ NO --> No action needed; review again next period
+```
+
+### Mining Frequency
+
+| Account Spend | Review Frequency | Minimum Data Window |
+|--------------|-----------------|---------------------|
+| < $1,000/month | Monthly | 30 days |
+| $1,000-$5,000/month | Bi-weekly | 14 days |
+| $5,000-$20,000/month | Weekly | 7 days |
+| > $20,000/month | Twice weekly | 3-7 days |
+
+---
+
+## Negative Keyword Strategy
+
+### Negative Match Type Selection
+
+| Negative Match Type | Syntax | What It Blocks | When to Use |
+|--------------------|--------|---------------|-------------|
+| **Negative Broad** | `free` | Any query containing the word "free" in any order | Block a single toxic word across all contexts |
+| **Negative Phrase** | `"free plumber"` | Queries containing "free plumber" in that order | Block a specific phrase but allow other uses of individual words |
+| **Negative Exact** | `[free plumber near me]` | Only that exact query | Block one specific query without risking over-blocking |
+
+### Negative Match Type Decision Tree
+
+```
+Is the word ALWAYS irrelevant regardless of context?
+ YES --> Negative broad match (e.g., "free", "jobs", "salary")
+ NO --> Continue
+
+Is the phrase irrelevant but individual words might be OK?
+ YES --> Negative phrase match (e.g., "plumber jobs" — "plumber" alone is fine)
+ NO --> Continue
+
+Is only this specific query irrelevant?
+ YES --> Negative exact match (e.g., [plumber salary in texas])
+```
+
+### Campaign-Level vs. Ad Group-Level Negatives
+
+| Level | When to Use | Example |
+|-------|------------|---------|
+| **Ad group level** | Block terms from triggering in one ad group but allow in another | "plumber" negative in HVAC ad group; still active in Plumbing ad group |
+| **Campaign level** | Block terms from the entire campaign | "jobs" negative at campaign level for all service campaigns |
+| **Negative keyword list (shared)** | Block terms across multiple campaigns | Universal exclusion list: "free", "DIY", "salary", "reddit", "youtube" |
+
+### Universal Negative Keyword Lists
+
+Build these shared lists and apply across all campaigns in the account.
+
+#### General Exclusions (Apply to All Commercial Campaigns)
+
+| Category | Negative Keywords | Match Type |
+|----------|------------------|------------|
+| **Job seekers** | jobs, careers, hiring, salary, pay, wage, resume, indeed, glassdoor, interview | Broad |
+| **Education / DIY** | how to, tutorial, DIY, learn, course, class, training, certification, school, university | Broad |
+| **Free / cheap seekers** | free, cheap, cheapest, discount code, coupon, promo code, giveaway | Broad |
+| **Information seekers** | what is, definition, meaning, wiki, wikipedia, history of | Phrase |
+| **Social / entertainment** | reddit, youtube, tiktok, pinterest, instagram, forum, meme, video | Broad |
+| **Complaints / reviews** | complaint, scam, lawsuit, ripoff, BBB, better business bureau | Broad |
+
+#### Industry-Specific Exclusion Patterns
+
+| Industry | Additional Negatives | Rationale |
+|----------|---------------------|-----------|
+| **Legal** | "pro bono", "legal aid", "free consultation" (if not offered), "law school" | Filters out non-paying prospects |
+| **Home Services** | "DIY", "home depot", "lowes", "parts", "tools" | Filters out DIYers who won't hire |
+| **SaaS** | "open source", "free alternative", "github", "self-hosted" | Filters out non-buyers |
+| **Healthcare** | "symptoms", "webmd", "home remedy", "natural cure" | Filters out info-seekers |
+| **E-commerce** | "used", "refurbished", "craigslist", "ebay", "amazon" (if not selling there) | Filters out bargain hunters and marketplace traffic |
+| **Real Estate** | "zillow", "trulia", "rent", "section 8" (if selling, not renting) | Filters out renters and portal users |
+| **Education** | "free", "scholarship", "financial aid" (if paid-only programs) | Filters out non-paying students |
+| **Finance** | "calculator", "formula", "excel template", "reddit" | Filters out DIY finance people |
+
+---
+
+## N-gram Analysis Framework
+
+N-gram analysis identifies recurring word patterns in search terms to find systematic waste or opportunity.
+
+### How to Run N-gram Analysis
+
+1. Export search term report (last 30-90 days)
+2. Split each search term into individual words (unigrams) and word pairs (bigrams)
+3. Aggregate clicks, cost, and conversions by each n-gram
+4. Sort by cost descending to find the most expensive patterns
+
+### Common High-Waste N-grams (Cross-Industry)
+
+| N-gram | Typical Waste Signal | Action |
+|--------|---------------------|--------|
+| "free" | High clicks, near-zero conversions | Add as broad negative |
+| "jobs" / "careers" | Job seekers, not customers | Add as broad negative |
+| "salary" / "pay" | Job seekers | Add as broad negative |
+| "DIY" | Will not hire/buy | Add as broad negative |
+| "reddit" | Looking for opinions, not buying | Add as broad negative |
+| "youtube" | Looking for video content | Add as broad negative |
+| "near me" | High intent if local business; irrelevant if not | Keep if local; negative if not local |
+| "reviews" | Can be high intent (commercial investigation) | Keep; optimize landing page |
+| "vs" / "versus" | Comparison shoppers; moderate intent | Keep; ensure comparison content on LP |
+| "best" | High commercial intent | Keep; prioritize in ad copy |
+| "how to" | Informational intent; low conversion | Add as phrase negative for commercial campaigns |
+| "what is" | Pure informational | Add as phrase negative |
+| "cost" / "price" / "pricing" | High commercial intent — ready to buy | Keep; ensure pricing info on LP |
+
+---
+
+## Search Term Categorization Framework
+
+Categorize search terms by intent to determine campaign-level strategy.
+
+| Category | Signal Words | Conversion Likelihood | Campaign Strategy |
+|----------|-------------|----------------------|-------------------|
+| **High-Intent Commercial** | buy, hire, cost, price, near me, quote, book, order, best + [product] | High (5-15% conv rate) | Bid aggressively; dedicated ad groups; specific landing pages |
+| **Comparison / Evaluation** | vs, compare, review, alternative, top, best + [category] | Medium (2-5% conv rate) | Moderate bids; comparison landing pages; remarketing |
+| **Informational** | how to, what is, why, guide, tutorial, tips | Low (0.5-2% conv rate) | Low bids or exclude; content marketing channel instead |
+| **Navigational** | [brand name], [competitor name], login, website | Variable | Own brand: bid high. Competitor: moderate bid with competitor LP |
+| **Irrelevant** | jobs, salary, free, DIY, meme, youtube | Near zero | Add as negative immediately |
+
+---
+
+## Search Term Report Analysis Cadence
+
+| Time Period | Analysis Task | Key Questions |
+|------------|--------------|---------------|
+| **Weekly** | Review top 50 search terms by spend | Any new irrelevant terms burning budget? |
+| **Weekly** | Check terms with 10+ clicks, 0 conversions | Are these terms worth continued investment? |
+| **Bi-weekly** | Mine converting search terms | Any new terms with 3+ conversions to add as keywords? |
+| **Monthly** | Full n-gram analysis | Any systematic waste patterns? New negative keyword lists needed? |
+| **Monthly** | Review negative keyword lists | Any over-blocking (negatives killing good traffic)? |
+| **Quarterly** | Match type performance audit | Are broad match terms converting at acceptable CPA? Should any be tightened to phrase/exact? |
+
+### Match Type Performance Evaluation
+
+| Match Type | Acceptable CPA vs. Account Avg | Action if CPA Exceeds Threshold |
+|-----------|-------------------------------|-------------------------------|
+| Exact Match | CPA <= 100% of account average | This is your baseline; if even exact is too expensive, the keyword itself is the problem |
+| Phrase Match | CPA <= 130% of account average | Review search terms; add negatives for irrelevant phrase matches |
+| Broad Match | CPA <= 160% of account average | Review search terms aggressively; consider tightening to phrase; ensure smart bidding is active |
+
+**Rule**: If broad match CPA is > 200% of exact match CPA for the same keyword, switch to phrase match. Broad match should only be used with smart bidding (tCPA or tROAS) which adjusts bids per query.
+
+---
+
+## Wasted Spend Audit
+
+### Calculating Wasted Spend
+
+```
+Wasted spend = Cost from search terms with Relevance Score 1-2
+ + Cost from search terms with 15+ clicks and 0 conversions
+ - Cost from those terms that generated assisted conversions
+
+Healthy account: Wasted spend < 10% of total spend
+Needs work: Wasted spend 10-20% of total spend
+Critical: Wasted spend > 20% of total spend
+```
+
+### Top Wasted Spend Patterns
+
+| Pattern | How to Identify | Fix |
+|---------|----------------|-----|
+| Broad match runaway | High spend, low relevance search terms, mostly from broad match keywords | Add negatives; consider switching to phrase match |
+| Wrong-intent matches | Commercial keyword matching to informational queries | Add informational signal words as negatives |
+| Competitor term leakage | Your ads showing for competitor brand names (unintentionally) | Add competitor names as exact negatives (unless conquesting) |
+| Geographic mismatch | Queries from locations you don't serve | Tighten location targeting; add location negatives |
+| Language mismatch | Queries in languages you don't serve | Check campaign language settings |
diff --git a/seo/content-writer/SKILL.md b/skills/content-writer/SKILL.md
similarity index 93%
rename from seo/content-writer/SKILL.md
rename to skills/content-writer/SKILL.md
index cb24b02c..fcca52e0 100644
--- a/seo/content-writer/SKILL.md
+++ b/skills/content-writer/SKILL.md
@@ -11,20 +11,6 @@ description: >
"listicle", or any content creation or improvement task for a website.
---
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
-
-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
-
----
-
# Content Writer
You are a senior content strategist who writes content that ranks on Google AND
@@ -78,7 +64,7 @@ If spawned by seo-analysis, this context is already provided. Use it directly.
Locate and read the content writing reference:
```bash
-CONTENT_REF=$(find ~/.claude/skills ~/.codex/skills .agents/skills -name "content-writing.md" -path "*content-writer*" 2>/dev/null | head -1)
+CONTENT_REF=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -name "content-writing.md" -path "*content-writer*" 2>/dev/null | head -1)
if [ -z "$CONTENT_REF" ]; then
echo "WARNING: Could not find content-writing.md reference"
else
diff --git a/seo/content-writer/references/content-writing.md b/skills/content-writer/references/content-writing.md
similarity index 100%
rename from seo/content-writer/references/content-writing.md
rename to skills/content-writer/references/content-writing.md
diff --git a/seo/keyword-research/SKILL.md b/skills/keyword-research/SKILL.md
similarity index 94%
rename from seo/keyword-research/SKILL.md
rename to skills/keyword-research/SKILL.md
index c92541e5..ef792705 100644
--- a/seo/keyword-research/SKILL.md
+++ b/skills/keyword-research/SKILL.md
@@ -9,20 +9,6 @@ description: >
"keyword difficulty", "content ideas", or any keyword discovery task.
---
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
-
-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
-
----
-
# Keyword Research
diff --git a/seo/keyword-research/references/example-report.md b/skills/keyword-research/references/example-report.md
similarity index 100%
rename from seo/keyword-research/references/example-report.md
rename to skills/keyword-research/references/example-report.md
diff --git a/seo/keyword-research/references/keyword-intent-taxonomy.md b/skills/keyword-research/references/keyword-intent-taxonomy.md
similarity index 100%
rename from seo/keyword-research/references/keyword-intent-taxonomy.md
rename to skills/keyword-research/references/keyword-intent-taxonomy.md
diff --git a/seo/keyword-research/references/keyword-prioritization-framework.md b/skills/keyword-research/references/keyword-prioritization-framework.md
similarity index 100%
rename from seo/keyword-research/references/keyword-prioritization-framework.md
rename to skills/keyword-research/references/keyword-prioritization-framework.md
diff --git a/seo/keyword-research/references/topic-cluster-templates.md b/skills/keyword-research/references/topic-cluster-templates.md
similarity index 100%
rename from seo/keyword-research/references/topic-cluster-templates.md
rename to skills/keyword-research/references/topic-cluster-templates.md
diff --git a/seo/meta-tags-optimizer/SKILL.md b/skills/meta-tags-optimizer/SKILL.md
similarity index 95%
rename from seo/meta-tags-optimizer/SKILL.md
rename to skills/meta-tags-optimizer/SKILL.md
index c4ae951c..4b8b7a8e 100644
--- a/seo/meta-tags-optimizer/SKILL.md
+++ b/skills/meta-tags-optimizer/SKILL.md
@@ -9,20 +9,6 @@ description: >
or any meta tag task.
---
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
-
-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
-
----
-
# Meta Tags Optimizer
This skill creates compelling, optimized meta tags that improve click-through rates from search results and enhance social media sharing. It covers title tags, meta descriptions, and social meta tags.
diff --git a/seo/meta-tags-optimizer/references/ctr-and-social-reference.md b/skills/meta-tags-optimizer/references/ctr-and-social-reference.md
similarity index 100%
rename from seo/meta-tags-optimizer/references/ctr-and-social-reference.md
rename to skills/meta-tags-optimizer/references/ctr-and-social-reference.md
diff --git a/seo/meta-tags-optimizer/references/meta-tag-code-templates.md b/skills/meta-tags-optimizer/references/meta-tag-code-templates.md
similarity index 100%
rename from seo/meta-tags-optimizer/references/meta-tag-code-templates.md
rename to skills/meta-tags-optimizer/references/meta-tag-code-templates.md
diff --git a/seo/meta-tags-optimizer/references/meta-tag-formulas.md b/skills/meta-tags-optimizer/references/meta-tag-formulas.md
similarity index 100%
rename from seo/meta-tags-optimizer/references/meta-tag-formulas.md
rename to skills/meta-tags-optimizer/references/meta-tag-formulas.md
diff --git a/seo/schema-markup-generator/SKILL.md b/skills/schema-markup-generator/SKILL.md
similarity index 95%
rename from seo/schema-markup-generator/SKILL.md
rename to skills/schema-markup-generator/SKILL.md
index c991163f..f96536af 100644
--- a/seo/schema-markup-generator/SKILL.md
+++ b/skills/schema-markup-generator/SKILL.md
@@ -9,20 +9,6 @@ description: >
page", "how to get rich snippets", or any structured data task.
---
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
-
-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
-
----
-
# Schema Markup Generator
This skill creates Schema.org structured data markup in JSON-LD format to help search engines understand your content and enable rich results in SERPs.
diff --git a/seo/schema-markup-generator/references/schema-decision-tree.md b/skills/schema-markup-generator/references/schema-decision-tree.md
similarity index 100%
rename from seo/schema-markup-generator/references/schema-decision-tree.md
rename to skills/schema-markup-generator/references/schema-decision-tree.md
diff --git a/seo/schema-markup-generator/references/schema-templates.md b/skills/schema-markup-generator/references/schema-templates.md
similarity index 100%
rename from seo/schema-markup-generator/references/schema-templates.md
rename to skills/schema-markup-generator/references/schema-templates.md
diff --git a/seo/schema-markup-generator/references/validation-guide.md b/skills/schema-markup-generator/references/validation-guide.md
similarity index 100%
rename from seo/schema-markup-generator/references/validation-guide.md
rename to skills/schema-markup-generator/references/validation-guide.md
diff --git a/seo/seo-analysis/SKILL.md b/skills/seo-analysis/SKILL.md
similarity index 97%
rename from seo/seo-analysis/SKILL.md
rename to skills/seo-analysis/SKILL.md
index ed75a118..adaf592b 100644
--- a/seo/seo-analysis/SKILL.md
+++ b/skills/seo-analysis/SKILL.md
@@ -18,20 +18,6 @@ description: >
checks to deep technical audits.
---
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: immediately follow the inline upgrade flow in the `/toprank-upgrade` skill (Step 1 onward) to auto-upgrade, then return here and continue.
-
-If the output contains `JUST_UPGRADED <old> <new>`: mention "toprank upgraded from v{old} to v{new}" briefly, then continue.
-
----
-
# SEO Analysis
You are a senior technical SEO consultant. You combine real Google Search Console
@@ -86,7 +72,7 @@ exists, enables the Search Console API, and opens the browser for Google OAuth
if needed:
```bash
-SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
python3 "$SKILL_SCRIPTS/preflight.py"
```
@@ -118,7 +104,7 @@ python3 "$SKILL_SCRIPTS/preflight.py"
## Phase 1 — Confirm Access to Google Search Console
```bash
-SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
[ -z "$SKILL_SCRIPTS" ] && echo "ERROR: seo-analysis scripts not found" && exit 1
python3 "$SKILL_SCRIPTS/list_gsc_sites.py"
```
@@ -300,7 +286,7 @@ This phase is **non-blocking** — if no CMS is configured it is silently skippe
### Detect configured CMS
```bash
-SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
CMS_DETECT_EXIT=$?
```
@@ -1131,7 +1117,7 @@ Spawn agents in parallel. Each agent receives:
Before spawning agents, locate the content writing reference:
```bash
-CONTENT_REF=$(find ~/.claude/skills ~/.codex/skills .agents/skills -name "content-writing.md" -path "*content-writer*" 2>/dev/null | head -1)
+CONTENT_REF=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -name "content-writing.md" -path "*content-writer*" 2>/dev/null | head -1)
if [ -z "$CONTENT_REF" ]; then
echo "WARNING: content-writing.md not found. Content agents will use built-in knowledge only."
else
diff --git a/seo/seo-analysis/evals/evals.json b/skills/seo-analysis/evals/evals.json
similarity index 100%
rename from seo/seo-analysis/evals/evals.json
rename to skills/seo-analysis/evals/evals.json
diff --git a/seo/seo-analysis/references/gsc_setup.md b/skills/seo-analysis/references/gsc_setup.md
similarity index 97%
rename from seo/seo-analysis/references/gsc_setup.md
rename to skills/seo-analysis/references/gsc_setup.md
index adea5a30..ac9bdda7 100644
--- a/seo/seo-analysis/references/gsc_setup.md
+++ b/skills/seo-analysis/references/gsc_setup.md
@@ -136,7 +136,7 @@ setup is needed.
## Step 5 — Verify Everything Works
```bash
-SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
python3 "$SKILL_SCRIPTS/list_gsc_sites.py"
```
diff --git a/seo/seo-analysis/scripts/analyze_gsc.py b/skills/seo-analysis/scripts/analyze_gsc.py
similarity index 100%
rename from seo/seo-analysis/scripts/analyze_gsc.py
rename to skills/seo-analysis/scripts/analyze_gsc.py
diff --git a/seo/seo-analysis/scripts/cms_detect.py b/skills/seo-analysis/scripts/cms_detect.py
similarity index 100%
rename from seo/seo-analysis/scripts/cms_detect.py
rename to skills/seo-analysis/scripts/cms_detect.py
diff --git a/seo/seo-analysis/scripts/fetch_contentful_content.py b/skills/seo-analysis/scripts/fetch_contentful_content.py
similarity index 100%
rename from seo/seo-analysis/scripts/fetch_contentful_content.py
rename to skills/seo-analysis/scripts/fetch_contentful_content.py
diff --git a/seo/seo-analysis/scripts/fetch_ghost_content.py b/skills/seo-analysis/scripts/fetch_ghost_content.py
similarity index 100%
rename from seo/seo-analysis/scripts/fetch_ghost_content.py
rename to skills/seo-analysis/scripts/fetch_ghost_content.py
diff --git a/seo/seo-analysis/scripts/fetch_strapi_content.py b/skills/seo-analysis/scripts/fetch_strapi_content.py
similarity index 100%
rename from seo/seo-analysis/scripts/fetch_strapi_content.py
rename to skills/seo-analysis/scripts/fetch_strapi_content.py
diff --git a/seo/seo-analysis/scripts/fetch_wordpress_content.py b/skills/seo-analysis/scripts/fetch_wordpress_content.py
similarity index 100%
rename from seo/seo-analysis/scripts/fetch_wordpress_content.py
rename to skills/seo-analysis/scripts/fetch_wordpress_content.py
diff --git a/seo/seo-analysis/scripts/list_gsc_sites.py b/skills/seo-analysis/scripts/list_gsc_sites.py
similarity index 100%
rename from seo/seo-analysis/scripts/list_gsc_sites.py
rename to skills/seo-analysis/scripts/list_gsc_sites.py
diff --git a/seo/seo-analysis/scripts/preflight.py b/skills/seo-analysis/scripts/preflight.py
similarity index 100%
rename from seo/seo-analysis/scripts/preflight.py
rename to skills/seo-analysis/scripts/preflight.py
diff --git a/seo/seo-analysis/scripts/preflight_contentful.py b/skills/seo-analysis/scripts/preflight_contentful.py
similarity index 100%
rename from seo/seo-analysis/scripts/preflight_contentful.py
rename to skills/seo-analysis/scripts/preflight_contentful.py
diff --git a/seo/seo-analysis/scripts/preflight_ghost.py b/skills/seo-analysis/scripts/preflight_ghost.py
similarity index 100%
rename from seo/seo-analysis/scripts/preflight_ghost.py
rename to skills/seo-analysis/scripts/preflight_ghost.py
diff --git a/seo/seo-analysis/scripts/preflight_strapi.py b/skills/seo-analysis/scripts/preflight_strapi.py
similarity index 100%
rename from seo/seo-analysis/scripts/preflight_strapi.py
rename to skills/seo-analysis/scripts/preflight_strapi.py
diff --git a/seo/seo-analysis/scripts/preflight_wordpress.py b/skills/seo-analysis/scripts/preflight_wordpress.py
similarity index 100%
rename from seo/seo-analysis/scripts/preflight_wordpress.py
rename to skills/seo-analysis/scripts/preflight_wordpress.py
diff --git a/seo/seo-analysis/scripts/push_strapi_seo.py b/skills/seo-analysis/scripts/push_strapi_seo.py
similarity index 100%
rename from seo/seo-analysis/scripts/push_strapi_seo.py
rename to skills/seo-analysis/scripts/push_strapi_seo.py
diff --git a/seo/seo-analysis/scripts/show_gsc.py b/skills/seo-analysis/scripts/show_gsc.py
similarity index 100%
rename from seo/seo-analysis/scripts/show_gsc.py
rename to skills/seo-analysis/scripts/show_gsc.py
diff --git a/seo/seo-analysis/scripts/url_inspection.py b/skills/seo-analysis/scripts/url_inspection.py
similarity index 100%
rename from seo/seo-analysis/scripts/url_inspection.py
rename to skills/seo-analysis/scripts/url_inspection.py
diff --git a/seo/setup-cms/SKILL.md b/skills/setup-cms/SKILL.md
similarity index 94%
rename from seo/setup-cms/SKILL.md
rename to skills/setup-cms/SKILL.md
index 3079b942..1d9a9ba9 100644
--- a/seo/setup-cms/SKILL.md
+++ b/skills/setup-cms/SKILL.md
@@ -25,23 +25,10 @@ invisible pages, content gaps, stale articles, and missing SEO fields.
---
-## Preamble (run first)
-
-```bash
-_UPD=$(~/.claude/skills/toprank/bin/toprank-update-check 2>/dev/null || \
- ~/.claude/skills/stockholm/bin/toprank-update-check 2>/dev/null || true)
-[ -n "$_UPD" ] && echo "$_UPD" || true
-```
-
-If the output contains `UPGRADE_AVAILABLE <old> <new>`: follow the inline
-upgrade flow in `/toprank-upgrade`, then return here and continue.
-
----
-
## Step 1 — Detect existing CMS configuration
```bash
-SKILL_SCRIPTS=$(find ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
+SKILL_SCRIPTS=$(find ~/.claude/plugins ~/.claude/skills ~/.codex/skills .agents/skills -type d -name scripts -path "*seo-analysis*" 2>/dev/null | head -1)
CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
CMS_STATUS=$?
echo "CMS_TYPE=$CMS_TYPE EXIT=$CMS_STATUS"
diff --git a/toprank-upgrade/SKILL.md b/skills/toprank-upgrade/SKILL.md
similarity index 100%
rename from toprank-upgrade/SKILL.md
rename to skills/toprank-upgrade/SKILL.md
diff --git a/test/helpers/llm_judge.py b/test/helpers/llm_judge.py
index e0d773d6..7fe59bac 100644
--- a/test/helpers/llm_judge.py
+++ b/test/helpers/llm_judge.py
@@ -1,11 +1,13 @@
"""
LLM-as-judge helpers for toprank evals.
-Requires: ANTHROPIC_API_KEY env var and `anthropic` package installed.
+Uses Gemini (cheapest option). Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.
+
+Requires: `google-genai` package installed (pip install google-genai).
"""
import json
-import re
+import os
import time
from dataclasses import dataclass
@@ -14,54 +16,70 @@ _client = None
def _get_client():
global _client
- if _client is None:
- try:
- import anthropic
- except ImportError:
- raise ImportError(
- 'anthropic package required for LLM judge — run: pip install anthropic'
- )
- _client = anthropic.Anthropic()
+ if _client is not None:
+ return _client
+
+ api_key = (
+ os.environ.get('GEMINI_API_KEY')
+ or os.environ.get('GOOGLE_GENERATIVE_AI_API_KEY')
+ )
+ if not api_key:
+ raise EnvironmentError(
+ 'No Gemini API key found. Set GEMINI_API_KEY or GOOGLE_GENERATIVE_AI_API_KEY.'
+ )
+
+ try:
+ from google import genai
+ except ImportError:
+ raise ImportError(
+ 'google-genai package required — run: pip install google-genai'
+ )
+
+ _client = genai.Client(api_key=api_key)
return _client
def call_judge(prompt: str) -> dict:
- """Call claude-sonnet-4-6, return parsed JSON. Retries up to 3 times on rate limit."""
+ """Call Gemini, return parsed JSON. Retries up to 3 times on rate limit."""
client = _get_client()
def make_request():
- return client.messages.create(
- model='claude-sonnet-4-6',
- max_tokens=1024,
- messages=[{'role': 'user', 'content': prompt}],
+ response = client.models.generate_content(
+ model=JUDGE_MODEL,
+ contents=prompt,
+ config={
+ 'response_mime_type': 'application/json',
+ 'temperature': 0.0,
+ },
)
+ return response.text
last_exc: Exception | None = None
for attempt in range(3):
try:
- response = make_request()
+ text = make_request()
break
except Exception as e:
- if getattr(e, 'status_code', None) == 429 or 'rate' in str(e).lower():
+ status = getattr(e, 'status_code', None) or getattr(e, 'code', None)
+ if status == 429 or 'rate' in str(e).lower() or 'quota' in str(e).lower():
last_exc = e
- time.sleep(2 ** attempt) # 1s, 2s, 4s
+ time.sleep(2 ** attempt)
else:
raise
else:
raise last_exc # all retries exhausted
- text = response.content[0].text if response.content[0].type == 'text' else ''
- match = re.search(r'\{[\s\S]*\}', text)
- if not match:
- raise ValueError(f'Judge returned non-JSON: {text[:200]}')
- return json.loads(match.group(0))
+ try:
+ return json.loads(text, strict=False)
+ except json.JSONDecodeError as e:
+ raise ValueError(f'Judge returned non-JSON: {text[:200]}') from e
@dataclass
class JudgeScore:
- clarity: int # 1–5: can an agent understand what to do?
- completeness: int # 1–5: is all needed info present?
- actionability: int # 1–5: can an agent act without guessing?
+ clarity: int # 1-5: can an agent understand what to do?
+ completeness: int # 1-5: is all needed info present?
+ actionability: int # 1-5: can an agent act without guessing?
reasoning: str
@@ -71,10 +89,76 @@ class SeoReportScore:
recommendations_specific: bool # Recommendations include specific URLs and query names
has_action_plan: bool # Report includes a 30-day action plan
quantified_impact: bool # At least one recommendation quantifies impact
- score: int # 1–5 overall quality
+ score: int # 1-5 overall quality
reasoning: str
+JUDGE_MODEL = 'gemini-2.0-flash'
+
+MIN_CLARITY = 4
+MIN_COMPLETENESS = 4
+MIN_ACTIONABILITY = 4
+
+
+def extract_section(md: str, start_marker: str, end_marker: str = '') -> str:
+ """Extract a section from a markdown document between two markers."""
+ start = md.find(start_marker)
+ if start == -1:
+ return ''
+ if end_marker:
+ end = md.find(end_marker, start + len(start_marker))
+ return md[start:end].strip() if end != -1 else md[start:].strip()
+ return md[start:].strip()
+
+
+def run_judge_test(
+ name: str,
+ suite: str,
+ section_label: str,
+ content: str,
+ collector,
+ min_clarity: int = MIN_CLARITY,
+ min_completeness: int = MIN_COMPLETENESS,
+ min_actionability: int = MIN_ACTIONABILITY,
+ cost_usd: float = 0.02,
+) -> JudgeScore:
+ """Run a judge test, add to collector, and assert scores. Returns the scores."""
+ import time as _time
+ t0 = _time.time()
+ assert len(content) > 100, f'{name}: section not found or too short'
+
+ scores = judge(section_label, content)
+ print(f'{name} scores:', scores)
+
+ passed = (
+ scores.clarity >= min_clarity
+ and scores.completeness >= min_completeness
+ and scores.actionability >= min_actionability
+ )
+
+ if collector:
+ from helpers.eval_store import EvalTestEntry
+ collector.add_test(EvalTestEntry(
+ name=name,
+ suite=suite,
+ tier='llm-judge',
+ passed=passed,
+ duration_ms=int((_time.time() - t0) * 1000),
+ cost_usd=cost_usd,
+ judge_scores={
+ 'clarity': scores.clarity,
+ 'completeness': scores.completeness,
+ 'actionability': scores.actionability,
+ },
+ judge_reasoning=scores.reasoning,
+ ))
+
+ assert scores.clarity >= min_clarity, f'{name}: clarity {scores.clarity} < {min_clarity}'
+ assert scores.completeness >= min_completeness, f'{name}: completeness {scores.completeness} < {min_completeness}'
+ assert scores.actionability >= min_actionability, f'{name}: actionability {scores.actionability} < {min_actionability}'
+ return scores
+
+
def judge(section: str, content: str) -> JudgeScore:
"""Score a SKILL.md section for documentation quality."""
result = call_judge(f"""You are evaluating instructions for an AI agent performing SEO analysis.
@@ -84,11 +168,11 @@ The agent reads these instructions to learn how to run a structured SEO audit. I
2. Know what tools/scripts to call and with what arguments
3. Know what the output should look like and what to include
-Rate the following {section} on three dimensions (1–5):
+Rate the following {section} on three dimensions (1-5):
-- **clarity** (1–5): Can an agent understand what each step does from the description alone?
-- **completeness** (1–5): Are commands, arguments, and expected behavior documented? Would an agent need to guess anything?
-- **actionability** (1–5): Can an agent execute this section correctly without asking follow-up questions?
+- **clarity** (1-5): Can an agent understand what each step does from the description alone?
+- **completeness** (1-5): Are commands, arguments, and expected behavior documented? Would an agent need to guess anything?
+- **actionability** (1-5): Can an agent execute this section correctly without asking follow-up questions?
Scoring guide:
- 5: Excellent — no ambiguity, all info present
diff --git a/test/helpers/touchfiles.py b/test/helpers/touchfiles.py
index af814b47..a2feff1f 100644
--- a/test/helpers/touchfiles.py
+++ b/test/helpers/touchfiles.py
@@ -12,20 +12,28 @@ from pathlib import Path
from typing import Optional
E2E_TOUCHFILES: dict[str, list[str]] = {
- 'seo-no-gsc-technical-audit': ['seo/seo-analysis/**'],
- 'seo-fixture-full-audit': ['seo/seo-analysis/**', 'test/fixtures/sample_gsc_data.json'],
- 'seo-report-quality': ['seo/seo-analysis/**', 'test/fixtures/sample_gsc_data.json'],
+ 'seo-no-gsc-technical-audit': ['skills/seo-analysis/**'],
+ 'seo-fixture-full-audit': ['skills/seo-analysis/**', 'test/fixtures/sample_gsc_data.json'],
+ 'seo-report-quality': ['skills/seo-analysis/**', 'test/fixtures/sample_gsc_data.json'],
}
LLM_JUDGE_TOUCHFILES: dict[str, list[str]] = {
- 'seo-phases-clarity': ['seo/seo-analysis/SKILL.md'],
- 'seo-report-format-clarity': ['seo/seo-analysis/SKILL.md'],
- 'seo-quick-wins-clarity': ['seo/seo-analysis/SKILL.md'],
+ 'seo-phases-clarity': ['skills/seo-analysis/SKILL.md'],
+ 'seo-report-format-clarity': ['skills/seo-analysis/SKILL.md'],
+ 'seo-quick-wins-clarity': ['skills/seo-analysis/SKILL.md'],
+}
+
+ADS_LLM_JUDGE_TOUCHFILES: dict[str, list[str]] = {
+ 'ads-heuristics-clarity': ['skills/ads/SKILL.md', 'skills/ads/references/**'],
+ 'ads-workflows-clarity': ['skills/ads/SKILL.md'],
+ 'ads-audit-scoring-clarity': ['skills/ads-audit/SKILL.md', 'skills/ads-audit/references/**'],
+ 'ads-audit-report-clarity': ['skills/ads-audit/SKILL.md'],
+ 'ads-copy-formulas-clarity': ['skills/ads-copy/SKILL.md', 'skills/ads-copy/references/**'],
}
ROUTING_TOUCHFILES: dict[str, list[str]] = {
- 'routing-seo-triggers': ['seo/seo-analysis/SKILL.md'],
- 'routing-seo-non-triggers': ['seo/seo-analysis/SKILL.md'],
+ 'routing-seo-triggers': ['skills/seo-analysis/SKILL.md'],
+ 'routing-seo-non-triggers': ['skills/seo-analysis/SKILL.md'],
}
# Changes to these files trigger all tests
diff --git a/test/install.test.sh b/test/install.test.sh
index 62ec85c6..5da91ff9 100755
--- a/test/install.test.sh
+++ b/test/install.test.sh
@@ -1,10 +1,10 @@
#!/usr/bin/env bash
-# test/install.test.sh — mock-$HOME install tests for ./setup
+# test/install.test.sh — plugin structure validation tests
#
# Usage:
# ./test/install.test.sh
#
-# Tests run in isolated temp directories. No system state is modified.
+# Validates that the toprank repo has the correct Claude Code plugin structure.
set -eo pipefail
@@ -17,19 +17,20 @@ FAIL=0
pass() { echo " PASS $1"; PASS=$((PASS + 1)); }
fail() { echo " FAIL $1"; FAIL=$((FAIL + 1)); }
-assert_link() {
+assert_file() {
local path="$1" label="$2"
- [ -L "$path" ] && pass "$label" || fail "$label — expected symlink at $path"
+ [ -f "$path" ] && pass "$label" || fail "$label — expected file at $path"
}
-assert_no_link() {
+assert_dir() {
local path="$1" label="$2"
- [ ! -L "$path" ] && pass "$label" || fail "$label — unexpected symlink at $path"
+ [ -d "$path" ] && pass "$label" || fail "$label — expected directory at $path"
}
-assert_file() {
- local path="$1" label="$2"
- [ -f "$path" ] && pass "$label" || fail "$label — expected file at $path"
+assert_json_field() {
+ local path="$1" field="$2" label="$3"
+ python3 -c "import json; d=json.load(open('$path')); assert '$field' in d" 2>/dev/null \
+ && pass "$label" || fail "$label — field '$field' not in $path"
}
assert_contains() {
@@ -37,240 +38,148 @@ assert_contains() {
grep -q "$needle" "$path" 2>/dev/null && pass "$label" || fail "$label — '$needle' not in $path"
}
-assert_exit_nonzero() {
- local code="$1" label="$2"
- [ "$code" -ne 0 ] && pass "$label" || fail "$label — expected non-zero exit"
-}
-
-run_setup() {
- (cd "$1" && ./setup "${@:2}") >/dev/null 2>&1
+assert_not_contains() {
+ local path="$1" needle="$2" label="$3"
+ ! grep -q "$needle" "$path" 2>/dev/null && pass "$label" || fail "$label — '$needle' found in $path (should not be)"
}
-# Skills that should be registered (everything with a SKILL.md).
-# This list is intentionally explicit — new skills must be added here consciously.
-# The count-check below will catch a mismatch if a skill is added to the repo
-# without updating this list.
-#
-# Format: skill_name:relative_path (name is what gets symlinked, path is source)
-SKILLS_WITH_PATHS=(
- "seo-analysis:seo/seo-analysis"
- "content-writer:seo/content-writer"
- "keyword-research:seo/keyword-research"
- "meta-tags-optimizer:seo/meta-tags-optimizer"
- "schema-markup-generator:seo/schema-markup-generator"
- "setup-cms:seo/setup-cms"
- "ads:google-ads/ads"
- "toprank-upgrade:toprank-upgrade"
+# Skills expected in skills/ directory
+SKILLS=(
+ seo-analysis
+ keyword-research
+ meta-tags-optimizer
+ schema-markup-generator
+ content-writer
+ setup-cms
+ ads
+ ads-audit
+ ads-copy
+ toprank-upgrade
)
-# Extract just skill names for iteration
-SKILLS=()
-for entry in "${SKILLS_WITH_PATHS[@]}"; do
- SKILLS+=("${entry%%:*}")
-done
-
-# Build associative-style lookup: skill_name -> relative_path
-skill_rel_path() {
- local name="$1"
- for entry in "${SKILLS_WITH_PATHS[@]}"; do
- if [ "${entry%%:*}" = "$name" ]; then
- echo "${entry#*:}"
- return
- fi
- done
-}
-
-# Guard: actual SKILL.md count must match the SKILLS array above.
-actual_skill_count=$(find "$REPO_ROOT" -maxdepth 3 -name "SKILL.md" | wc -l | tr -d ' ')
-if [ "$actual_skill_count" -ne "${#SKILLS[@]}" ]; then
- echo "ERROR: SKILLS array has ${#SKILLS[@]} entries but repo has $actual_skill_count SKILL.md files."
- echo " Update the SKILLS array in this file to match."
- exit 1
-fi
-
-# Make a fresh copy of the repo in a subdirectory of TMP (exclude .git to
-# avoid confusing git rev-parse in tests that set up their own git repo)
-clone_into() {
- local dest="$1"
- mkdir -p "$dest"
- rsync -a --exclude='.git' --exclude='.claude' "$REPO_ROOT/" "$dest/"
-}
-
-TMP="$(mktemp -d)"
-trap 'rm -rf "$TMP"' EXIT
-
-# ─── Test 1: Claude Code global install (--host claude) ───────
+# ─── Test 1: Plugin metadata exists and is valid ─────────────
echo ""
-echo "=== 1. Claude Code global install ==="
+echo "=== 1. Plugin metadata ==="
-T1="$TMP/t1"
-SKILLS_DIR="$T1/.claude/skills"
-TOPRANK_DIR="$SKILLS_DIR/toprank"
+assert_file "$REPO_ROOT/.claude-plugin/plugin.json" "plugin.json exists"
+assert_file "$REPO_ROOT/.claude-plugin/marketplace.json" "marketplace.json exists"
+assert_file "$REPO_ROOT/.mcp.json" ".mcp.json exists"
-clone_into "$TOPRANK_DIR"
-run_setup "$TOPRANK_DIR" --host claude
+assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "name" "plugin.json has name"
+assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "version" "plugin.json has version"
+assert_json_field "$REPO_ROOT/.claude-plugin/plugin.json" "skills" "plugin.json has skills path"
-for skill in "${SKILLS[@]}"; do
- assert_link "$SKILLS_DIR/$skill" "symlink created: $skill"
-done
+assert_json_field "$REPO_ROOT/.claude-plugin/marketplace.json" "plugins" "marketplace.json has plugins"
-# Each symlink must point to toprank/<relative_path>
-for skill in "${SKILLS[@]}"; do
- rel=$(skill_rel_path "$skill")
- expected_target="toprank/$rel"
- target="$(readlink "$SKILLS_DIR/$skill" 2>/dev/null || echo '')"
- [ "$target" = "$expected_target" ] \
- && pass "symlink target correct: $skill -> $expected_target" \
- || fail "symlink target wrong for $skill — got '$target', want '$expected_target'"
-done
+# Plugin version matches VERSION file
+PLUGIN_VERSION=$(python3 -c "import json; print(json.load(open('$REPO_ROOT/.claude-plugin/plugin.json'))['version'])")
+FILE_VERSION=$(cat "$REPO_ROOT/VERSION" | tr -d '[:space:]')
+[ "$PLUGIN_VERSION" = "$FILE_VERSION" ] \
+ && pass "plugin.json version ($PLUGIN_VERSION) matches VERSION file" \
+ || fail "version mismatch: plugin.json=$PLUGIN_VERSION, VERSION=$FILE_VERSION"
-# SKILL.md files (except toprank-upgrade and ads) must have preamble injected
-for skill in "${SKILLS[@]}"; do
- [ "$skill" = "toprank-upgrade" ] && continue
- [ "$skill" = "ads" ] && continue
- rel=$(skill_rel_path "$skill")
- assert_contains "$TOPRANK_DIR/$rel/SKILL.md" "toprank-update-check" "preamble injected: $skill"
-done
-
-# ─── Test 2: Auto-detect via path (no --host flag) ────────────
-
-echo ""
-echo "=== 2. Auto-detect: path ends in .claude/skills ==="
-
-T2="$TMP/t2"
-SKILLS_DIR2="$T2/.claude/skills"
-TOPRANK_DIR2="$SKILLS_DIR2/toprank"
-
-clone_into "$TOPRANK_DIR2"
-run_setup "$TOPRANK_DIR2" # no --host flag
+# marketplace.json versions must also match
+MKT_META_VERSION=$(python3 -c "import json; print(json.load(open('$REPO_ROOT/.claude-plugin/marketplace.json'))['metadata']['version'])")
+MKT_PLUGIN_VERSION=$(python3 -c "import json; print(json.load(open('$REPO_ROOT/.claude-plugin/marketplace.json'))['plugins'][0]['version'])")
+[ "$MKT_META_VERSION" = "$FILE_VERSION" ] \
+ && pass "marketplace.json metadata.version matches VERSION" \
+ || fail "version mismatch: marketplace metadata=$MKT_META_VERSION, VERSION=$FILE_VERSION"
+[ "$MKT_PLUGIN_VERSION" = "$FILE_VERSION" ] \
+ && pass "marketplace.json plugins[0].version matches VERSION" \
+ || fail "version mismatch: marketplace plugin=$MKT_PLUGIN_VERSION, VERSION=$FILE_VERSION"
-for skill in "${SKILLS[@]}"; do
- assert_link "$SKILLS_DIR2/$skill" "auto-detected and linked: $skill"
-done
-
-# ─── Test 3: Idempotency — running setup twice is safe ────────
+# ─── Test 2: All skills exist with SKILL.md ──────────────────
echo ""
-echo "=== 3. Idempotency (setup runs twice) ==="
-
-run_setup "$TOPRANK_DIR" --host claude # second run on T1
+echo "=== 2. Skill directories ==="
for skill in "${SKILLS[@]}"; do
- assert_link "$SKILLS_DIR/$skill" "symlink still valid after re-run: $skill"
+ assert_dir "$REPO_ROOT/skills/$skill" "skill directory: $skill"
+ assert_file "$REPO_ROOT/skills/$skill/SKILL.md" "SKILL.md exists: $skill"
done
-# No extra symlinks created
-actual_count="$(find "$SKILLS_DIR" -maxdepth 1 -type l | wc -l | tr -d ' ')"
-expected_count="${#SKILLS[@]}"
-[ "$actual_count" -eq "$expected_count" ] \
- && pass "no duplicate links ($actual_count total)" \
- || fail "wrong link count — got $actual_count, want $expected_count"
+# Guard: actual SKILL.md count must match the SKILLS array
+actual_skill_count=$(find "$REPO_ROOT/skills" -maxdepth 2 -name "SKILL.md" | wc -l | tr -d ' ')
+if [ "$actual_skill_count" -ne "${#SKILLS[@]}" ]; then
+ fail "SKILLS array has ${#SKILLS[@]} entries but skills/ has $actual_skill_count SKILL.md files"
+else
+ pass "skill count matches ($actual_skill_count)"
+fi
-# ─── Test 4: Real directory is not overwritten ────────────────
+# ─── Test 3: No old structure remains ────────────────────────
echo ""
-echo "=== 4. Existing real directory is not overwritten ==="
+echo "=== 3. Old structure removed ==="
-T4="$TMP/t4"
-SKILLS_DIR4="$T4/.claude/skills"
-TOPRANK_DIR4="$SKILLS_DIR4/toprank"
+[ ! -f "$REPO_ROOT/setup" ] \
+ && pass "setup script removed" \
+ || fail "setup script still exists (should be deleted)"
-clone_into "$TOPRANK_DIR4"
-mkdir -p "$SKILLS_DIR4/seo-analysis" # real dir, not a symlink
+[ ! -d "$REPO_ROOT/bin" ] \
+ && pass "bin/ directory removed" \
+ || fail "bin/ directory still exists"
-output="$(cd "$TOPRANK_DIR4" && ./setup --host claude 2>&1 || true)"
+[ ! -d "$REPO_ROOT/seo" ] \
+ && pass "seo/ directory removed" \
+ || fail "seo/ directory still exists (skills should be in skills/)"
-assert_no_link "$SKILLS_DIR4/seo-analysis" "real dir not overwritten"
-echo "$output" | grep -q "skipped seo-analysis" \
- && pass "skip message shown for existing real dir" \
- || fail "no skip message for existing real dir"
+[ ! -d "$REPO_ROOT/google-ads" ] \
+ && pass "google-ads/ directory removed" \
+ || fail "google-ads/ directory still exists (skills should be in skills/)"
-# Other skills still get linked
-for skill in "${SKILLS[@]}"; do
- [ "$skill" = "seo-analysis" ] && continue
- assert_link "$SKILLS_DIR4/$skill" "other skills linked despite skip: $skill"
-done
+[ ! -f "$REPO_ROOT/skills/ads/mcporter.json" ] \
+ && pass "mcporter.json removed" \
+ || fail "mcporter.json still exists (replaced by .mcp.json)"
-# ─── Test 5: Codex install (--host codex) ─────────────────────
+# ─── Test 4: No preamble injection remnants ──────────────────
echo ""
-echo "=== 5. Codex install ==="
-
-T5="$TMP/t5"
-REPO="$T5/myproject"
-TOPRANK_DIR5="$REPO/.agents/skills/toprank"
-AGENTS_DIR="$REPO/.agents/skills"
-
-git init "$REPO" >/dev/null 2>&1
-clone_into "$TOPRANK_DIR5"
-run_setup "$TOPRANK_DIR5" --host codex
+echo "=== 4. Preamble cleanup ==="
for skill in "${SKILLS[@]}"; do
- codex_name="toprank-$skill"
- assert_file "$AGENTS_DIR/$codex_name/agents/openai.yaml" "openai.yaml created: $codex_name"
- assert_file "$AGENTS_DIR/$codex_name/SKILL.md" "SKILL.md copied: $codex_name"
+ [ "$skill" = "toprank-upgrade" ] && continue
+ assert_not_contains "$REPO_ROOT/skills/$skill/SKILL.md" "toprank-update-check" \
+ "no preamble in $skill"
done
-# openai.yaml must have required fields
-yaml="$AGENTS_DIR/toprank-seo-analysis/agents/openai.yaml"
-assert_contains "$yaml" "display_name" "openai.yaml has display_name"
-assert_contains "$yaml" "allow_implicit_invocation" "openai.yaml has allow_implicit_invocation"
-assert_contains "$yaml" "toprank-seo-analysis" "openai.yaml has correct skill name"
-
-# ─── Test 6: Invalid --host value exits non-zero ──────────────
+# ─── Test 5: MCP server configuration ───────────────────────
echo ""
-echo "=== 6. Invalid --host exits non-zero ==="
+echo "=== 5. MCP server config ==="
-T6="$TMP/t6"
-clone_into "$T6/toprank"
-exit_code=0
-(cd "$T6/toprank" && ./setup --host badvalue) >/dev/null 2>&1 || exit_code=$?
-assert_exit_nonzero "$exit_code" "--host badvalue exits non-zero"
+assert_contains "$REPO_ROOT/.mcp.json" "adsagent" ".mcp.json has adsagent server"
+assert_contains "$REPO_ROOT/.mcp.json" "mcp-remote" ".mcp.json uses mcp-remote"
+assert_contains "$REPO_ROOT/.mcp.json" "ADSAGENT_API_KEY" ".mcp.json references API key env var"
-# ─── Test 7: Google Ads interactive setup ─────────────────────
+# ─── Test 6: Google Ads skills have MCP detection ────────────
echo ""
-echo "=== 7. Google Ads interactive setup ==="
+echo "=== 6. MCP detection in ads skills ==="
-T7="$TMP/t7"
-SKILLS_DIR7="$T7/.claude/skills"
-TOPRANK_DIR7="$SKILLS_DIR7/toprank"
-HOME7="$T7/home"
+for skill in ads ads-audit ads-copy; do
+ assert_contains "$REPO_ROOT/skills/$skill/SKILL.md" "MCP Server Detection" \
+ "MCP detection section in $skill"
+done
-clone_into "$TOPRANK_DIR7"
+# ─── Test 7: Reference docs exist ───────────────────────────
-# Simulate interactive input: "y" then a test API key
-# TOPRANK_FORCE_INTERACTIVE bypasses the isatty() check for piped input
-printf 'y\nasa_test_key_123\n' | HOME="$HOME7" TOPRANK_FORCE_INTERACTIVE=1 \
- bash -c 'cd "'"$TOPRANK_DIR7"'" && ./setup --host claude' >/dev/null 2>&1
+echo ""
+echo "=== 7. Reference documents ==="
-# Verify config was written
-config_file="$HOME7/.adsagent/config.json"
-assert_file "$config_file" "ads config file created"
-if [ -f "$config_file" ]; then
- assert_contains "$config_file" "asa_test_key_123" "ads config has correct API key"
-fi
+assert_dir "$REPO_ROOT/skills/ads/references" "ads references directory"
+assert_dir "$REPO_ROOT/skills/ads-audit/references" "ads-audit references directory"
+assert_dir "$REPO_ROOT/skills/ads-copy/references" "ads-copy references directory"
+assert_dir "$REPO_ROOT/skills/seo-analysis/references" "seo-analysis references directory"
-# ─── Test 8: Google Ads setup with --api-key flag ─────────────
+# ─── Test 8: Eval files exist ────────────────────────────────
echo ""
-echo "=== 8. Google Ads --api-key flag ==="
+echo "=== 8. Eval files ==="
-T8="$TMP/t8"
-SKILLS_DIR8="$T8/.claude/skills"
-TOPRANK_DIR8="$SKILLS_DIR8/toprank"
-HOME8="$T8/home"
-
-clone_into "$TOPRANK_DIR8"
-HOME="$HOME8" bash -c 'cd "'"$TOPRANK_DIR8"'" && ./setup --host claude --api-key asa_flag_key_456' >/dev/null 2>&1
-
-config_file8="$HOME8/.adsagent/config.json"
-assert_file "$config_file8" "ads config created via --api-key"
-if [ -f "$config_file8" ]; then
- assert_contains "$config_file8" "asa_flag_key_456" "ads config has flag API key"
-fi
+assert_file "$REPO_ROOT/skills/ads/evals/evals.json" "ads evals exist"
+assert_file "$REPO_ROOT/skills/ads-audit/evals/evals.json" "ads-audit evals exist"
+assert_file "$REPO_ROOT/skills/ads-copy/evals/evals.json" "ads-copy evals exist"
# ─── Results ──────────────────────────────────────────────────
diff --git a/test/test_ads_skill_llm_eval.py b/test/test_ads_skill_llm_eval.py
new file mode 100644
index 00000000..aeeb76fe
--- /dev/null
+++ b/test/test_ads_skill_llm_eval.py
@@ -0,0 +1,96 @@
+"""
+LLM-as-a-Judge evals for Google Ads SKILL.md quality.
+
+Run: EVALS=1 pytest test/test_ads_skill_llm_eval.py -v
+Cost: ~$0.10 per run (Gemini Flash)
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+from helpers.llm_judge import extract_section, run_judge_test
+from helpers.eval_store import EvalCollector
+from helpers.touchfiles import (
+ select_tests, detect_base_branch, get_changed_files,
+ ADS_LLM_JUDGE_TOUCHFILES, GLOBAL_TOUCHFILES,
+)
+
+ROOT = Path(__file__).parent.parent
+ADS_SKILL = ROOT / 'skills' / 'ads' / 'SKILL.md'
+AUDIT_SKILL = ROOT / 'skills' / 'ads-audit' / 'SKILL.md'
+COPY_SKILL = ROOT / 'skills' / 'ads-copy' / 'SKILL.md'
+
+EVALS = bool(os.environ.get('EVALS'))
+pytestmark = pytest.mark.skipif(not EVALS, reason='Set EVALS=1 to run LLM-judge evals')
+
+_selected: list[str] | None = None
+if EVALS and not os.environ.get('EVALS_ALL'):
+ _base = os.environ.get('EVALS_BASE') or detect_base_branch(str(ROOT)) or 'main'
+ _changed = get_changed_files(_base, str(ROOT))
+ if _changed:
+ _sel = select_tests(_changed, ADS_LLM_JUDGE_TOUCHFILES, GLOBAL_TOUCHFILES)
+ _selected = _sel['selected']
+ print(
+ f"\nAds LLM-judge selection ({_sel['reason']}): "
+ f"{len(_selected)}/{len(ADS_LLM_JUDGE_TOUCHFILES)} tests",
+ file=sys.stderr,
+ )
+
+_ads_md = ADS_SKILL.read_text() if EVALS else ''
+_audit_md = AUDIT_SKILL.read_text() if EVALS else ''
+_copy_md = COPY_SKILL.read_text() if EVALS else ''
+_collector = EvalCollector('ads-llm-judge') if EVALS else None
+
+SUITE = 'Google Ads SKILL.md quality'
+
+
+def _skip(name: str) -> bool:
+ return not EVALS or (_selected is not None and name not in _selected)
+
+
[email protected](_skip('ads-heuristics-clarity'), reason='not selected')
+def test_ads_heuristics_clarity():
+ run_judge_test('ads-heuristics-clarity', SUITE,
+ 'Google Ads analysis heuristics (numeric thresholds for QS, bids, keywords, impression share)',
+ extract_section(_ads_md, '## Analysis Heuristics', '## Wasted Spend'),
+ _collector)
+
+
[email protected](_skip('ads-workflows-clarity'), reason='not selected')
+def test_ads_workflows_clarity():
+ run_judge_test('ads-workflows-clarity', SUITE,
+ 'Google Ads common workflows (step-by-step optimization procedures)',
+ extract_section(_ads_md, '## Common Workflows', '## Report Template'),
+ _collector)
+
+
[email protected](_skip('ads-audit-scoring-clarity'), reason='not selected')
+def test_ads_audit_scoring_clarity():
+ run_judge_test('ads-audit-scoring-clarity', SUITE,
+ 'Google Ads audit scoring rubric (7 health dimensions with 0-5 numeric scores)',
+ extract_section(_audit_md, '## Phase 2: Analyze and Score', '## Phase 2.5'),
+ _collector)
+
+
[email protected](_skip('ads-audit-report-clarity'), reason='not selected')
+def test_ads_audit_report_clarity():
+ run_judge_test('ads-audit-report-clarity', SUITE,
+ 'Google Ads audit report format (scorecard, health score, wasted spend, actions)',
+ extract_section(_audit_md, '## Phase 4: Deliver the Audit Report', '## Conditional Handoffs'),
+ _collector, min_completeness=3)
+
+
[email protected](_skip('ads-copy-formulas-clarity'), reason='not selected')
+def test_ads_copy_formulas_clarity():
+ run_judge_test('ads-copy-formulas-clarity', SUITE,
+ 'Google Ads RSA copy formulas (headline templates, description templates, character counts, pinning)',
+ extract_section(_copy_md, '## Workflow', '## Rules'),
+ _collector)
+
+
+def teardown_module(module):
+ if _collector:
+ _collector.finalize()
diff --git a/test/test_skill_e2e.py b/test/test_skill_e2e.py
index 691567bf..d9ec9425 100644
--- a/test/test_skill_e2e.py
+++ b/test/test_skill_e2e.py
@@ -24,7 +24,7 @@ from helpers.touchfiles import (
)
ROOT = Path(__file__).parent.parent
-SKILL_PATH = ROOT / 'seo' / 'seo-analysis'
+SKILL_PATH = ROOT / 'skills' / 'seo-analysis'
FIXTURES_DIR = ROOT / 'test' / 'fixtures'
EVALS = bool(os.environ.get('EVALS'))
diff --git a/test/test_skill_llm_eval.py b/test/test_skill_llm_eval.py
index 835bcdb4..a3e91106 100644
--- a/test/test_skill_llm_eval.py
+++ b/test/test_skill_llm_eval.py
@@ -1,34 +1,29 @@
"""
LLM-as-a-Judge evals for seo-analysis SKILL.md quality.
-Guards against regressions — if someone edits SKILL.md in a way that
-makes instructions ambiguous, these tests will catch it.
-
Run: EVALS=1 pytest test/test_skill_llm_eval.py
-Cost: ~$0.05 per run
+Cost: ~$0.05 per run (Gemini Flash)
"""
import os
import sys
-import time
from pathlib import Path
import pytest
-from helpers.llm_judge import judge
-from helpers.eval_store import EvalCollector, EvalTestEntry
+from helpers.llm_judge import extract_section, run_judge_test
+from helpers.eval_store import EvalCollector
from helpers.touchfiles import (
select_tests, detect_base_branch, get_changed_files,
LLM_JUDGE_TOUCHFILES, GLOBAL_TOUCHFILES,
)
ROOT = Path(__file__).parent.parent
-SKILL_MD = ROOT / 'seo' / 'seo-analysis' / 'SKILL.md'
+SKILL_MD = ROOT / 'skills' / 'seo-analysis' / 'SKILL.md'
EVALS = bool(os.environ.get('EVALS'))
pytestmark = pytest.mark.skipif(not EVALS, reason='Set EVALS=1 to run LLM-judge evals')
-# Diff-based selection
_selected: list[str] | None = None
if EVALS and not os.environ.get('EVALS_ALL'):
_base = os.environ.get('EVALS_BASE') or detect_base_branch(str(ROOT)) or 'main'
@@ -42,101 +37,38 @@ if EVALS and not os.environ.get('EVALS_ALL'):
file=sys.stderr,
)
-
-def _should_run(name: str) -> bool:
- return EVALS and (_selected is None or name in _selected)
-
-
_skill_md = SKILL_MD.read_text() if EVALS else ''
_collector = EvalCollector('llm-judge') if EVALS else None
+SUITE = 'seo-analysis SKILL.md quality'
+
-def _extract_section(md: str, start_marker: str, end_marker: str = '') -> str:
- start = md.find(start_marker)
- if start == -1:
- return ''
- if end_marker:
- end = md.find(end_marker, start + len(start_marker))
- return md[start:end].strip() if end != -1 else md[start:].strip()
- return md[start:].strip()
+def _skip(name: str) -> bool:
+ return not EVALS or (_selected is not None and name not in _selected)
[email protected](not _should_run('seo-phases-clarity'), reason='not selected')
[email protected](_skip('seo-phases-clarity'), reason='not selected')
def test_seo_phases_clarity():
- t0 = time.time()
- section = _extract_section(_skill_md, '## Phase 1', '## Phase 4')
- assert len(section) > 100
+ run_judge_test('seo-phases-clarity', SUITE,
+ 'Phase 1-3 (setup & data collection)',
+ extract_section(_skill_md, '## Phase 1', '## Phase 4'),
+ _collector)
- scores = judge('Phase 1–3 (setup & data collection)', section)
- print('Phases 1-3 scores:', scores)
- if _collector:
- _collector.add_test(EvalTestEntry(
- name='seo-phases-clarity',
- suite='seo-analysis SKILL.md quality',
- tier='llm-judge',
- passed=scores.clarity >= 4 and scores.completeness >= 4 and scores.actionability >= 4,
- duration_ms=int((time.time() - t0) * 1000),
- cost_usd=0.02,
- judge_scores={'clarity': scores.clarity, 'completeness': scores.completeness, 'actionability': scores.actionability},
- judge_reasoning=scores.reasoning,
- ))
-
- assert scores.clarity >= 4
- assert scores.completeness >= 4
- assert scores.actionability >= 4
-
-
[email protected](not _should_run('seo-quick-wins-clarity'), reason='not selected')
[email protected](_skip('seo-quick-wins-clarity'), reason='not selected')
def test_seo_quick_wins_clarity():
- t0 = time.time()
- section = _extract_section(_skill_md, '### Quick Wins', '### Search Intent')
- assert len(section) > 50
+ run_judge_test('seo-quick-wins-clarity', SUITE,
+ 'Quick Wins analysis instructions',
+ extract_section(_skill_md, '### Quick Wins', '### Search Intent'),
+ _collector)
- scores = judge('Quick Wins analysis instructions', section)
- print('Quick Wins scores:', scores)
- if _collector:
- _collector.add_test(EvalTestEntry(
- name='seo-quick-wins-clarity',
- suite='seo-analysis SKILL.md quality',
- tier='llm-judge',
- passed=scores.clarity >= 4 and scores.completeness >= 4 and scores.actionability >= 4,
- duration_ms=int((time.time() - t0) * 1000),
- cost_usd=0.02,
- judge_scores={'clarity': scores.clarity, 'completeness': scores.completeness, 'actionability': scores.actionability},
- judge_reasoning=scores.reasoning,
- ))
-
- assert scores.clarity >= 4
- assert scores.completeness >= 4
- assert scores.actionability >= 4
-
-
[email protected](not _should_run('seo-report-format-clarity'), reason='not selected')
[email protected](_skip('seo-report-format-clarity'), reason='not selected')
def test_seo_report_format_clarity():
- t0 = time.time()
- section = _extract_section(_skill_md, '## Phase 6')
- assert len(section) > 100
-
- scores = judge('Phase 6 report format', section)
- print('Report format scores:', scores)
-
- if _collector:
- _collector.add_test(EvalTestEntry(
- name='seo-report-format-clarity',
- suite='seo-analysis SKILL.md quality',
- tier='llm-judge',
- passed=scores.clarity >= 4 and scores.completeness >= 3 and scores.actionability >= 4,
- duration_ms=int((time.time() - t0) * 1000),
- cost_usd=0.02,
- judge_scores={'clarity': scores.clarity, 'completeness': scores.completeness, 'actionability': scores.actionability},
- judge_reasoning=scores.reasoning,
- ))
-
- assert scores.clarity >= 4
- assert scores.completeness >= 3
- assert scores.actionability >= 4
+ run_judge_test('seo-report-format-clarity', SUITE,
+ 'Phase 6 report format',
+ extract_section(_skill_md, '## Phase 6'),
+ _collector, min_completeness=3)
def teardown_module(module):
diff --git a/test/unit/test_analyze_gsc.py b/test/unit/test_analyze_gsc.py
index 8053f31f..b7cdf88a 100644
--- a/test/unit/test_analyze_gsc.py
+++ b/test/unit/test_analyze_gsc.py
@@ -17,7 +17,7 @@ from unittest.mock import MagicMock, patch
# Load analyze_gsc.py as a module without executing main()
_SCRIPT_PATH = os.path.join(
- os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', 'analyze_gsc.py'
+ os.path.dirname(__file__), '..', '..', 'skills', 'seo-analysis', 'scripts', 'analyze_gsc.py'
)
spec = importlib.util.spec_from_file_location('analyze_gsc', _SCRIPT_PATH)
gsc = importlib.util.module_from_spec(spec)
diff --git a/test/unit/test_cms_scripts.py b/test/unit/test_cms_scripts.py
index 798fec4c..450eab38 100644
--- a/test/unit/test_cms_scripts.py
+++ b/test/unit/test_cms_scripts.py
@@ -17,7 +17,7 @@ import unittest
def _load(name):
path = os.path.join(
- os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', name
+ os.path.dirname(__file__), '..', '..', 'skills', 'seo-analysis', 'scripts', name
)
spec = importlib.util.spec_from_file_location(name.replace('.py', ''), path)
mod = importlib.util.module_from_spec(spec)
diff --git a/test/unit/test_strapi_scripts.py b/test/unit/test_strapi_scripts.py
index e0cce0dd..1a5f22fa 100644
--- a/test/unit/test_strapi_scripts.py
+++ b/test/unit/test_strapi_scripts.py
@@ -18,7 +18,7 @@ import unittest
def _load(name):
path = os.path.join(
- os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', name
+ os.path.dirname(__file__), '..', '..', 'skills', 'seo-analysis', 'scripts', name
)
spec = importlib.util.spec_from_file_location(name.replace('.py', ''), path)
mod = importlib.util.module_from_spec(spec)
diff --git a/test/unit/test_url_inspection.py b/test/unit/test_url_inspection.py
index 06bb91ba..c37d254f 100644
--- a/test/unit/test_url_inspection.py
+++ b/test/unit/test_url_inspection.py
@@ -12,7 +12,7 @@ import unittest
# Load url_inspection.py as a module without executing main()
_SCRIPT_PATH = os.path.join(
- os.path.dirname(__file__), '..', '..', 'seo', 'seo-analysis', 'scripts', 'url_inspection.py'
+ os.path.dirname(__file__), '..', '..', 'skills', 'seo-analysis', 'scripts', 'url_inspection.py'
)
spec = importlib.util.spec_from_file_location('url_inspection', _SCRIPT_PATH)
ui = importlib.util.module_from_spec(spec)