Add apify-search-console-ai-overview skill

skills/apify-search-console-ai-overview/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: apify-search-console-ai-overview
+description: "Build a prioritized page rewrite queue from your Google Search Console data with the Apify AI Overview Rewrite Queue Actor (johnvc/ai-overview-rewrite-queue). It joins your Search Console query positions and CTR against the live Google AI Overview citation state, then returns a tiered queue that puts the highest-leverage rewrites first, the pages where a competitor is cited in the AI Overview while you rank 5 to 20. Use when the user asks about google search console ai overview, search console ai overview, which pages to rewrite for AI Overviews, or wants to turn a Search Console export into an action list. Pass target_domains plus a Search Console CSV, inline rows, or a query list. Pay per scored query, MCP-ready for Claude and other AI agents."
+author: John Cole
+author_url: https://github.com/johnisanerd
+license: MIT
+metadata:
+  version: "1.0"
+  keywords: "google search console ai overview, search console ai overview, ai overview rewrite queue, ai overview tracking, seo content refresh"
+---
+
+# Search Console AI Overview: A Prioritized Rewrite Queue
+
+Build a prioritized rewrite queue from your Google Search Console data. This Actor joins each query's Search Console position and CTR against the live AI Overview citation state, then returns a tiered queue so you rewrite the highest-leverage pages first: the ones where a competitor is cited in the AI Overview while you still rank 5 to 20.
+
+## When to use this skill
+
+- The user wants to know which pages to rewrite because of Google AI Overviews, starting from their own Search Console data.
+- They ask about "google search console ai overview" or "search console ai overview" and want an action list, not a dashboard.
+- They have a Search Console Queries export (CSV) and a domain, and want it turned into a ranked to-do queue.
+- They want the join that nothing else does: Search Console rank and CTR on one side, live AI Overview citation state on the other.
+
+Not for: a plain yes or no citation check across a fixed watchlist (use the google-ai-overview-monitoring skill), organic rank tracking on its own, or content rewriting itself (this tells you which pages to rewrite, not what to write).
+
+## What you get (one row per query)
+
+Queue and identity: `result_type` (labels the record), `query`, `query_normalized`, `tier` (A to D, or X), `tier_reason` (why it landed there), `join_status` (whether the query matched a Search Console row).
+
+Search Console metrics carried through the join: `clicks`, `impressions`, `ctr`, `position`.
+
+Live citation check: `check_status`, `ai_overview_present`, `citation_state` (one of cited, competitor_cited, no_overview, overview_no_references, or null), `cited_urls`, `cited_pages_count`, `reference_domains`, `reference_count`, `fetched_at`. Failures carry `error_message` and `error_type`.
+
+A run summary is written to the key-value store.
+
+### How tiers rank the queue
+
+- Tier A: a competitor is cited in the AI Overview and you rank position 5 to 20. Highest-leverage rewrites; do these first.
+- Tier B: a competitor is cited or the overview has no references, and you rank 1 to 4. You are close; a rewrite can win the citation.
+- Tier C: you are already cited but your CTR is below your own baseline for that query.
+- Tier D: no AI Overview for the query.
+- Tier X: the citation check failed, or the query did not match a Search Console row. Kept, never dropped, so you can see the gap.
+
+## Prerequisites
+
+- Apify account (sign up at https://apify.com?fpr=9n7kx3&fp_sid=awesomeskills).
+- Authentication via `apify login`, or an `APIFY_TOKEN` environment variable (Apify Console, Settings, Integrations).
+- Your Search Console Queries report. Export it from the Performance report as CSV, host it at a URL and pass `search_console_csv_url`, or pass the rows inline as `search_console_rows`.
+
+## The Actor
+
+- Store page: https://apify.com/johnvc/ai-overview-rewrite-queue?fpr=9n7kx3&fp_sid=awesomeskills
+- Actor ID: `johnvc/ai-overview-rewrite-queue`
+- Pricing: a small per-run setup fee plus a scored-query fee. This is a composition Actor, so the citation half runs a second Actor that bills your own account separately. Read `references/gotchas.md` before scheduling.
+
+## Run it with the Apify CLI
+
+From a hosted Search Console CSV:
+
+```bash
+apify actors call "johnvc/ai-overview-rewrite-queue" -i '{"target_domains":["example.com"],"search_console_csv_url":"https://example.com/exports/search-console-queries.csv","min_impressions":10,"gl":"us","hl":"en"}' \
+  --json \
+  --user-agent apify-awesome-skills/apify-search-console-ai-overview \
+  2>/dev/null
+```
+
+From inline rows, when you already have the Queries report in hand:
+
+```bash
+apify actors call "johnvc/ai-overview-rewrite-queue" -i '{"target_domains":["example.com"],"search_console_rows":[{"query":"best crm for startups","clicks":12,"impressions":540,"ctr":0.022,"position":7.3},{"query":"crm with free tier","clicks":4,"impressions":210,"ctr":0.019,"position":11.4}],"min_impressions":10}' \
+  --json \
+  --user-agent apify-awesome-skills/apify-search-console-ai-overview \
+  2>/dev/null
+```
+
+Read the rows back later, for example from a scheduled run:
+
+```bash
+apify datasets get-items <DATASET_ID> --format json --user-agent apify-awesome-skills/apify-search-console-ai-overview 2>/dev/null
+```
+
+Every call carries the three flags this repo expects: `--json` (or `--format json`), `--user-agent apify-awesome-skills/apify-search-console-ai-overview`, and `2>/dev/null`.
+
+## Run it from Claude or another AI agent (MCP)
+
+The Actor is MCP-ready. Add the hosted server URL:
+
+`https://mcp.apify.com/?tools=actors,docs,johnvc/ai-overview-rewrite-queue`
+
+Then ask, for example: "Here is my Search Console CSV for example.com. Build the rewrite queue and show me the tier A pages first." MCP setup docs: https://docs.apify.com/platform/integrations/mcp
+
+## Workflow
+
+1. Export the Queries report. In Search Console, open Performance, set the date range and property, and export the Queries table as CSV (query, clicks, impressions, ctr, position). Host it and pass `search_console_csv_url`, or paste the rows into `search_console_rows`.
+2. Set `target_domains`. List every property you count as "yours" (apex plus subdomains you own). The Actor compares these against the AI Overview's cited domains to decide cited versus competitor_cited.
+3. Set `min_impressions` to trim noise. The default is 10; raise it on a long export so you score the queries that actually carry traffic and keep the child citation cost down.
+4. Estimate the cost for both Actors and confirm. Query count drives the bill on both sides. See `references/gotchas.md` and set a run budget.
+5. Run, then work the queue top down. Start with tier A (competitor cited, you rank 5 to 20), then tier B (you rank 1 to 4). Use `tier_reason`, `position`, and `reference_domains` to brief the rewrite.
+6. Re-run after you ship rewrites to confirm the tier moved (A to B to cited).
+
+## Inputs
+
+- `target_domains` (array, required): the domains you own; used to classify cited versus competitor_cited.
+- `search_console_csv_url` (string): URL to a Search Console Queries CSV. One of the three query sources.
+- `search_console_rows` (array): inline rows of {query, clicks, impressions, ctr, position}. Preserves the join fields.
+- `queries` (array): a bare query list when you have no Search Console metrics; those rows join_status as unmatched and land in tier X, but still get a citation check.
+- `min_impressions` (int, default 10): drop queries below this impression floor before scoring.
+- `gl` (string, default us) and `hl` (string, default en): market targeting for the citation check.
+- `location` (string): optional named location for local-intent queries.
+
+## Cost
+
+Two Actors bill on one run. This Actor charges a per-run setup fee plus a per-scored-query fee; the citation half runs the sibling `johnvc/google-ai-overview-api`, whose run bills your own account separately (a setup fee plus a per-retrieval fee, one or two retrievals per query). So the query count drives the bill on both sides. Keep query counts modest, raise `min_impressions`, and set a run budget. Worked numbers and the exact per-event prices are in `references/gotchas.md`.
+
+## Honest limits
+
+- Join rate. Search Console anonymizes long-tail queries, so a long-tail export will not fully match; expect roughly 30 to 60 percent of a long-tail list to join. Unmatched queries are labelled tier X and kept, never dropped, so the gap is visible.
+- AI Overviews are not deterministic. The cited set can shift between identical runs, so treat a single tier A as a candidate and confirm over a couple of runs before a big rewrite.
+- The CTR baseline in tier C is your own historical CTR for that query, not an industry number.
+- The queue tells you which pages to rewrite and why; the rewrite itself is your call.
+- Point-in-time, not a live feed: `fetched_at` timestamps each row.
+
+## Troubleshooting
+
+- Everything lands in tier X: the join is not matching. Check that `query` values in your CSV match live queries, that `target_domains` is set, and that `min_impressions` is not filtering everything out.
+- Few or no tier A rows: either you already rank 1 to 4 (look at tier B) or few overviews cite competitors in your space; lower `min_impressions` to widen the set, or confirm `gl` matches your market.
+- Whole run shows `ai_overview_present` false: keep `hl` at en, try `gl` at us, and check the queries actually trigger overviews.
+- Cost higher than expected: the child citation checks dominate; cut the query count or raise `min_impressions`, and set a run budget.
+
+See `references/gotchas.md` for cost guardrails and error recovery, and `references/actor-index.md` for the Actor routing table.
+
+## Related answer-engine Actors
+
+- Google AI Overview API (the citation engine this Actor composes, and a standalone check): https://apify.com/johnvc/Google-AI-Overview-API?fpr=9n7kx3&fp_sid=awesomeskills
+- Bing Copilot API: https://apify.com/johnvc/bing-copilot-api?fpr=9n7kx3&fp_sid=awesomeskills
+- Brave AI Mode API: https://apify.com/johnvc/brave-ai-mode-api?fpr=9n7kx3&fp_sid=awesomeskills

skills/apify-search-console-ai-overview/references/actor-index.md

@@ -0,0 +1,29 @@
+# Actor index: Search Console AI Overview rewrite queue
+
+The primary Actor for this skill, the sibling it composes, and the answer-engine Actors worth chaining when a program covers more than Google. The agent reads this after `SKILL.md` to pick the right Actor for a specific user intent.
+
+| Platform | User intent | Actor ID | Tier | Notes |
+|----------|-------------|----------|------|-------|
+| Google (Search Console + AI Overview) | Turn a Search Console export into a tiered page rewrite queue | `johnvc/ai-overview-rewrite-queue` | community | Composition Actor. Joins Search Console position and CTR with the live AI Overview citation state. Inputs: `target_domains` (required), one of `search_console_csv_url` / `search_console_rows` / `queries`, `min_impressions`, `gl`, `hl`, `location`. One row per query with `tier`, `tier_reason`, `citation_state`, and the joined Search Console metrics. Bills the caller for this Actor and for the child citation Actor. |
+
+## The sibling Actor this one composes
+
+| User intent | Actor ID | Notes |
+|-------------|----------|-------|
+| The live AI Overview citation check itself, standalone | `johnvc/Google-AI-Overview-API` | This is the Actor the rewrite queue runs for the citation half. Use it directly for a plain watchlist citation check with no Search Console join. Its run bills the caller's own account separately. |
+
+## Chain with other answer-engine Actors
+
+| User intent | Actor ID | Notes |
+|-------------|----------|-------|
+| The same page audit on Microsoft's answer engine | `johnvc/bing-copilot-api` | Bing Copilot answers and cited sources. |
+| Brave Search AI answers | `johnvc/brave-ai-mode-api` | Privacy-focused search visibility. |
+| Korean-market AI answers | `johnvc/naver-ai-overview-api` | Naver's AI overview equivalent. |
+
+## How to extend
+
+1. Search candidates: `apify actors search "ai overview" --json --limit 20 --user-agent apify-awesome-skills/apify-search-console-ai-overview 2>/dev/null`
+2. Fetch the input schema: `apify actors info "johnvc/ai-overview-rewrite-queue" --input --json --user-agent apify-awesome-skills/apify-search-console-ai-overview 2>/dev/null`
+3. Add a row above with the user intent that should trigger it.
+
+Note: `Tier` here is `community` because these are third-party Actors published by John Cole on the Apify Store, not Apify-maintained Actors.

skills/apify-search-console-ai-overview/references/gotchas.md

@@ -0,0 +1,65 @@
+# Gotchas: Search Console AI Overview rewrite queue (johnvc/ai-overview-rewrite-queue)
+
+Cost guardrails, the two-Actor billing model, and error recovery. The agent reads this on demand when scoping a run or when a run misbehaves.
+
+## Two Actors bill on one run (read this first)
+
+This is a composition Actor. It does two things per run:
+
+1. It joins your Search Console rows and grades them into tiers. That work bills on THIS Actor: a per-run setup fee plus a per-scored-query fee.
+2. It runs the sibling `johnvc/google-ai-overview-api` to fetch the live AI Overview for each scored query. That child run bills YOUR OWN account separately, as its own Actor run.
+
+So a single run charges you for BOTH Actors. The query count is the cost driver on both sides. Keep query counts modest, raise `min_impressions` to score fewer low-traffic queries, and set a run budget (`maxTotalChargeUsd` on the run, or a plan-level limit) before you launch a large export.
+
+## Cost guardrails
+
+Per-event prices at the time of writing. Confirm the live numbers on each Store card, or with `apify actors info "johnvc/ai-overview-rewrite-queue" --json --user-agent apify-awesome-skills/apify-search-console-ai-overview 2>/dev/null` (look at `pricingInfo`).
+
+This Actor (johnvc/ai-overview-rewrite-queue):
+
+- Setup: about $0.005 per run.
+- Scored query: about $0.002 per scored query (about $0.0022 on the free tier).
+
+The child citation Actor (johnvc/google-ai-overview-api), billed to your account separately:
+
+- Setup: about $0.01 per run.
+- AI Overview retrieval: about $0.015 each, and Google defers some answers, so budget 1 to 2 retrievals per query.
+
+Combined estimate per run, where N is the number of scored queries:
+
+- This Actor: about $0.005 + (N x $0.002).
+- Child Actor: about $0.01 + (N x $0.015 to N x $0.030).
+
+Worked numbers:
+
+- 25 queries: this Actor about $0.055; child about $0.39 to $0.76; total about $0.44 to $0.82.
+- 50 queries: this Actor about $0.105; child about $0.76 to $1.51; total about $0.87 to $1.62.
+- 100 queries: this Actor about $0.205; child about $1.51 to $3.01; total about $1.72 to $3.22.
+
+The child retrievals dominate, so trimming the query list (a higher `min_impressions`, a shorter export) is the main lever.
+
+Suggested confirmation thresholds:
+
+- Combined estimate over $5: warn the user.
+- Combined estimate over $20: get explicit confirmation and set a run budget before launching.
+- Always present cost as "around $X", not a guarantee, because deferred answers add retrievals.
+
+## Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Run fails at startup | `target_domains` missing, or none of `search_console_csv_url` / `search_console_rows` / `queries` provided | Supply `target_domains` plus one query source. |
+| Everything lands in tier X | The join is not matching, or the citation check failed | Confirm `query` values match live queries, `target_domains` is set, and `min_impressions` is not filtering the whole list. |
+| Whole run shows `ai_overview_present` false | Non-English `hl`, unsupported country, or head terms that never trigger overviews | Keep `hl=en`, try `gl=us`, rephrase head terms as questions. Checks are still billed. |
+| Domain always reads competitor_cited | `target_domains` is too narrow to match a subdomain or apex variant | List every property you own; the Actor compares registered domains. |
+| Cost higher than expected | The child citation checks scale with query count | Raise `min_impressions`, shorten the export, and set a run budget. |
+
+## Scoring and join notes
+
+- Join rate: Search Console anonymizes long-tail queries, so a long-tail export will not fully match. Expect roughly 30 to 60 percent of a long-tail list to join. Unmatched queries get `join_status` unmatched, land in tier X, and are kept, never dropped.
+- Tier A is the highest-leverage bucket: a competitor is cited and you rank position 5 to 20. Work these first.
+- Tier C uses your own historical CTR for the query as the baseline, not an industry benchmark.
+- `citation_state` values: cited, competitor_cited, no_overview, overview_no_references, or null. Read it together with `reference_domains` and `cited_urls` to brief a rewrite.
+- AI Overviews vary between identical runs; confirm a tier A over a couple of runs before committing a large rewrite.
+- History key: `query` plus `fetched_at`. Re-run after shipping rewrites to confirm the tier moved.
+- The per-run summary in the key-value store is a quick read for tier counts before you page through the dataset.