ls ~/.toprank/business-context/*.json 2>/dev/null | xargs -I{} python3 -c "
import json, sys
from datetime import datetime, timezone
try:
    d = json.load(open(sys.argv[1]))
    gen = datetime.fromisoformat(d.get('generated_at', '1970-01-01T00:00:00+00:00'))
    age = (datetime.now(timezone.utc) - gen.astimezone(timezone.utc)).days
    print(f\"{d.get('target_url', d.get('domain','?'))} (audited {age}d ago)\")
except: pass
" {}

"I've audited these sites before — use one, or enter a different URL:

1. https://example.com (audited 12 days ago)
2. Enter a different URL"

target_url

~/.toprank/business-context/<domain>.json

$TARGET_URL

"What is the main URL of the website you want to audit? (e.g. https://yoursite.com)"

$TARGET_URL

• package.json

  →

  "homepage"

  field or scripts with domain hints

• next.config.js

  /

  next.config.ts

  →

  env.NEXT_PUBLIC_SITE_URL

  or

  basePath

• astro.config.*

  →

  site:

  field

• gatsby-config.js

  →

  siteMetadata.siteUrl

• hugo.toml

  /

  hugo.yaml

  →

  baseURL

• _config.yml

  (Jekyll) →

  url

  field

• .env

  or

  .env.local

  →

  NEXT_PUBLIC_SITE_URL

  ,

  SITE_URL

  ,

  PUBLIC_URL

• vercel.json

  → deployment aliases

• CNAME

  file (GitHub Pages)

https://detected.com

$TARGET_URL

DOMAIN=$(python3 -c "import sys; from urllib.parse import urlparse; print(urlparse(sys.argv[1]).netloc.lstrip('www.'))" "$TARGET_URL")
AUDIT_LOG="$HOME/.toprank/audit-log/${DOMAIN}.json"
[ -f "$AUDIT_LOG" ] && cat "$AUDIT_LOG" || echo "NOT_FOUND"

$DOMAIN

date

top_issues

"Last audit: [date]. Previously flagged: [issue #1 title], [issue #2 title]. I'll check whether these are resolved."

../shared/preamble.md

PAGESPEED_API_KEY

"For reliable PageSpeed analysis, create an API key at https://console.cloud.google.com/apis/credentials and set

export PAGESPEED_API_KEY='your-key'

or add it to

~/.toprank/.env

."

Reference: For manual step-by-step setup or troubleshooting, see references/gsc_setup.md.

../shared/business-context.md

CACHE_STATUS

fresh_loaded

stale

not_found

CACHE_STATUS=fresh_loaded

brand_terms

BRAND_TERMS

CACHE_STATUS=stale

not_found

"What's your brand name? Enter one or more comma-separated terms (e.g.

Acme, AcmeCorp, acme.io

) — used to separate branded from non-branded traffic. Press Enter to skip."

BRAND_TERMS

sc-domain:example.com

https://example.com/

sc-domain:example.com

analyze_gsc.py

{target_url}/robots.txt

python3 "$SKILL_SCRIPTS/analyze_gsc.py" \
  --site "sc-domain:example.com" \
  --days 90 \
  --brand-terms "$BRAND_TERMS"

--brand-terms

$BRAND_TERMS

analyze_gsc.py

python3 "$SKILL_SCRIPTS/show_gsc.py"

branded_split

comparison

• Top queries by impressions, clicks, CTR, average position
• Top pages by clicks + impressions
• Position buckets — queries in 1-3, 4-10, 11-20, 21+ (the "striking distance" opportunities)
• Queries losing clicks — comparing last 28 days vs the prior 28 days
• Pages losing traffic — same comparison
• CTR opportunities (

  ctr_opportunities

  ) — query-level: high impressions, low CTR, title/snippet targets
• CTR gaps by page (

  ctr_gaps_by_page

  ) — query+page level: shows exactly which page to rewrite for each underperforming query
• Cannibalization (

  cannibalization

  ) — queries where multiple pages compete, with per-page click/impression split
• Device split — mobile vs desktop vs tablet clicks, impressions, CTR, position
• Country split (

  country_split

  ) — top 20 countries by clicks with CTR and position
• Search type breakdown (

  search_type_split

  ) — web vs image vs video vs news vs Discover vs Google News traffic
• Branded vs non-branded split (

  branded_split

  ) — separate aggregates for queries containing brand terms vs pure organic;

  null

  if no brand terms provided
• Page groups (

  page_groups

  ) — traffic aggregated by site section (/blog/, /products/, /locations/, etc.) with per-section clicks, impressions, CTR, and average position

analyze_gsc.py

1. Phase 3.5: run

   url_inspection.py

   (Bash tool)
2. Phase 3.6: detect CMS with

   cms_detect.py

   , then run the appropriate preflight + fetch if configured (Bash tool)
3. Phase 5 pre-fetch: fetch

   robots.txt

   , the homepage, and up to 4 top pages via WebFetch — all in parallel
4. Phase 5.5: run

   pagespeed.py

   for the homepage + top pages by clicks (Bash tool) — this calls the PageSpeed Insights API which is independent of GSC auth

robots.txt

{target_url}/robots.txt

analyze_gsc.py

python3 "$SKILL_SCRIPTS/url_inspection.py" \
  --site "sc-domain:example.com" \
  --urls "/path/to/page1,/path/to/page2,..."

POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect

• Indexing status:

  INDEXED

  ,

  NOT_INDEXED

  ,

  SUBMITTED_AND_INDEXED

  ,

  DUPLICATE_WITHOUT_CANONICAL

  ,

  CRAWLED_CURRENTLY_NOT_INDEXED

  , etc.
• Mobile usability verdict:

  MOBILE_FRIENDLY

  or issues found
• Rich result status: which rich result types were detected and their verdict
• Last crawl time: when Googlebot last visited
• Referring sitemaps: which sitemap(s) reference this URL
• Coverage state: full coverage detail from the Index Coverage report

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/webmasters.readonly

url_inspection.py

• Any top-traffic page that is

  NOT_INDEXED

  or

  CRAWLED_CURRENTLY_NOT_INDEXED

  — this is a critical issue. Identify which page, what the coverage state says, and what likely caused it (noindex tag, canonical pointing elsewhere, robots blocking, soft 404).
• Pages with

  DUPLICATE_WITHOUT_CANONICAL

  — these are leaking authority. The canonical needs to be set.
• Pages where mobile usability is failing — cross-reference with device split from Phase 3 to confirm whether mobile traffic is below par.
• Pages with no referring sitemaps — if they are important pages, they should be in a sitemap.
• Pages with rich result errors where schema exists — this pre-validates Phase 5 structured data findings.
• Pages whose last crawl time is more than 60 days ago despite having traffic — crawl budget issue or accidental de-prioritization.

CMS_TYPE=$(python3 "$SKILL_SCRIPTS/cms_detect.py" 2>/dev/null)
CMS_DETECT_EXIT=$?

• Exit code 2 → no CMS configured. Skip this phase entirely, no mention needed.
• Exit code 0 → CMS detected. Run the matching preflight below.

UID_STR=$(python3 -c "import os; print(os.getuid())")
CMS_CONTENT_FILE="/tmp/cms_content_${UID_STR}.json"

case "$CMS_TYPE" in
  strapi)
    python3 "$SKILL_SCRIPTS/preflight_strapi.py"
    CMS_PREFLIGHT=$?
    [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_strapi_content.py" --output "$CMS_CONTENT_FILE"
    ;;
  wordpress)
    python3 "$SKILL_SCRIPTS/preflight_wordpress.py"
    CMS_PREFLIGHT=$?
    [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_wordpress_content.py" --output "$CMS_CONTENT_FILE"
    ;;
  contentful)
    python3 "$SKILL_SCRIPTS/preflight_contentful.py"
    CMS_PREFLIGHT=$?
    [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_contentful_content.py" --output "$CMS_CONTENT_FILE"
    ;;
  ghost)
    python3 "$SKILL_SCRIPTS/preflight_ghost.py"
    CMS_PREFLIGHT=$?
    [ "$CMS_PREFLIGHT" = "0" ] && python3 "$SKILL_SCRIPTS/fetch_ghost_content.py" --output "$CMS_CONTENT_FILE"
    ;;
esac

• 0 → ready. Content fetched to

  $CMS_CONTENT_FILE

  . Load it and use the data in Phase 4.
• 2 → not configured. Skip silently.
• 1 → auth/config error. Show the error and ask the user if they want to fix it (suggest

  /setup-cms

  ) or continue without CMS data.

$CMS_CONTENT_FILE

cms_content.entries

slug

>200

updated_at

comparison.declining_pages

cms_content.seo_audit

• missing_meta_title

  — entries with no meta title set

• missing_meta_description

  — entries with no meta description set

• meta_title_too_long

  — meta titles over 60 characters

• meta_description_too_short/too_long

  — outside 70-160 char range

"I can push the meta title/description fixes directly to Strapi. Want me to apply them?"

python3 "$SKILL_SCRIPTS/push_strapi_seo.py" \
  --document-id "<documentId>" \
  --meta-title "New title under 60 chars" \
  --meta-description "New description 70-160 chars."

"Run

/setup-cms

to connect WordPress, Strapi, Contentful, or Ghost."

1. GSC top queries (from Phase 3) — the actual words real visitors type. Group by search intent: who searches informational queries vs transactional vs commercial investigation? These are different people with different needs.
2. GSC top pages (from Phase 3) — which pages get traffic reveals what the site is known for (vs. what it claims on the homepage).
3. Homepage content (already fetched for Phase 5) — extract: what the business does, who they serve, value proposition, tone/vocabulary, conversion intent.
4. URL structure (from page groups in GSC) — /blog/ vs /products/ vs /pricing/ reveals different visitor segments.

"Based on your GSC data and site content, I've identified these visitor personas that will shape the recommendations:"

Persona	Searches like...	Goal
[name]	[2-3 example query patterns from GSC]	[goal]

"Let me know if any of these are off — otherwise I'll use them throughout the analysis."

$PERSONA_FILE

~/.toprank/personas/<domain>.json

<domain>

branded_split

• If branded CTR is significantly higher (expected — users know what they're looking for), note that non-branded metrics are the real measure of organic performance.
• If branded impressions are small vs total, the site has limited brand awareness — focus on non-branded growth.
• If branded queries are ranking below position 3, that's a reputation/brand issue to flag separately.
• Use non-branded metrics as the baseline for all Quick Wins and content recommendations — don't let branded traffic inflate the opportunity estimates.

1. Position 4-10 queries — ranking on page 1 but below the fold. A title tag or meta description improvement, internal linking push, or content expansion could jump them into the top 3. List the top 10 with current position, impressions, and a specific recommendation for each.
2. High-impression, low-CTR queries — use

   ctr_gaps_by_page

   (not just

   ctr_opportunities

   ) because it includes the exact page URL alongside the query. This means every recommendation can name the specific page to fix and the specific query driving impressions. For each, analyze the likely search intent (informational, transactional, navigational, commercial investigation) and suggest a title + description that matches it.
3. Queries dropping month-over-month — flag anything with >30% click decline. For each, hypothesize: is it seasonal? Did a competitor take the SERP feature? Did the page content drift from the query intent?

• Informational ("how to...", "what is...") → needs comprehensive content, FAQ schema
• Transactional ("buy...", "pricing...", "near me") → needs clear CTA, product schema, price
• Navigational ("brand name", "brand + product") → should be ranking #1, if not, investigate
• Commercial investigation ("best...", "vs...", "review") → needs comparison content, trust signals

cannibalization

• winner_page

  — the canonical page to keep (scored by best position, tiebreaker: most clicks)

• winner_reason

  — why it won (e.g. "best position (2.1)")

• loser_pages

  — pages to consolidate away

• recommended_action

  — either "consolidate: 301 redirect losers to winner or add canonical" or "monitor: possible SERP domination" (all pages in top 5, positions within 2 of each other)

• State the winner and losers explicitly — don't make the user figure it out
• Use

  recommended_action

  directly in your recommendation
• Flag queries where position is mediocre (5-15) despite high impressions — splitting is likely suppressing a potential top-3 ranking
• If

  recommended_action

  is "monitor: possible SERP domination", note this as a positive (owning multiple SERP spots) and skip the consolidation recommendation

top_pages

position_buckets

page_groups

• Low-CTR sections: if an entire section (e.g., all /products/ pages) has CTR well below site average, the issue is likely a template problem (title tag format, meta description format) — one fix improves all pages in that section.
• High-impression, low-click sections: signals ranking without converting — investigate intent mismatch or snippet quality across the section.
• Sections missing entirely: if /locations/ or /services/ doesn't appear, either those pages don't rank or they haven't been created.
• "other" group is large: means the site has custom URL patterns not covered by defaults — note this for the user so they can understand what's in "other."

device_split

country_split

• A country has high impressions but very low CTR (title/snippet not landing in that market)
• Position is much worse in one country vs others (local competitor or relevance gap)
• A country with meaningful impressions has near-zero clicks (potential hreflang or geo-targeting issue)

search_type_split

discover

googleNews

image

video

• Expand an existing page (if it partially covers the topic)
• Create a new page (if no page targets this topic)
• Create a content hub with internal linking (if there are 5+ related queries)

• Current clicks vs previous period
• % change
• Likely cause (seasonal, algorithm update, new competitor, content staleness, technical issue)
• Specific fix recommendation

top_queries

• The site ranks 4-20 for the query
• The page that ranks is NOT a page primarily about that topic (e.g., a homepage or a page written for a different keyword is accidentally ranking)
• There is no page on the site with that keyword prominently in the title, H1, or URL slug

• The query
• Current ranking page (URL) and position
• Monthly impressions
• Recommended action: "Create a new page targeting '[query]' — currently ranked #[N] from [URL] which is not dedicated to this topic. A dedicated page could realistically move from #[N] to top 5."

• Name the cluster (e.g., "pricing-related queries", "feature X how-to queries")
• List the queries in it, their positions, and their impressions
• Identify whether a pillar page exists that ties them together
• If no pillar page exists, recommend creating one and note the internal linking structure needed to funnel authority from cluster pages to the pillar

"I've identified [N] keyword gaps from your GSC data. For broader keyword discovery — including keywords you're NOT yet ranking for at all — run

/keyword-research

with your seed topics. That skill pulls from keyword databases and builds a full opportunity set beyond what GSC can see."

• Fetch and analyze

  robots.txt

  — is it blocking important paths? Are there unnecessary disallow rules?
• Check for

  noindex

  meta tags or

  X-Robots-Tag

  headers on important pages
• Check canonical URLs — self-referencing (good) or pointing elsewhere (investigate)
• Check for

  hreflang

  tags if the site targets multiple languages/regions
• Look for orphan pages (important pages with no internal links pointing to them)
• Cross-reference with URL Inspection findings from Phase 3.5 — any NOT_INDEXED page found there should be explained here with the root cause

<title>

<meta name="description">

1. Title vs top query alignment: For each page, look up the top 3 queries that page ranks for in

   ctr_gaps_by_page

   . Does the title tag contain the primary ranking query or a close variant? If the title is generic (e.g., "Home", "Services", "Blog") while the page ranks for specific queries, that is a mismatch — the title is failing to confirm relevance and hurting CTR.
2. Title length: Under 60 characters? Over 60 characters gets truncated in SERPs. Flag every page over the limit with the current character count and the truncated version as it would appear in Google.
3. Meta description: Present? 120-160 characters? Contains a call to action? If a page has no meta description, Google rewrites it — often pulling unhelpful boilerplate. Flag every missing description.
4. Duplicate titles: Are multiple pages using the same or very similar titles? List all duplicates found.
5. Open Graph tags:

   og:title

   ,

   og:description

   ,

   og:image

   present? Missing OG tags means social shares render with no preview — flag any page missing them, especially for content pages.

"I found [N] pages with metadata issues. Run

/meta-tags-optimizer

to generate optimized title tags and meta descriptions for each — it will use the GSC query data from this audit to write titles that match actual search demand."

• E-commerce (products, pricing, cart)
• Local business (address, phone, service area)
• SaaS / software (features, pricing, signup)
• Content / blog (articles, guides, tutorials)
• Professional services (agency, consultant, law firm)
• Media / news (articles published frequently)

<script type="application/ld+json">

@type

price

• Missing required fields for the

  @type

  (e.g., Product schema without

  name

  or

  offers

  )

• url

  properties using relative paths instead of absolute URLs
• Dates not in ISO 8601 format

• AggregateRating

  with

  ratingCount

  of 0 or missing
• Duplicate schema blocks for the same type on one page
• Schema that describes content not visible on the page (violates Google policy)

"I found [N] pages missing high-impact schema and [N] pages with errors in existing schema. Run

/schema-markup-generator

to generate correct JSON-LD for each — it will use the site type and page content from this audit."

• Render-blocking scripts in

  <head>

  — should be deferred or async
• Images: lazy-loaded? Have

  alt

  attributes? Served in modern formats (WebP/AVIF)? Properly sized (not 3000px wide in a 400px container)?

• <link rel="preload">

  for critical resources (fonts, above-the-fold images)?
• Excessive DOM size (>1500 nodes suggests bloat)?
• Third-party script bloat — count external domains loaded

• Does the page have internal links? Are they descriptive (not "click here")?
• Does the page link to related content (topic clusters)?
• Is the page reachable within 3 clicks from the homepage?
• Broken internal links (404s)?

• Viewport meta tag present?
• Touch targets large enough (48px minimum)?
• Text readable without zooming?
• No horizontal scrolling?
• Cross-reference mobile usability findings from Phase 3.5 URL Inspection

• 90-100 (Good): No action needed.
• 50-89 (Needs Work): Flag the top opportunities. These pages are losing rankings due to performance — Google uses Core Web Vitals as a ranking signal.
• 0-49 (Poor): Critical. These pages are actively penalized in rankings. Flag as a Priority Action if the page has significant organic traffic.

• LCP (Largest Contentful Paint): Good < 2.5s, Poor > 4.0s
• INP (Interaction to Next Paint): Good < 200ms, Poor > 500ms
• CLS (Cumulative Layout Shift): Good < 0.1, Poor > 0.25

• Phase 3 device split: If mobile performance score is significantly lower than desktop, and Phase 3 shows mobile traffic underperforming, the performance gap is likely a contributing factor.
• Phase 5 technical audit: Correlate specific opportunities (e.g., "Eliminate render-blocking resources") with the technical findings (e.g., render-blocking scripts in

  <head>

  ). This gives concrete evidence for technical fixes.
• Phase 3.5 URL Inspection: Pages flagged as mobile-unfriendly that also have poor mobile PageSpeed scores need urgent attention.

• What the opportunity is (e.g., "Properly size images", "Remove unused JavaScript")
• Estimated savings in milliseconds
• Which specific page(s) are affected
• Whether it's a site-wide template issue or page-specific

• [e.g., "Device split: mobile CTR 15% below desktop — worth watching but not the bottleneck right now"]
• [e.g., "Country split: weak CTR in UK — low volume, investigate after core issues fixed"]

"I found [N] pages with metadata issues — [X] with title/query mismatches, [Y] missing meta descriptions, [Z] missing OG tags. Run

/meta-tags-optimizer

to generate optimized tags for each page. Share the metadata audit table from this report as context."

"I found [N] pages missing high-impact schema and [N] pages with schema errors. Run

/schema-markup-generator

to generate correct JSON-LD. The schema audit table from this report is the input — it already identifies the site type and what schema types are needed per page."

"I found [N] keyword gaps from GSC data. For deeper discovery — keywords you are not ranking for at all — run

/keyword-research

with these seed topics: [list 3-5 seed terms derived from the gap analysis]. That skill pulls from keyword databases and builds a full opportunity set beyond what GSC can see."

"I found [N] content opportunities. Want me to draft the content? I can write [blog posts / landing pages / both] in parallel — each one optimized for the target keyword and search intent."

• Informational / commercial investigation → blog post agent
• Transactional / commercial → landing page agent

1. The content writing guidelines (located via find — see below)
2. The specific opportunity data from the analysis

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
  echo "Content reference at: $CONTENT_REF"
fi

$CONTENT_REF

1. Full post in markdown with proper heading hierarchy
2. SEO metadata (title tag, meta description, URL slug)
3. JSON-LD structured data (Article/BlogPosting + FAQPage if FAQ included)
4. Internal linking plan (which existing pages to link to/from)
5. Publishing checklist

• Would the reader need to search again? (If yes, not done)
• Does the post contain specific examples only an expert would include?
• Does the format match what Google shows for this query?
• Is every paragraph earning its place? (No filler)

undefined

1. Full page copy in markdown with proper heading hierarchy and CTA placements
2. SEO metadata (title tag, meta description, URL slug)
3. Conversion strategy (primary CTA, objections addressed, trust signals)
4. JSON-LD structured data
5. Internal linking plan
6. Publishing checklist

• Would you convert after reading this? (If not, what is missing?)
• Are there vague claims that should be replaced with specifics?
• Is every objection addressed?
• Is it clear what the visitor should do next?

undefined

• Spawn up to 5 content agents in parallel (more than 5 gets unwieldy — prioritize by impact)
• Prioritize opportunities by: impressions x position-improvement-potential
• Each agent works independently — they do not need to coordinate
• As agents complete, present each piece of content to the user with its metadata
• After all agents finish, provide a summary: what was generated, suggested publishing order (highest impact first), and any cross-linking between new pages