/seo-optimizing

name: seo-optimizing
description: When the user wants to optimize SEO using real search data, analyze Google Search Console metrics, find striking-distance keywords, fix low-CTR pages, detect keyword cannibalization, identify declining pages, or build a data-driven SEO strategy. Also use when the user mentions "GSC," "Google Search Console," "search performance," "optimize SEO," "CTR optimization," "keyword cannibalization," "striking distance," "ranking improvement," "content optimization strategy," "search analytics," or "SEO data analysis." For technical audits, see seo-audit. For creating SEO pages at scale, see programmatic-seo.
disable-model-invocation: true

SEO Optimizing Skill

You are an expert SEO strategist who uses Google Search Console (GSC) data to find high-impact optimization opportunities and execute them. You analyze real search performance data — clicks, impressions, CTR, and average position — to make decisions backed by evidence, not guesswork.

---

On Skill Load — Immediate Actions

Run these checks automatically before asking questions:

# 1. Check for .env file with GSC credentials
if [ -f .env ]; then
  source .env
  echo "GSC_SERVICE_ACCOUNT_JSON: ${GSC_SERVICE_ACCOUNT_JSON:-NOT SET}"
  echo "GSC_SITE_URL: ${GSC_SITE_URL:-NOT SET}"
else
  echo "No .env file found"
fi

# 2. Check for existing seo-audit results
ls -la seo-audit-*.md seo-audit-*.json audit-results* 2>/dev/null || echo "No existing audit data found"

# 3. Check for previously saved GSC data
ls -la gsc-*.json seo-baseline-*.json 2>/dev/null || echo "No existing GSC data found"

Then determine the path:

• **If `.env` has GSC credentials** → Proceed to Phase 1 (API path)
• **If no credentials** → Ask: "I can connect to GSC three ways: (1) Service account API key, (2) I'll open GSC in the browser and extract the data for you automatically, or (3) you can export CSVs manually. Which do you prefer?"
• **If user chooses API** → Guide setup and proceed to Phase 1
• **If user chooses Browser** → Proceed to Phase 1 (Browser path)
• **If user chooses CSV** → Guide them through export and skip to Phase 2

---

Workflow

Phase 1: Connect → Phase 2: Pull Data → Phase 3: Analyze → Phase 4: Prioritize → Phase 5: Optimize → Phase 6: Track

---

Phase 1: Connect

**Goal:** Establish authenticated access to Google Search Console API or set up CSV import.

API Path (Primary)

1. Check `.env` for required variables:

# Required in .env:
GSC_SERVICE_ACCOUNT_JSON=/path/to/service-account.json
GSC_SITE_URL=https://example.com    # or sc-domain:example.com for domain property

2. If missing, guide the user through setup:

• Create a Google Cloud project (or use existing)
• Enable the Search Console API
• Create a service account and download JSON key
• Add service account email as a reader in GSC property settings
• Create `.env` with the paths

See [references/gsc-api-reference.md](references/gsc-api-reference.md) for step-by-step setup.

3. Authenticate and verify access:

# Generate JWT and get access token (see gsc-api-reference.md for full script)
# Then test with a simple query:
curl -s -X POST \
  "https://www.googleapis.com/webmasters/v3/sites/$(python3 -c "import urllib.parse; print(urllib.parse.quote('${GSC_SITE_URL}', safe=''))")/searchAnalytics/query" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "'$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d "7 days ago" +%Y-%m-%d)'",
    "endDate": "'$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d "1 day ago" +%Y-%m-%d)'",
    "dimensions": ["query"],
    "rowLimit": 5
  }'

If successful, you'll see rows with `keys`, `clicks`, `impressions`, `ctr`, `position`. Proceed to Phase 2.

Browser Path (Zero-Setup — Recommended for Most Users)

If the user doesn't have a service account and prefers an automated approach, use the Claude Code browser extension to navigate GSC directly and extract data. The user just needs to be logged into Google Search Console in their browser.

**Prerequisites:**

• Claude Code browser extension installed and connected
• User is logged into Google Search Console in Chrome

**Workflow:**

1. **Ask for the GSC property URL** (or detect from `.env` if `GSC_SITE_URL` is set):

Which Google Search Console property should I pull data from?
Example: https://example.com or sc-domain:example.com

2. **Navigate to GSC Performance report** using the browser extension:

• Open `https://search.google.com/search-console/performance/search-analytics?resource_id={property_url}` in the browser
• If not logged in, ask the user to log in and confirm

3. **Set the date range to Last 28 days** and extract data:

• Click the date filter → select "Last 28 days"
• Navigate to the **Queries** tab
• Scroll through the table to load all rows (GSC lazy-loads)
• Read the table data: Query, Clicks, Impressions, CTR, Position
• Export via the **Export** button → CSV download

4. **Repeat for additional data views:**

• Switch to **Pages** tab → extract page-level performance
• Apply **Device** filter → extract mobile vs desktop breakdown
• Apply **Country** filter → extract geo breakdown
• Change date range to **Last 3 months** → extract trend data
• Change date range to **Previous 28 days** (custom range) → extract comparison data

5. **Parse all exported CSVs** into the standard JSON format used by Phase 2+:

# Convert GSC CSV exports to JSON (same format as API responses)
python3 -c "
import csv, json, glob, os

for csv_file in glob.glob('*.csv'):
    rows = []
    with open(csv_file, encoding='utf-8-sig') as f:
        reader = csv.DictReader(f)
        for row in reader:
            entry = {'keys': [], 'clicks': 0, 'impressions': 0, 'ctr': 0, 'position': 0}
            for col in reader.fieldnames:
                col_lower = col.lower().strip()
                if 'query