antigravity-seo-kit 2.0.0

package/.agent/skills/seo-maps/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: seo-maps
+description: >
+  Maps intelligence for local SEO — geo-grid rank tracking, GBP profile
+  auditing via API, review intelligence across Google/Tripadvisor/Trustpilot,
+  cross-platform NAP verification (Google/Bing/Apple/OSM), competitor
+  radius mapping, and LocalBusiness schema generation from API data.
+  Three-tier capability: free (Overpass + Geoapify), DataForSEO (full
+  intelligence), DataForSEO + Google (maximum coverage). Use when user
+  says "maps", "geo-grid", "rank tracking", "GBP audit", "review
+  velocity", "competitor radius", "maps analysis", "local rank
+  tracking", "Share of Local Voice", or "SoLV".
+---
+
+# Maps Intelligence (March 2026)
+
+Maps platform analysis for local businesses. Works with external APIs to assess
+how a business appears on Google Maps, Bing Places, Apple Maps, and OpenStreetMap.
+
+**Boundary with seo-local:** This skill analyzes the business on maps PLATFORMS
+(via APIs). seo-local analyzes local SEO signals on the WEBSITE (via HTML fetch).
+Do not duplicate seo-local on-page analysis. Recommend `/seo local <url>` for
+website-level checks.
+
+---
+
+## Quick Reference
+
+| Command | What it does | Tier |
+|---------|-------------|------|
+| `/seo maps <url>` | Full maps presence audit (auto-selects tier) | 0+ |
+| `/seo maps grid <keyword> <location>` | Geo-grid rank scan (7x7, 1 keyword default) | 1+ |
+| `/seo maps reviews <business> <location>` | Cross-platform review intelligence | 1+ |
+| `/seo maps competitors <keyword> <location>` | Competitor radius mapping | 0+ |
+| `/seo maps nap <business-name>` | Cross-platform NAP verification | 0+ |
+| `/seo maps schema <business-name>` | Generate LocalBusiness JSON-LD from data | 0+ |
+| `/seo maps gbp <business> <location>` | GBP completeness audit | 1+ |
+
+---
+
+## Three-Tier Capability Detection
+
+Before any analysis, detect the available capability tier:
+
+### Tier 0 (Free)
+**Detection:** DataForSEO MCP tools NOT available.
+**Capabilities:** Overpass API competitor discovery, Geoapify POI search, Nominatim geocoding, static GBP checklist, schema generation, cross-platform NAP guidance.
+**Load:** `references/maps-free-apis.md`
+
+### Tier 1 (DataForSEO)
+**Detection:** `business_data_business_listings_search` MCP tool IS available.
+**Capabilities:** Everything in Tier 0 PLUS geo-grid rank tracking, live GBP profile audit, review intelligence (velocity, sentiment, distribution), GBP post activity, Q&A data, Tripadvisor/Trustpilot reviews.
+**Load:** `references/maps-api-endpoints.md`
+
+### Tier 2 (DataForSEO + Google Maps Platform)
+**Detection:** Tier 1 available AND Google Maps API key in environment.
+**Capabilities:** Everything in Tier 1 PLUS Google Places details, real-time business status, AI-powered place summaries, photo analysis.
+**Note:** Google ToS restricts storage to `place_id` only. Lat/lng cached 30 days max.
+
+**Always communicate the detected tier to the user** at the start of analysis.
+
+---
+
+## Geo-Grid Rank Tracking (Tier 1+)
+
+Simulates Google Maps searches from multiple GPS coordinates to show ranking
+variation across a geographic area. Requires DataForSEO.
+
+**Load:** `references/maps-geo-grid.md` for algorithm, SoLV formula, heatmap format.
+**Load:** `references/maps-api-endpoints.md` for Maps SERP endpoint details.
+
+### Workflow
+
+1. Geocode business address to get center lat/lng
+2. Generate grid points (default: 7x7, 5km radius) using Haversine offset formula
+3. **Display cost estimate and ask for confirmation before proceeding**
+4. Fire DataForSEO Maps SERP API calls with `location_coordinate` per grid point
+5. Find target business rank at each point
+6. Calculate SoLV: `(top_3_count / total_points) * 100`
+7. Render ASCII heatmap in output
+
+### Cost Warning (REQUIRED)
+
+Before every geo-grid scan, display:
+```
+Geo-Grid Scan: [keyword] at [location]
+Grid: 7x7 (49 points) | Keywords: [N] | Est. cost: $[amount]
+DataForSEO credits will be consumed. Proceed?
+```
+
+---
+
+## GBP Profile Audit (Tier 1 preferred, Tier 0 manual)
+
+Audits the 25 fields that affect Google Business Profile quality and ranking.
+
+**Load:** `references/maps-gbp-checklist.md` for full checklist and scoring.
+
+### Tier 1 Workflow
+
+1. Fetch business profile via DataForSEO My Business Info API (keyword or CID)
+2. Map API response fields to 25-field checklist
+3. Score each field: Present + Optimized = 2pts, Present = 1pt, Missing = 0pts
+4. Apply industry-specific weight multipliers
+5. Normalize to 0-100 scale
+
+### Tier 0 Workflow
+
+1. Fetch the business website via WebFetch
+2. Extract any visible GBP signals (Maps embed, place references, review widgets)
+3. Apply static checklist based on detectable signals
+4. Mark undetectable fields as "Unknown (requires DataForSEO for live data)"
+
+---
+
+## Review Intelligence (Tier 1+)
+
+Cross-platform review analysis: velocity, sentiment, rating distribution, fake detection.
+
+**Reference:** `references/local-seo-signals.md` for benchmarks (shared with seo-local).
+
+### Workflow
+
+1. Fetch Google reviews via DataForSEO Reviews API (sort by newest)
+2. Calculate review velocity: reviews per month over last 6 months
+3. Check 18-day rule (Sterling Sky): any 3-week gap = ranking risk
+4. Analyze rating distribution: healthy = bell curve skewed to 5-star
+5. Calculate owner response rate: responses / total reviews
+6. Fetch Tripadvisor and Trustpilot reviews (if available)
+7. Cross-platform comparison table
+
+### Fake Review Detection Signals
+
+Flag reviews matching 2+ of these patterns:
+- Uniform timing (multiple reviews same day/hour)
+- Reviewer accounts with limited history or single review
+- Geographic inconsistencies (reviewer location vs business location)
+- Exclusively 5-star velocity spike (vs historical baseline)
+- Identical or near-identical text across reviews
+- Sudden volume spike without corresponding marketing activity
+
+---
+
+## Competitor Radius Mapping (Tier 0+)
+
+Identify and analyze competitors within a defined radius.
+
+### Tier 0 (Overpass API)
+
+**Load:** `references/maps-free-apis.md` for query templates.
+
+1. Geocode business address
+2. Query Overpass API for businesses with same OSM tag within radius
+3. Parse results: name, address, phone, website, distance from center
+4. Sort by distance, present as competitor landscape table
+
+### Tier 1 (DataForSEO)
+
+1. Use Maps SERP API with business keyword + location
+2. Extract top 20 competitors with full profile data
+3. Compare: rating, review count, categories, photos, attributes
+4. Calculate competitive density score: competitors per km^2
+
+---
+
+## Cross-Platform NAP Verification (Tier 0+)
+
+Check business listing consistency across Google, Bing Places, Apple, and OSM.
+
+### Workflow
+
+1. Search for business name on each platform:
+   - Google: infer from GBP data or Maps SERP result
+   - Bing: `WebFetch https://www.bing.com/maps?q=BUSINESS+NAME+LOCATION`
+   - Apple: manual check (no public API -- recommend Apple Business Connect at businessconnect.apple.com)
+   - OSM: Overpass or Nominatim search
+2. Extract NAP (Name, Address, Phone) from each source
+3. Compare for consistency: exact match, partial match, missing, or conflicting
+4. Flag discrepancies as Critical (name mismatch), High (address mismatch), Medium (phone mismatch)
+5. Recommend claiming unclaimed profiles
+
+---
+
+## Schema Generation (Tier 0+)
+
+Generate LocalBusiness JSON-LD markup from collected data.
+
+**Reference:** `references/local-schema-types.md` for industry subtypes (shared with seo-local).
+
+### Workflow
+
+1. Determine most specific schema subtype for the industry
+2. Populate required properties: `@type`, `name`, `address`, `image`
+3. Add recommended properties: `telephone`, `url`, `geo`, `openingHoursSpecification`, `priceRange`
+4. Add strategic properties for multi-location: `branchOf`, `areaServed`, `sameAs`
+5. Add `aggregateRating` if review data available
+6. Output valid JSON-LD block ready for implementation
+
+**Do NOT generate self-serving review markup** -- Google ignores LocalBusiness review markup from the business itself. Only mark up third-party reviews visible on the page.
+
+---
+
+## Reference Files
+
+Load on-demand as needed (do NOT load all at startup):
+- `references/maps-api-endpoints.md`: DataForSEO endpoint details, params, costs
+- `references/maps-free-apis.md`: Overpass, Geoapify, Nominatim query templates
+- `references/maps-geo-grid.md`: Grid algorithm, SoLV formula, heatmap rendering
+- `references/maps-gbp-checklist.md`: 25-field GBP audit with industry weights
+- `references/local-seo-signals.md`: Ranking factors, review benchmarks (shared)
+- `references/local-schema-types.md`: LocalBusiness subtypes by industry (shared)
+
+---
+
+## Output
+
+Generate `MAPS-ANALYSIS-{domain}.md` with:
+
+1. **Maps Health Score: XX/100** with dimension breakdown table
+2. **Capability tier detected** (Tier 0 or Tier 1) with explanation of what's available
+3. **Geo-grid heatmap** (Tier 1): ASCII grid with SoLV percentage and average rank
+4. **GBP profile audit**: field-by-field scoring with industry-specific weights
+5. **Review intelligence**: velocity chart, rating distribution, response rate, cross-platform comparison
+6. **Competitor landscape**: count in radius, top 5 by rating/reviews, competitive density
+7. **Cross-platform presence**: Google/Bing/Apple/OSM listing status
+8. **Schema recommendation**: generated LocalBusiness JSON-LD (if missing or incomplete)
+9. **Top 10 prioritized actions** (Critical > High > Medium > Low)
+10. **Cost report**: DataForSEO credits consumed during analysis (Tier 1 only)
+11. **Limitations disclaimer**: what could not be assessed at current tier
+
+---
+
+## Cross-Skill Delegation
+
+- Website on-page local signals: recommend `/seo local <url>`
+- Full AI search visibility: recommend `/seo geo <url>`
+- Schema validation and fixes: recommend `/seo schema <url>`
+- Live SERP and keyword data: recommend `/seo dataforseo [command]`
+
+---
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| DataForSEO MCP not available | Drop to Tier 0. Inform user: "DataForSEO not detected. Running free-tier analysis. For geo-grid tracking and review intelligence, install the DataForSEO extension." |
+| Business not found in Maps SERP | Try My Business Info with keyword. If still not found, report "Business not found in Google Maps for this location." |
+| Geocoding fails (Nominatim) | Ask user to provide coordinates or a more specific address. |
+| API rate limit hit | Report the limit. Suggest waiting or using standard (queued) method instead of live. |
+| No reviews found | Report zero review state. Recommend review generation strategy with 18-day cadence target. |
+| Multi-location detected | Ask user which location to analyze, or offer batch mode with per-location cost estimate. |
+
+
+## Specialist Role Instructions
+
+When operating as a specialist during audits:
+
+You are a Maps Intelligence specialist. When delegated tasks during an SEO audit or given a business URL/name:
+
+1. Detect capability tier: check if DataForSEO MCP tools are available (try `business_data_business_listings_search`). If available = Tier 1. If not = Tier 0 (free APIs only).
+2. Identify the target business: extract name, location, and category from the URL or provided context
+3. Geocode the business address using Nominatim (free) or DataForSEO (Tier 1)
+4. Run available analyses based on tier (see below)
+5. Score the business on the Maps Health Score rubric
+6. Generate structured report with prioritized recommendations
+
+## Tier 0 (Free) Capabilities
+
+- Competitor discovery via Overpass API (radius query by business category)
+- Structured POI search via Geoapify (if API key available)
+- Address geocoding via Nominatim (1 req/sec, include User-Agent header)
+- Static GBP completeness checklist (manual assessment from visible data)
+- LocalBusiness schema generation from collected data
+- Cross-platform NAP guidance (recommend claiming Google, Bing, Apple)
+
+## Tier 1 (DataForSEO) Additional Capabilities
+
+- Geo-grid rank tracking via Maps SERP API with `location_coordinate`
+- Live GBP profile audit via My Business Info API
+- Review intelligence via Reviews API (velocity, sentiment, distribution)
+- GBP post activity audit via My Business Updates API
+- Q&A gap analysis via Questions and Answers API
+- Cross-platform reviews (Tripadvisor, Trustpilot)
+- Business listings search for competitor discovery
+
+## Maps Health Score (0-100)
+
+| Dimension | Weight | Data Source |
+|-----------|--------|-------------|
+| Geo-Grid Visibility / SoLV | 25% | DataForSEO Maps SERP (Tier 1 only; skip and redistribute if Tier 0) |
+| GBP Profile Completeness | 20% | DataForSEO My Business Info (Tier 1) or manual checklist (Tier 0) |
+| Review Health | 20% | DataForSEO Reviews (Tier 1) or visible review signals (Tier 0) |
+| Cross-Platform Presence | 15% | WebFetch checks for Bing, Apple, OSM listings |
+| Competitor Position | 10% | Overpass/DataForSEO competitor count and relative rating |
+| Schema & AI Readiness | 10% | Schema detection + AI citation signal check |
+
+**Tier 0 weight redistribution:** When geo-grid is unavailable, redistribute its 25% across GBP (+10%), Review Health (+10%), Cross-Platform (+5%).
+
+## Reference Files
+
+Load on-demand:
+- `skills/seo/references/maps-api-endpoints.md`: DataForSEO endpoint details and costs
+- `skills/seo/references/maps-free-apis.md`: Overpass, Geoapify, Nominatim query templates
+- `skills/seo/references/maps-geo-grid.md`: Grid algorithm, SoLV calculation, heatmap rendering
+- `skills/seo/references/maps-gbp-checklist.md`: 25-field GBP audit checklist with industry weights
+- `skills/seo/references/local-seo-signals.md`: Ranking factors, review benchmarks (shared with seo-local)
+- `skills/seo/references/local-schema-types.md`: LocalBusiness subtypes by industry (shared with seo-local)
+
+## Cross-Skill Delegation
+
+- Do NOT duplicate seo-local on-page analysis. Recommend `/seo local <url>` for website-level checks.
+- Do NOT duplicate seo-geo AI visibility analysis. Recommend `/seo geo <url>` for full GEO audit.
+- Do NOT duplicate seo-schema validation. Recommend `/seo schema <url>` for schema fixes.
+
+## Output Format
+
+Provide a structured report with:
+- Maps Health Score (0-100) with dimension breakdown
+- Capability tier detected (Tier 0 or Tier 1)
+- Geo-grid heatmap (if Tier 1) with SoLV percentage
+- GBP profile completeness score with field-by-field breakdown
+- Review health snapshot (rating, count, velocity, response rate, cross-platform)
+- Competitor landscape (count in radius, top competitors by rating/reviews)
+- Cross-platform presence status (Google, Bing, Apple, OSM)
+- Generated LocalBusiness JSON-LD (if schema missing)
+- Top 10 prioritized actions (Critical > High > Medium > Low)
+- Cost report (DataForSEO credits consumed, if applicable)
+- Limitations disclaimer (what could not be assessed at current tier)

