/seo-optimize

name: seo-optimize
description: GSC data-driven SEO optimization. Connects to Google Search Console (API, browser, or CSV), pulls search performance data, runs 8 analysis types (striking distance, low-CTR, declining pages, content gaps, cannibalization, quick wins, top performers at risk, device/geo gaps), prioritizes findings, and executes optimizations. Use when user says "optimize SEO", "GSC", "Google Search Console", "search performance", "CTR optimization", "keyword cannibalization", "striking distance", "declining pages", "content gaps", or "quick wins".
disable-model-invocation: true

GSC Data-Driven SEO Optimization

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?"

---

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. See `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
  }'

Browser Path (Zero-Setup)

If the user doesn't have a service account, use browser automation to navigate GSC directly. The user needs to be logged into Google Search Console in their browser.

1. Ask for the GSC property URL 2. Navigate to GSC Performance report 3. Set date range to Last 28 days and extract data 4. Parse exported CSVs into JSON format

CSV Path (Manual Fallback)

1. Ask user to go to Google Search Console → Performance → Search results 2. Set date range to Last 28 days, click Export → Download CSV 3. Repeat with Last 3 months for trend data 4. Parse CSVs into JSON format

---

Phase 2: Pull Data

**Goal:** Execute 6 targeted GSC API calls and save results locally as JSON.

| # | Query | Output File | Dimensions | |---|-------|-------------|------------| | 1 | Last 28 days | gsc-query-page-28d.json | query, page | | 2 | Previous 28 days | gsc-query-page-prev-28d.json | query, page | | 3 | Pages last 28 days | gsc-pages-28d.json | page | | 4 | Pages last 90 days | gsc-pages-90d.json | page | | 5 | Device breakdown | gsc-query-page-device-28d.json | query, page, device | | 6 | Country breakdown | gsc-query-page-country-28d.json | query, page, country |

See `references/gsc-api-reference.md` for exact curl commands.

**Do NOT load all 25,000 rows into context.** Process data in targeted chunks using `jq` or `python3` one-liners.

---

Phase 3: Analyze

**Goal:** Run 8 analysis types to find every optimization opportunity.

| # | Analysis | Key Filter | |---|----------|------------| | 1 | Striking Distance Keywords | Position 11-20, impressions >= 100 | | 2 | Low-CTR Pages | CTR below expected curve, impressions >= 500 | | 3 | Declining Pages | Clicks dropped > 20% vs previous period | | 4 | Content Gaps | High-impression queries on homepage or unrelated URLs | | 5 | Keyword Cannibalization | Same query ranking on 2+ pages | | 6 | Quick Wins | Page 1 + low CTR OR position 11-15 + high impressions | | 7 | Top Performers at Risk | Position 1-5, clicks > 50/mo, declining trend | | 8 | Device/Geo Gaps | Position differs > 5 spots across mobile/desktop |

For each analysis, use the exact filter criteria in `references/analysis-playbooks.md`. See `references/data-interpretation.md` for how to read each metric correctly.

---

Phase 4: Prioritize

**Goal:** Score findings and create a ranked action plan.

Score every finding using: **Impact x Effort x Confidence**

| Priority | Criteria | Action | Timeline | |----------|----------|--------|----------| | **P0 — Quick Wins** | Page 1 + low CTR | Rewrite title/meta description | 1-2 weeks | | **P1 — Striking Distance** | Position 11-20 + high impressions | Content enhancement + internal links | 2-4 weeks | | **P2 — Cannibalization** | Multiple pages competing | Consolidate/redirect/differentiate | 4-8 weeks | | *