@hybridlabor-api/bdb-antigravity-skills 1.0.0

package/skills/global_config/seo-audit/SKILL.md

@@ -0,0 +1,492 @@
+---
+name: seo-audit
+description: Diagnose and audit SEO issues affecting crawlability, indexation, rankings, and organic performance.
+risk: safe
+source: community
+date_added: '2026-02-27'
+---
+
+# SEO Audit
+
+You are an **SEO diagnostic specialist**.
+Your role is to **identify, explain, and prioritize SEO issues** that affect organic visibility—**not to implement fixes unless explicitly requested**.
+
+Your output must be **evidence-based, scoped, and actionable**.
+
+---
+
+## Scope Gate (Ask First if Missing)
+
+Before performing a full audit, clarify:
+
+1. **Business Context**
+
+   * Site type (SaaS, e-commerce, blog, local, marketplace, etc.)
+   * Primary SEO goal (traffic, conversions, leads, brand visibility)
+   * Target markets and languages
+
+2. **SEO Focus**
+
+   * Full site audit or specific sections/pages?
+   * Technical SEO, on-page, content, or all?
+   * Desktop, mobile, or both?
+
+3. **Data Access**
+
+   * Google Search Console access?
+   * Analytics access?
+   * Known issues, penalties, or recent changes (migration, redesign, CMS change)?
+
+If critical context is missing, **state assumptions explicitly** before proceeding.
+
+---
+
+## Audit Framework (Priority Order)
+
+1. **Crawlability & Indexation** – Can search engines access and index the site?
+2. **Technical Foundations** – Is the site fast, stable, and accessible?
+3. **On-Page Optimization** – Is each page clearly optimized for its intent?
+4. **Content Quality & E-E-A-T** – Does the content deserve to rank?
+5. **Authority & Signals** – Does the site demonstrate trust and relevance?
+
+---
+
+## Technical SEO Audit
+
+### Crawlability
+
+**Robots.txt**
+
+* Accidental blocking of important paths
+* Sitemap reference present
+* Environment-specific rules (prod vs staging)
+
+**XML Sitemaps**
+
+* Accessible and valid
+* Contains only canonical, indexable URLs
+* Reasonable size and segmentation
+* Submitted and processed successfully
+
+**Site Architecture**
+
+* Key pages within ~3 clicks
+* Logical hierarchy
+* Internal linking coverage
+* No orphaned URLs
+
+**Crawl Efficiency (Large Sites)**
+
+* Parameter handling
+* Faceted navigation controls
+* Infinite scroll with crawlable pagination
+* Session IDs avoided
+
+---
+
+### Indexation
+
+**Coverage Analysis**
+
+* Indexed vs expected pages
+* Excluded URLs (intentional vs accidental)
+
+**Common Indexation Issues**
+
+* Incorrect `noindex`
+* Canonical conflicts
+* Redirect chains or loops
+* Soft 404s
+* Duplicate content without consolidation
+
+**Canonicalization Consistency**
+
+* Self-referencing canonicals
+* HTTPS consistency
+* Hostname consistency (www / non-www)
+* Trailing slash rules
+
+---
+
+### Performance & Core Web Vitals
+
+**Key Metrics**
+
+* LCP < 2.5s
+* INP < 200ms
+* CLS < 0.1
+
+**Contributing Factors**
+
+* Server response time
+* Image handling
+* JavaScript execution cost
+* CSS delivery
+* Caching strategy
+* CDN usage
+* Font loading behavior
+
+---
+
+### Mobile-Friendliness
+
+* Responsive layout
+* Proper viewport configuration
+* Tap target sizing
+* No horizontal scrolling
+* Content parity with desktop
+* Mobile-first indexing readiness
+
+---
+
+### Security & Accessibility Signals
+
+* HTTPS everywhere
+* Valid certificates
+* No mixed content
+* HTTP → HTTPS redirects
+* Accessibility issues that impact UX or crawling
+
+---
+
+## On-Page SEO Audit
+
+### Title Tags
+
+* Unique per page
+* Keyword-aligned
+* Appropriate length
+* Clear intent and differentiation
+
+### Meta Descriptions
+
+* Unique and descriptive
+* Supports click-through
+* Not auto-generated noise
+
+### Heading Structure
+
+* One clear H1
+* Logical hierarchy
+* Headings reflect content structure
+
+### Content Optimization
+
+* Satisfies search intent
+* Sufficient topical depth
+* Natural keyword usage
+* Not competing with other internal pages
+
+### Images
+
+* Descriptive filenames
+* Accurate alt text
+* Proper compression and formats
+* Responsive handling and lazy loading
+
+### Internal Linking
+
+* Important pages reinforced
+* Descriptive anchor text
+* No broken links
+* Balanced link distribution
+
+---
+
+## Content Quality & E-E-A-T
+
+### Experience & Expertise
+
+* First-hand knowledge
+* Original insights or data
+* Clear author attribution
+
+### Authoritativeness
+
+* Citations or recognition
+* Consistent topical focus
+
+### Trustworthiness
+
+* Accurate, updated content
+* Transparent business information
+* Policies (privacy, terms)
+* Secure site
+
+---
+## 🔢 SEO Health Index & Scoring Layer (Additive)
+
+### Purpose
+
+The **SEO Health Index** provides a **normalized, explainable score** that summarizes overall SEO health **without replacing detailed findings**.
+
+It is designed to:
+
+* Communicate severity at a glance
+* Support prioritization
+* Track improvement over time
+* Avoid misleading “one-number SEO” claims
+
+---
+
+## Scoring Model Overview
+
+### Total Score: **0–100**
+
+The score is a **weighted composite**, not an average.
+
+| Category                  | Weight  |
+| ------------------------- | ------- |
+| Crawlability & Indexation | 30      |
+| Technical Foundations     | 25      |
+| On-Page Optimization      | 20      |
+| Content Quality & E-E-A-T | 15      |
+| Authority & Trust Signals | 10      |
+| **Total**                 | **100** |
+
+> If a category is **out of scope**, redistribute its weight proportionally and state this explicitly.
+
+---
+
+## Category Scoring Rules
+
+Each category is scored **independently**, then weighted.
+
+### Per-Category Score: 0–100
+
+Start each category at **100** and subtract points based on issues found.
+
+#### Severity Deductions
+
+| Issue Severity                              | Deduction  |
+| ------------------------------------------- | ---------- |
+| Critical (blocks crawling/indexing/ranking) | −15 to −30 |
+| High impact                                 | −10        |
+| Medium impact                               | −5         |
+| Low impact / cosmetic                       | −1 to −3   |
+
+#### Confidence Modifier
+
+If confidence is **Medium**, apply **50%** of the deduction
+If confidence is **Low**, apply **25%** of the deduction
+
+---
+
+## Example (Category)
+
+> Crawlability & Indexation (Weight: 30)
+
+* Noindex on key category pages → Critical (−25, High confidence)
+* XML sitemap includes redirected URLs → Medium (−5, Medium confidence → −2.5)
+* Missing sitemap reference in robots.txt → Low (−2)
+
+**Raw score:** 100 − 29.5 = **70.5**
+**Weighted contribution:** 70.5 × 0.30 = **21.15**
+
+---
+
+## Overall SEO Health Index
+
+### Calculation
+
+```
+SEO Health Index =
+Σ (Category Score × Category Weight)
+```
+
+Rounded to nearest whole number.
+
+---
+
+## Health Bands (Required)
+
+Always classify the final score into a band:
+
+| Score Range | Health Status | Interpretation                                  |
+| ----------- | ------------- | ----------------------------------------------- |
+| 90–100      | Excellent     | Strong SEO foundation, minor optimizations only |
+| 75–89       | Good          | Solid performance with clear improvement areas  |
+| 60–74       | Fair          | Meaningful issues limiting growth               |
+| 40–59       | Poor          | Serious SEO constraints                         |
+| <40         | Critical      | SEO is fundamentally broken                     |
+
+---
+
+## Output Requirements (Scoring Section)
+
+Include this **after the Executive Summary**:
+
+### SEO Health Index
+
+* **Overall Score:** XX / 100
+* **Health Status:** [Excellent / Good / Fair / Poor / Critical]
+
+#### Category Breakdown
+
+| Category                  | Score | Weight | Weighted Contribution |
+| ------------------------- | ----- | ------ | --------------------- |
+| Crawlability & Indexation | XX    | 30     | XX                    |
+| Technical Foundations     | XX    | 25     | XX                    |
+| On-Page Optimization      | XX    | 20     | XX                    |
+| Content Quality & E-E-A-T | XX    | 15     | XX                    |
+| Authority & Trust         | XX    | 10     | XX                    |
+
+---
+
+## Interpretation Rules (Mandatory)
+
+* The score **does not replace findings**
+* Improvements must be traceable to **specific issues**
+* A high score with unresolved **Critical issues is invalid** → flag inconsistency
+* Always explain **what limits the score from being higher**
+
+---
+
+## Change Tracking (Optional but Recommended)
+
+If a previous audit exists:
+
+* Include **score delta** (+/−)
+* Attribute change to specific fixes
+* Avoid celebrating score increases without validating outcomes
+
+---
+
+## Explicit Limitations (Always State)
+
+* Score reflects **SEO readiness**, not guaranteed rankings
+* External factors (competition, algorithm updates) are not scored
+* Authority score is directional, not exhaustive
+
+### Findings Classification (Required · Scoring-Aligned)
+
+For **every identified issue**, provide the following fields.
+These fields are **mandatory** and directly inform the SEO Health Index.
+
+* **Issue**
+  A concise description of what is wrong (one sentence, no solution).
+
+* **Category**
+  One of:
+
+  * Crawlability & Indexation
+  * Technical Foundations
+  * On-Page Optimization
+  * Content Quality & E-E-A-T
+  * Authority & Trust Signals
+
+* **Evidence**
+  Objective proof of the issue (e.g. URLs, reports, headers, crawl data, screenshots, metrics).
+  *Do not rely on intuition or best-practice claims.*
+
+* **Severity**
+  One of:
+
+  * Critical (blocks crawling, indexation, or ranking)
+  * High
+  * Medium
+  * Low
+
+* **Confidence**
+  One of:
+
+  * High (directly observed, repeatable)
+  * Medium (strong indicators, partial confirmation)
+  * Low (indirect or sample-based)
+
+* **Why It Matters**
+  A short explanation of the SEO impact in plain language.
+
+* **Score Impact**
+  The point deduction applied to the relevant category **before weighting**, including confidence modifier.
+
+* **Recommendation**
+  What should be done to resolve the issue.
+  **Do not include implementation steps unless explicitly requested.**
+
+---
+
+### Prioritized Action Plan (Derived from Findings)
+
+The action plan must be **derived directly from findings and scores**, not subjective judgment.
+
+Group actions as follows:
+
+1. **Critical Blockers**
+
+   * Issues with *Critical severity*
+   * Issues that invalidate the SEO Health Index if unresolved
+   * Highest negative score impact
+
+2. **High-Impact Improvements**
+
+   * High or Medium severity issues with large cumulative score deductions
+   * Issues affecting multiple pages or templates
+
+3. **Quick Wins**
+
+   * Low or Medium severity issues
+   * Easy to fix with measurable score improvement
+
+4. **Longer-Term Opportunities**
+
+   * Structural or content improvements
+   * Items that improve resilience, depth, or authority over time
+
+For each action group:
+
+* Reference the **related findings**
+* Explain **expected score recovery range**
+* Avoid timelines unless explicitly requested
+
+---
+
+### Tools (Evidence Sources Only)
+
+Tools may be referenced **only to support evidence**, never as authority by themselves.
+
+Acceptable uses:
+
+* Demonstrating an issue exists
+* Quantifying impact
+* Providing reproducible data
+
+Examples:
+
+* Search Console (coverage, CWV, indexing)
+* PageSpeed Insights (field vs lab metrics)
+* Crawlers (URL discovery, metadata validation)
+* Log analysis (crawl behavior, frequency)
+
+Rules:
+
+* Do not rely on a single tool for conclusions
+* Do not report tool “scores” without interpretation
+* Always explain *what the data shows* and *why it matters*
+
+---
+
+### Related Skills (Non-Overlapping)
+
+Use these skills **only after the audit is complete** and findings are accepted.
+
+* **programmatic-seo**
+  Use when the action plan requires **scaling page creation** across many URLs.
+
+* **schema-markup**
+  Use when structured data implementation is approved as a remediation.
+
+* **page-cro**
+  Use when the goal shifts from ranking to **conversion optimization**.
+
+* **analytics-tracking**
+  Use when measurement gaps prevent confident auditing or score validation.
+
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/skills/global_config/seo-technical/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: seo-technical
+description: "Audit technical SEO across crawlability, indexability, security, URLs, mobile, Core Web Vitals, structured data, JavaScript rendering, and related platform signals like robots.txt and AI crawler access."
+risk: unknown
+source: "https://github.com/AgriciDaniel/claude-seo"
+date_added: "2026-03-21"
+user-invokable: true
+argument-hint: "[url]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+---
+
+# Technical SEO Audit
+
+## When to Use
+- Use when the user wants a technical SEO review focused on crawlability, indexability, performance, or rendering.
+- Use when auditing robots.txt, canonicalization, JavaScript SEO, Core Web Vitals, or AI crawler access.
+- Use when the task is infrastructure- and implementation-oriented rather than content-focused.
+
+## Categories
+
+### 1. Crawlability
+- robots.txt: exists, valid, not blocking important resources
+- XML sitemap: exists, referenced in robots.txt, valid format
+- Noindex tags: intentional vs accidental
+- Crawl depth: important pages within 3 clicks of homepage
+- JavaScript rendering: check if critical content requires JS execution
+- Crawl budget: for large sites (>10k pages), efficiency matters
+
+#### AI Crawler Management
+
+As of 2025-2026, AI companies actively crawl the web to train models and power AI search. Managing these crawlers via robots.txt is a critical technical SEO consideration.
+
+**Known AI crawlers:**
+
+| Crawler | Company | robots.txt token | Purpose |
+|---------|---------|-----------------|---------|
+| GPTBot | OpenAI | `GPTBot` | Model training |
+| ChatGPT-User | OpenAI | `ChatGPT-User` | Real-time browsing |
+| ClaudeBot | Anthropic | `ClaudeBot` | Model training |
+| PerplexityBot | Perplexity | `PerplexityBot` | Search index + training |
+| Bytespider | ByteDance | `Bytespider` | Model training |
+| Google-Extended | Google | `Google-Extended` | Gemini training (NOT search) |
+| CCBot | Common Crawl | `CCBot` | Open dataset |
+
+**Key distinctions:**
+- Blocking `Google-Extended` prevents Gemini training use but does NOT affect Google Search indexing or AI Overviews (those use `Googlebot`)
+- Blocking `GPTBot` prevents OpenAI training but does NOT prevent ChatGPT from citing your content via browsing (`ChatGPT-User`)
+- ~3-5% of websites now use AI-specific robots.txt rules
+
+**Example, selective AI crawler blocking:**
+```
+# Allow search indexing, block AI training crawlers
+User-agent: GPTBot
+Disallow: /
+
+User-agent: Google-Extended
+Disallow: /
+
+User-agent: Bytespider
+Disallow: /
+
+# Allow all other crawlers (including Googlebot for search)
+User-agent: *
+Allow: /
+```
+
+**Recommendation:** Consider your AI visibility strategy before blocking. Being cited by AI systems drives brand awareness and referral traffic. Cross-reference the `seo-geo` skill for full AI visibility optimization.
+
+### 2. Indexability
+- Canonical tags: self-referencing, no conflicts with noindex
+- Duplicate content: near-duplicates, parameter URLs, www vs non-www
+- Thin content: pages below minimum word counts per type
+- Pagination: rel=next/prev or load-more pattern
+- Hreflang: correct for multi-language/multi-region sites
+- Index bloat: unnecessary pages consuming crawl budget
+
+### 3. Security
+- HTTPS: enforced, valid SSL certificate, no mixed content
+- Security headers:
+  - Content-Security-Policy (CSP)
+  - Strict-Transport-Security (HSTS)
+  - X-Frame-Options
+  - X-Content-Type-Options
+  - Referrer-Policy
+- HSTS preload: check preload list inclusion for high-security sites
+
+### 4. URL Structure
+- Clean URLs: descriptive, hyphenated, no query parameters for content
+- Hierarchy: logical folder structure reflecting site architecture
+- Redirects: no chains (max 1 hop), 301 for permanent moves
+- URL length: flag >100 characters
+- Trailing slashes: consistent usage
+
+### 5. Mobile Optimization
+- Responsive design: viewport meta tag, responsive CSS
+- Touch targets: minimum 48x48px with 8px spacing
+- Font size: minimum 16px base
+- No horizontal scroll
+- Mobile-first indexing: Google indexes mobile version. **Mobile-first indexing is 100% complete as of July 5, 2024.** Google now crawls and indexes ALL websites exclusively with the mobile Googlebot user-agent.
+
+### 6. Core Web Vitals
+- **LCP** (Largest Contentful Paint): target <2.5s
+- **INP** (Interaction to Next Paint): target <200ms
+  - INP replaced FID on March 12, 2024. FID was fully removed from all Chrome tools (CrUX API, PageSpeed Insights, Lighthouse) on September 9, 2024. Do NOT reference FID anywhere.
+- **CLS** (Cumulative Layout Shift): target <0.1
+- Evaluation uses 75th percentile of real user data
+- Use PageSpeed Insights API or CrUX data if MCP available
+
+### 7. Structured Data
+- Detection: JSON-LD (preferred), Microdata, RDFa
+- Validation against Google's supported types
+- See seo-schema skill for full analysis
+
+### 8. JavaScript Rendering
+- Check if content visible in initial HTML vs requires JS
+- Identify client-side rendered (CSR) vs server-side rendered (SSR)
+- Flag SPA frameworks (React, Vue, Angular) that may cause indexing issues
+- Verify dynamic rendering setup if applicable
+
+#### JavaScript SEO: Canonical & Indexing Guidance (December 2025)
+
+Google updated its JavaScript SEO documentation in December 2025 with critical clarifications:
+
+1. **Canonical conflicts:** If a canonical tag in raw HTML differs from one injected by JavaScript, Google may use EITHER one. Ensure canonical tags are identical between server-rendered HTML and JS-rendered output.
+2. **noindex with JavaScript:** If raw HTML contains `<meta name="robots" content="noindex">` but JavaScript removes it, Google MAY still honor the noindex from raw HTML. Serve correct robots directives in the initial HTML response.
+3. **Non-200 status codes:** Google does NOT render JavaScript on pages returning non-200 HTTP status codes. Any content or meta tags injected via JS on error pages will be invisible to Googlebot.
+4. **Structured data in JavaScript:** Product, Article, and other structured data injected via JS may face delayed processing. For time-sensitive structured data (especially e-commerce Product markup), include it in the initial server-rendered HTML.
+
+**Best practice:** Serve critical SEO elements (canonical, meta robots, structured data, title, meta description) in the initial server-rendered HTML rather than relying on JavaScript injection.
+
+### 9. IndexNow Protocol
+- Check if site supports IndexNow for Bing, Yandex, Naver
+- Supported by search engines other than Google
+- Recommend implementation for faster indexing on non-Google engines
+
+## Output
+
+### Technical Score: XX/100
+
+### Category Breakdown
+| Category | Status | Score |
+|----------|--------|-------|
+| Crawlability | pass/warn/fail | XX/100 |
+| Indexability | pass/warn/fail | XX/100 |
+| Security | pass/warn/fail | XX/100 |
+| URL Structure | pass/warn/fail | XX/100 |
+| Mobile | pass/warn/fail | XX/100 |
+| Core Web Vitals | pass/warn/fail | XX/100 |
+| Structured Data | pass/warn/fail | XX/100 |
+| JS Rendering | pass/warn/fail | XX/100 |
+| IndexNow | pass/warn/fail | XX/100 |
+
+### Critical Issues (fix immediately)
+### High Priority (fix within 1 week)
+### Medium Priority (fix within 1 month)
+### Low Priority (backlog)
+
+## DataForSEO Integration (Optional)
+
+If DataForSEO MCP tools are available, use `on_page_instant_pages` for real page analysis (status codes, page timing, broken links, on-page checks), `on_page_lighthouse` for Lighthouse audits (performance, accessibility, SEO scores), and `domain_analytics_technologies_domain_technologies` for technology stack detection.
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| URL unreachable | Report connection error with status code. Suggest verifying URL, checking DNS resolution, and confirming the site is publicly accessible. |
+| robots.txt not found | Note that no robots.txt was detected at the root domain. Recommend creating one with appropriate directives. Continue audit on remaining categories. |
+| HTTPS not configured | Flag as a critical issue. Report whether HTTP is served without redirect, mixed content exists, or SSL certificate is missing/expired. |
+| Core Web Vitals data unavailable | Note that CrUX data is not available (common for low-traffic sites). Suggest using Lighthouse lab data as a proxy and recommend increasing traffic before re-testing. |
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.