package/.agent/skills/seo-page/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: seo-page
+description: >
+  Deep single-page SEO analysis covering on-page elements, content quality,
+  technical meta tags, schema, images, and performance. Use when user says
+  "analyze this page", "check page SEO", or provides a single URL for review.
+---
+
+# Single Page Analysis
+
+## What to Analyze
+
+### On-Page SEO
+- Title tag: 50-60 characters, includes primary keyword, unique
+- Meta description: 150-160 characters, compelling, includes keyword
+- H1: exactly one, matches page intent, includes keyword
+- H2-H6: logical hierarchy (no skipped levels), descriptive
+- URL: short, descriptive, hyphenated, no parameters
+- Internal links: sufficient, relevant anchor text, no orphan pages
+- External links: to authoritative sources, reasonable count
+
+### Content Quality
+- Word count vs page type minimums (see quality-gates.md)
+- Readability: Flesch Reading Ease score, grade level
+- Keyword density: natural (1-3%), semantic variations present
+- E-E-A-T signals: author bio, credentials, first-hand experience markers
+- Content freshness: publication date, last updated date
+
+### Technical Elements
+- Canonical tag: present, self-referencing or correct
+- Meta robots: index/follow unless intentionally blocked
+- Open Graph: og:title, og:description, og:image, og:url
+- Twitter Card: twitter:card, twitter:title, twitter:description
+- Hreflang: if multi-language, correct implementation
+
+### Schema Markup
+- Detect all types (JSON-LD preferred)
+- Validate required properties
+- Identify missing opportunities
+- NEVER recommend HowTo (deprecated) or FAQ (restricted to gov/health)
+
+### Images
+- Alt text: present, descriptive, includes keywords where natural
+- File size: flag >200KB (warning), >500KB (critical)
+- Format: recommend WebP/AVIF over JPEG/PNG
+- Dimensions: width/height set for CLS prevention
+- Lazy loading: loading="lazy" on below-fold images
+
+### Core Web Vitals (reference only, not measurable from HTML alone)
+- Flag potential LCP issues (huge hero images, render-blocking resources)
+- Flag potential INP issues (heavy JS, no async/defer)
+- Flag potential CLS issues (missing image dimensions, injected content)
+
+## Output
+
+### Page Score Card
+```
+Overall Score: XX/100
+
+On-Page SEO:     XX/100  ████████░░
+Content Quality: XX/100  ██████████
+Technical:       XX/100  ███████░░░
+Schema:          XX/100  █████░░░░░
+Images:          XX/100  ████████░░
+```
+
+### Issues Found
+Organized by priority: Critical -> High -> Medium -> Low
+
+### Recommendations
+Specific, actionable improvements with expected impact
+
+### Schema Suggestions
+Ready-to-use JSON-LD code for detected opportunities
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `serp_organic_live_advanced` for real SERP positions and `backlinks_summary` for backlink data and spam scores.
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable (DNS failure, connection refused) | Report the error clearly. Do not guess page content. Suggest the user verify the URL and try again. |
+| Page requires authentication (401/403) | Report that the page is behind authentication. Suggest the user provide the rendered HTML directly or a publicly accessible URL. |
+| JavaScript-rendered content (empty body in HTML) | Note that key content may be rendered client-side. Analyze the available HTML and flag that results may be incomplete. Suggest using a browser-rendered snapshot if available. |

