97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 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
|
|
```
|