Most SEO tools tell you what's wrong with your site. This one writes the pages.
`/seoagi "airport parking JFK"` pulls the current SERP, analyzes what's ranking, finds the gaps in their content, and writes you a complete page -- with the heading structure, depth, FAQ section, and schema markup that actually competes. Not thin content. Not keyword-stuffed filler. Pages backed by live data from the tools the pros use.
**New in v1.9.1 -- Decision Fit Mapping + Brand Voice + Missing Spoke Detection:**
- **Brand differentiator injection** via `--differentiators` on `research.py` (e.g. `--differentiators="women-owned, 24/7 service, no hidden fees"`). Passes through to the brief output so the writing agent has strict brand constraints. Differentiators must be woven verbatim into the 500-token chunks and surfaced in the AI Summary Nugget -- paraphrased fluff fails the new Brand Identity check.
- **Missing Spoke Detection** -- the research pipeline now extracts internal-link anchor text from the top 3 competitors, filters out navigational generics (Home, Contact Us, Privacy, FAQ, etc.) and image-link leakage, and outputs a ranked `missing_spokes` list. SKILL.md Section 12 now requires every generated page to append a `## Recommended Spoke Pages` section built from this data.
- **Decision Fit Mapping** -- new checklist enforcement: heading structure must map to the user's psychological buying stage (Research / Compare / Buy) instead of copy-pasting competitor H2s.
- **Execution Protocol now prompts for differentiators** if the user didn't supply them up front -- the agent stops and asks before writing rather than producing generic AI homogenization.
**New in v1.9.0 -- Massive Web Render as primary content parser:**
- **Massive Web Render** (render.joinmassive.com) is now the primary competitor content parser when `MASSIVE_API_TOKEN` is configured. Returns clean rendered markdown including JS-loaded content that DataForSEO's `content_parsing/live` endpoint misses.
- **Graceful per-URL fallback to DataForSEO** -- if Massive errors or returns empty for any single URL, that URL falls back to DataForSEO. A partial Massive outage cannot break a research run.
- **SERP organic results and keyword data continue to come from DataForSEO** -- Massive's `/search` endpoint only returns "also-searched" query suggestions, not organic results, so the SERP path is unchanged.
- **`content_parsers` field added** to research output so you can see exactly which parser handled each URL (e.g. `{"massive": 4, "dataforseo-fallback": 1}`).
- Setup: add `MASSIVE_API_TOKEN=...` to `~/.config/seo-agi/.env`. No token = skill runs in pure DataForSEO mode exactly as before.
- **DOM Vectoring & Shard Extraction Compliance** (Section 6) -- Google's AI Overviews are built by Gemini 3.5 Flash running a RAG pipeline that extracts structural "shards" from the raw HTML DOM. JSON-LD in `<head>` is no longer sufficient by itself: critical data points must live in front-facing `<table>` markup or inline RDFa spans where a clean-session crawler can see them without JavaScript execution.
- **Trust Pilot as Tier 1 Tributary** -- added to the Tributary Trust Protocol as a first-class Tier 1 asset. Trustpilot is now a highly weighted trust/relevance signal for LLMs and demonstrably shifts brand description vectoring in Gemini and ChatGPT within 48 hours of publication.
- **Off-Page Schema Injection** -- new Tier 1 tactic. Embedding `Organization` and `Person` JSON-LD schema in third-party properties (Cloud Pages, press releases) with explicit links back to the brand's Google Business Profile CID blocks Google's NavBoost from rank-shuffling the money page during A/B exposure tests.
- **Tributary network spread updated** from 4/5 Tier 1 assets to 5/7 to account for the two new asset types.
- **48-point quality checklist** -- adds Trust Pilot profiling, off-page schema mapping, and DOM-visible data point checks. Passing threshold raised to 39/48.
**New in v1.7.1 -- LLM Retrieval & Substantive Content Protocols:**
- **Meta-Specific Entity Isolation** -- competitor SERP descriptions are mined for the bolded query-matched terms (the snippet entities Google itself surfaces), not generic body entities. These become the primary entity set the brief must cover, because they are the exact tokens already validated as relevant by Google's snippet generator.
- **Bigram / Trigram AI Alignment** -- top 3 ranking competitors' body text is tokenized to extract the top 5 bigrams and top 5 trigrams. The AI Summary Nugget (top of page, position zero for LLM retrieval) must include 2 or more of these n-grams verbatim. AI retrieval scoring rewards token-window overlap with consensus phrasing -- this is how you align with what the LLM has already learned the topic "looks like."
- **Primary + Secondary Intent Mapping (Orcas 1)** -- single-intent pages underperform. Every page now maps Primary intent (the question the user typed) into the first 500 tokens AND Secondary intent (the action funnel: compare, book, contact, calculate) into the next two chunks. Pages without a secondary action path fail the dual-intent check.
- **The 410 Prune Protocol** -- on rewrites, every legacy URL gets an explicit status-code recommendation. 301 preserves equity when the topic survives. 410 prunes thin, cannibalizing, or out-of-topical-circle pages so they stop dragging the domain. Silent leave-as-is is no longer an acceptable output for a legacy URL audit.
- **Local Codebase Contextual Linking** -- when the skill is run inside a project repo, it scans the local file structure (`.tsx`, `.md`, `.html`, etc.), detects the framework, injects semantic HTML directly into source files where appropriate, and emits `.htaccess` / Nginx / `next.config.js` redirect snippets for the 410 recommendations. The skill writes ranking pages, not just content briefs.
**New in v1.6.0 -- ICP-Driven Content + Local Trust Signals:**
- **Ideal Customer Persona (ICP) Integration** -- page briefs now require a defined ICP with demographics, psychographics, and specific pain points. Content maps to who it's actually for, not a generic audience.
- **Deep Entity History & Identity Tags** -- founding dates, generational ownership, and identity attributes (women-owned, veteran-owned, family-owned) are now explicit entity signals. Maps directly to GBP tags and conversational AI filtering.
- **The Self-Placement Rule** -- ranking the client #1 in a listicle is now an approved tactic, provided the entry is strictly objective with a defined use-case and honest tradeoffs.
- **Keyword Cannibalization Governance** -- strict rule against creating pages that compete with existing URLs for the same intent. Sales-focused duplicates of informational pages get tagged with `noindex` recommendation.
**New in v1.5.0 -- Forensic SEO + Structural Signals:**
- **Semantic HTML Containers** -- generated HTML now uses `<article>`, `<section>`, `<aside>`, `<main>` instead of generic `<div>`. Google's crawler uses these elements to identify the Main Content zone for passage extraction and AI retrieval.
- **Proof-Term Proximity** -- supporting evidence (numbers, entity names, operational details) must live in the same 500-token chunk as the H2 it supports. BERT evaluates within the passage window, not page-wide. Orphaned proof terms don't help.
- **QDD Vulnerability Check** -- UGC (Instagram, Pinterest, Reddit) ranking for a commercial keyword is a structural gap, not a signal to avoid. Flag as HIGH_CONFIDENCE_TAKEOVER.
- **Site Over Page Rule** -- generalist competitors ranking with one page are vulnerable to specialist site architecture. Niche Site Pivot trigger fires when 2/3 top results are generalist pages.
- **Query Fan-Out (QFO) Facet Coverage** -- each 500-token chunk now targets a specific AI sub-query. 40% of future traffic arrives via AI fan-out from a single user prompt.
- **Forensic EMQ Check** -- EMQ in H1 is conditionally required when 2/3 top competitors use it. Competitive context overrides the default entity-based heading rule.
- **Orcas One CVR Modeling** -- keywords now ranked by estimated conversion value, not raw volume. Position 1 at 4.5% CVR vs position 7 at 2%.
- **NavBoost Geographic Click Relevance** -- pages now reranked by geographic click patterns. Local pages require neighborhood-level specificity, not just city names. Observed across SEO X community testing.
- **Click Satisfaction as Primary Signal** -- Google watches if users are satisfied after clicking. Content must deliver value in the first 3 chunks or rankings drop regardless of quality. Confirmed via practitioner NavBoost analysis.
- **AI Overview Link Optimization** -- earning a link inside AI Overviews drives 70-80% CTR. Pages structured for snippet extraction with clean tables and FAQ markup.
- **AI Overview Theft Defense** -- rising impressions + falling clicks = your content cited without credit. Interactive elements (calculators, widgets) defend against extraction.
- **QDD (Query Deserves Diversity)** -- Google pulls diverse results into overviews. Information Gain Test now critical for QDD survival.
- **FHASS Replaces YMYL** -- Financial, Health, And Safety, and Security. Expanded scrutiny for risk-adjacent content. Discussed in Google Cloud documentation updates.
- **Banned 2026 Content Patterns** -- generic AI FAQs, 300-word thin pages, blog rolls outside topical circle all confirmed penalized.
- **34-point quality checklist** with geographic specificity, click satisfaction, FHASS compliance, and minimum 1,500-word depth checks.
- **AI Summary Nuggets** -- every page opens with a 200-character fact-dense block designed for Perplexity/Gemini/ChatGPT to cite as a consensus source. Position zero for LLM retrieval.
- **Original Research Block** -- mandatory data experiment or first-hand observation section. Google's highest-priority E-E-A-T signal: Experience. Pages without original research cap at 20/28.
- **Map Traffic Shifting** -- internal links from high-traffic informational pages to map embeds, shifting engagement signals toward local intent.
- **Spam Resilience** -- quality scoring now prioritizes technical relevance density over "human tone." Factually perfect content is not downgraded for sounding clinical.
- **Recursive Fact-Checking** -- every claim validated against 2+ high-ranking sources for Entity Consensus before delivery.
- **28-point quality checklist** with mandatory printed scorecard at the end of every output.
**New in v1.2.0 -- Anti-Spam Ranking Signals:**
- Single H1 rule, no exact-match keyword in meta descriptions or subheadings
- No keyword-stuffed alt text, no duplicate content
**I built this because I got tired of the gap between "SEO audit" and "published page."** I've been doing SEO for 20+ years in ground transportation (1M+ bookings, 2M+ rides across my companies). The workflow was always the same: pull SERP data, analyze competitors, find gaps, write brief, write page, add schema, publish. Over and over. So I turned that entire workflow into a single skill that any AI agent can execute.
The result? I used this to research a competitor's best-performing pages, built equivalent content with `/seoagi`, bought the exact-match domains, and every single page is ranking on page 1. That's not theory. That's the workflow.
For rewrites, point it at any URL. It compares your page against the current top 3 ranking competitors, identifies exactly what you're missing, and rewrites with a change summary explaining every edit.
---
## The SEO Knowledge Inside
This isn't a wrapper around "write me an SEO article." The skill encodes strategies from the best in the game:
**Traditional SEO**
- Intent-first content architecture (match what searchers actually want, not what you think the keyword means)
- Competitive word count targeting (page length based on what's ranking, not arbitrary "write 2000 words")
- Heading hierarchy derived from SERP analysis (not templates, not guesswork)
- People Also Ask coverage as FAQ sections (answer the questions Google already knows people are asking)
- Schema markup patterns by page type (FAQPage, LocalBusiness, HowTo, Product, BreadcrumbList)
- Internal linking suggestions based on actual site data from GSC
**GEO / LLM SEO (Generative Engine Optimization)**
**No API keys?** The skill still works. It falls back to Ahrefs/SEMRush MCP tools (if connected) or web search. You lose SERP content parsing but the framework still writes quality pages.
### Step 4: Verify it works
```bash
# Test the research pipeline (uses mock data, no API keys needed)
**Exact-match domain play**: Research competitor's top pages with OpenClaw, generate equivalent content with `/seoagi`, buy the domains, publish. Page 1.
**Location page generation**: `/seoagi "plumber in [city]"` x 50 cities. Each page gets city-specific research, local PAA questions, LocalBusiness schema. Not cookie-cutter templates.
**Content refresh**: Point it at your underperforming URLs. It pulls your actual GSC data, compares against current top 3, and tells you exactly what to add, expand, or restructure. Then does it.
**Competitive intelligence**: `/seoagi research "competitor keyword"` gives you the full landscape without writing anything. Word count ranges, heading structures, topic gaps, related keywords with volumes.
**Brief handoff**: `/seoagi brief "keyword"` generates a structured content brief you can hand to a human writer. Research-backed, not vibes-based.
---
## The Workflow That Got Me Here
I've been running this workflow manually for 20 years across ParkingAccess.com (1M+ bookings) and Shuttlefare.com (2M+ rides). The pattern never changed:
1. Find what's ranking
2. Figure out what they cover that you don't
3. Write something deeper
4. Add the technical SEO (schema, meta, structure)
seobuild-onpage is that pattern, automated. The 20 years of pattern recognition compressed into a SKILL.md file, backed by live data APIs, running inside a super agent that can decompose and parallelize the work.
The skill is modular. Want to add a new page template? Edit `references/page-templates.md`. New schema pattern? `references/schema-patterns.md`. Better quality checks? `references/quality-checklist.md`. New data source? Add a client in `scripts/lib/` and wire it into `research.py`.
---
## Credits
Built by [Greg Bessoni](https://github.com/gbessoni) ([@gregbessoni](https://x.com/gregbessoni)).
