# AgentSkillsHub (pSEO High-Scale Framework)

A production-ready, pure-static programmatic SEO frontend framework built for AI Agent directories (Claude Code, Antigravity, Cursor, OpenAI Skills). Designed specifically to achieve indexation equilibrium ($M \approx N$) and eliminate crawl traps.

---

## 📊 1. Core Framework: The $N / M / X$ Indexation Health Model

Based on real production telemetry from [`agentskillshub.top`](http://agentskillshub.top):

| Metric | Case Study Value | Meaning | Health State & Problem Diagnosis |
| :--- | :--- | :--- | :--- |
| **$N$ (Total Generated)** | **~19,600** | Total indexable URLs created | **Generated set** |
| **Sitemap Submitted** | **4,050** | Submitted to GSC | ⚠️ **Huge Defect:** ~15,550 URLs missing from sitemap! |
| **$X$ (Google Discovered)** | **6,010** | URLs Google has encountered | ⚠️ **Crawl Blindness:** $N \gg X$, Google doesn't know 70% of the site |
| **$M$ (Google Indexed)** | **3,380** | URLs successfully in SERP | ⚠️ **Quality Barrier:** $X \gg M$, 2,630 crawled pages discarded |

### The Golden Rule
> **Healthy equilibrium:** $M \approx N$ and $X \rightarrow N$.
> - **$N \gg X$**: Crawl trap, orphan pages, or sitemap omissions.
> - **$X \gg M$**: Thin content, repetitive templates, or duplicate parameter URLs.

---

## ⚡ 2. The 6 Sudden Death Traps in pSEO & Solutions

| Trap | Failure Trigger | Architectural Mitigation in this Repo |
| :--- | :--- | :--- |
| **1. Batch Launching** | $N$ surges 10x overnight; $X$ & $M$ lag; domain flagged as spam. | **Quality Gates:** `getIndexableSkills()` filters out shallow content (<40 words) from XML sitemaps. |
| **2. Migrations & Renaming** | URLs change (e.g. `ppt-skills`); creates 404s in sitemaps. | `sitemap:validate` script checks 100% of sitemap URLs against static output. |
| **3. Parameter Explosion** | Filter/sort combinations multiply URLs infinitely ($N!$). | Self-referencing canonicals strip `?sort=`, `?page=`. `robots.txt` Disallows `/*?*`. |
| **4. Threshold Changes** | Bulk deletion creates 404/noindex cascade. | Deterministic quality criteria version-controlled in `src/config/site.ts`. |
| **5. Template-wide Bugs** | Canonical or robots error in single template affects 20k pages. | Centralized `<SEOHead />` component with automated pre-commit linting. |
| **6. Deployment Bugs** | Misconfigured `robots.txt` crashes index in 72h. | Automated `npm run check:all` runs before static deployment. |

---

## ⚠️ 3. Crucial SEO Law: `noindex` does NOT Save Crawl Budget

* **Misconception:** Putting `<meta name="robots" content="noindex">` on 50,000 filter URLs saves crawl budget.
* **Reality:** Googlebot **must make an HTTP request and download the HTML** to read the `noindex` tag. It still eats your crawl budget!
* **Correct Practice:**
  1. Filter/sorting is handled client-side without URL permutations.
  2. Dynamic query routes are disallowed in `robots.txt`:
     ```txt
     User-agent: *
     Disallow: /*?*
     Disallow: /?*
     Disallow: /api/*
     ```

---

## 🛠️ 4. Quick Start & Static Build

### Requirements
* Node.js >= 18
* pnpm (or npm / bun)

### Development
```bash
# Start local development server
pnpm dev
```

### Static Export & Automated SEO Audits
```bash
# Full static HTML build + SEO header audit + 100% Sitemap coverage validation
pnpm check:all
```

Individual commands:
```bash
# 1. Export pure static HTML to dist/
pnpm build

# 2. Automated SEO header, canonical, OpenGraph, JSON-LD audit
pnpm seo:audit

# 3. Verify that 100% of indexable HTML pages are included in XML sitemaps
pnpm sitemap:validate
```

---

## 🤖 5. Agent & Claude SEO Skills Integration

1. **Antigravity Custom Skill:** Located at `.gemini/antigravity/skills/programmatic-seo/SKILL.md`.
2. **Claude Code SEO Skill:**
   ```bash
   # Install AgriciDaniel/claude-seo
   /plugin marketplace add AgriciDaniel/claude-seo
   /plugin install claude-seo@agricidaniel-claude-seo
   # Run audit
   /seo audit https://agentskillshub.top
   ```