package/.agent/skills/seo-plan/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: seo-plan
+description: >
+  Strategic SEO planning for new or existing websites. Industry-specific
+  templates, competitive analysis, content strategy, and implementation
+  roadmap. Use when user says "SEO plan", "SEO strategy", "content strategy",
+  "site architecture", or "SEO roadmap".
+---
+
+# Strategic SEO Planning
+
+## Process
+
+### 1. Discovery
+- Business type, target audience, competitors, goals
+- Current site assessment (if exists)
+- Budget and timeline constraints
+- Key performance indicators (KPIs)
+
+### 2. Competitive Analysis
+- Identify top 5 competitors
+- Analyze their content strategy, schema usage, technical setup
+- Identify keyword gaps and content opportunities
+- Assess their E-E-A-T signals
+- Estimate their domain authority
+
+### 3. Architecture Design
+- Load industry template from `assets/` directory
+- Design URL hierarchy and content pillars
+- Plan internal linking strategy
+- Sitemap structure with quality gates applied
+- Information architecture for user journeys
+
+### 4. Content Strategy
+- Content gaps vs competitors
+- Page types and estimated counts
+- Blog/resource topics and publishing cadence
+- E-E-A-T building plan (author bios, credentials, experience signals)
+- Content calendar with priorities
+
+### 5. Technical Foundation
+- Hosting and performance requirements
+- Schema markup plan per page type
+- Core Web Vitals baseline targets
+- AI search readiness requirements
+- Mobile-first considerations
+
+### 6. Implementation Roadmap (4 phases)
+
+#### Phase 1: Foundation (weeks 1-4)
+- Technical setup and infrastructure
+- Core pages (home, about, contact, main services)
+- Essential schema implementation
+- Analytics and tracking setup
+
+#### Phase 2: Expansion (weeks 5-12)
+- Content creation for primary pages
+- Blog launch with initial posts
+- Internal linking structure
+- Local SEO setup (if applicable)
+
+#### Phase 3: Scale (weeks 13-24)
+- Advanced content development
+- Link building and outreach
+- GEO optimization
+- Performance optimization
+
+#### Phase 4: Authority (months 7-12)
+- Thought leadership content
+- PR and media mentions
+- Advanced schema implementation
+- Continuous optimization
+
+## Industry Templates
+
+Load from `assets/` directory:
+- `saas.md`: SaaS/software companies
+- `local-service.md`: Local service businesses
+- `ecommerce.md`: E-commerce stores
+- `publisher.md`: Content publishers/media
+- `agency.md`: Agencies and consultancies
+- `generic.md`: General business template
+
+## Output
+
+### Deliverables
+- `SEO-STRATEGY.md`: Complete strategic plan
+- `COMPETITOR-ANALYSIS.md`: Competitive insights
+- `CONTENT-CALENDAR.md`: Content roadmap
+- `IMPLEMENTATION-ROADMAP.md`: Phased action plan
+- `SITE-STRUCTURE.md`: URL hierarchy and architecture
+
+### KPI Targets
+| Metric | Baseline | 3 Month | 6 Month | 12 Month |
+|--------|----------|---------|---------|----------|
+| Organic Traffic | ... | ... | ... | ... |
+| Keyword Rankings | ... | ... | ... | ... |
+| Domain Authority | ... | ... | ... | ... |
+| Indexed Pages | ... | ... | ... | ... |
+| Core Web Vitals | ... | ... | ... | ... |
+
+### Success Criteria
+- Clear, measurable goals per phase
+- Resource requirements defined
+- Dependencies identified
+- Risk mitigation strategies
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `dataforseo_labs_google_competitors_domain` and `dataforseo_labs_google_domain_intersection` for real competitive intelligence, `dataforseo_labs_bulk_traffic_estimation` for traffic estimates, `kw_data_google_ads_search_volume` and `dataforseo_labs_bulk_keyword_difficulty` for keyword research, and `business_data_business_listings_search` for local business data.
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Unrecognized business type | Fall back to `generic.md` template. Inform user that no industry-specific template was found and proceed with the general business template. |
+| No website URL provided | Proceed with new-site planning mode. Skip current site assessment and competitive gap analysis that require a live URL. |
+| Industry template not found | Check `assets/` directory for available templates. If the requested template file is missing, use `generic.md` and note the missing template in output. |