seobuild-onpage/SPEC.md

SEO-AGI Technical Specification

Overview

seo-agi is a Claude Code skill that writes and rewrites SEO-optimized pages using live competitive data from DataForSEO and Google Search Console. It bridges the gap between "SEO audit tools" and "content generation" by making the data the input to the writing, not a separate workflow.

Architecture

User prompt ("write a page for airport parking JFK")
  │
  ▼
SKILL.md (orchestrator)
  │
  ├── scripts/research.py        ← DataForSEO SERP + keyword data
  │     └── lib/dataforseo.py    ← API client
  │     └── lib/serp_analyze.py  ← Content extraction + gap analysis
  │     └── lib/paa.py           ← People Also Ask extraction
  │
  ├── scripts/gsc_pull.py        ← Google Search Console data
  │     └── lib/gsc_client.py    ← GSC API client
  │     └── lib/cannibalization.py ← Query overlap detection
  │
  ├── scripts/setup.py           ← First-run config + dependency install
  │
  └── references/
        ├── page-templates.md    ← Structural templates by page type
        ├── schema-patterns.md   ← JSON-LD patterns by content type
        └── quality-checklist.md ← Scoring rubric for output validation

Data Flow

Write Flow

1. RESEARCH
   Input:  keyword string, optional location/language
   Action: DataForSEO SERP API → top 10 results
           DataForSEO Keywords API → related keywords + volumes
           DataForSEO PAA → People Also Ask questions
           (optional) GSC → existing pages for cannibalization check
   Output: research.json saved to ~/.local/share/seo-agi/research/

2. ANALYZE
   Input:  research.json
   Action: Extract competitor content structure (headings, word count, topics)
           Identify content gaps (topics competitors cover that you'd miss)
           Score keyword difficulty vs. content depth required
           Detect search intent (informational, commercial, transactional, navigational)
   Output: analysis object passed to Claude context

3. BRIEF
   Input:  analysis object
   Action: Claude generates content brief using analysis + page template
   Output: brief.md saved to ~/Documents/SEO-AGI/briefs/

4. WRITE
   Input:  brief + analysis + research data
   Action: Claude writes full page following brief constraints
           Validates against quality checklist
           Generates schema markup
   Output: page.md saved to ~/Documents/SEO-AGI/pages/

Rewrite Flow

1. INGEST
   Input:  URL or file path
   Action: Fetch/read existing content
           Extract: title, meta, headings, word count, structure
           Identify target keyword (from title/H1 or user input)
   Output: existing_page object

2. RESEARCH (same as Write flow, using detected keyword)

3. GAP ANALYSIS
   Input:  existing_page + research data
   Action: Compare existing page against top 3 SERP competitors
           Identify: missing sections, thin areas, outdated claims
           (optional) GSC: actual query performance, CTR, position trends
   Output: gap_report object

4. REWRITE
   Input:  existing_page + gap_report + research data
   Action: Claude rewrites following gap report
           Produces change summary (what changed and why)
           Updates schema markup
   Output: rewritten_page.md + changes.md saved to ~/Documents/SEO-AGI/rewrites/

DataForSEO API Endpoints Used

Endpoint	Purpose	Used In
/v3/serp/google/organic/live/advanced	Live SERP results	research.py
/v3/serp/google/organic/task_post	Async SERP (batch)	research.py (future)
/v3/dataforseo_labs/google/related_keywords/live	Related keywords	research.py
/v3/dataforseo_labs/google/keyword_suggestions/live	Keyword ideas	research.py
/v3/serp/google/organic/live/advanced (with PAA)	People Also Ask	research.py
/v3/on_page/content_parsing/live	Competitor content	serp_analyze.py

Google Search Console API Usage

Method	Purpose	Used In
searchanalytics.query()	Query performance data	gsc_pull.py
sitemaps.list()	Indexed pages	gsc_pull.py (future)

Configuration

All config stored in ~/.config/seo-agi/:

~/.config/seo-agi/
├── .env              # API credentials
├── config.json       # User preferences (default location, language, site URL)
└── sites.json        # GSC verified sites cache

config.json schema

{
  "default_location": 2840,
  "default_language": "en",
  "default_site": "https://example.com",
  "serp_depth": 10,
  "save_research": true,
  "output_dir": "~/Documents/SEO-AGI"
}

Output Schema

research.json

{
  "keyword": "airport parking JFK",
  "timestamp": "2026-03-17T14:30:00Z",
  "location": 2840,
  "serp": [
    {
      "position": 1,
      "url": "https://...",
      "title": "...",
      "description": "...",
      "word_count": 2400,
      "headings": ["H1: ...", "H2: ...", "H2: ..."],
      "topics_covered": ["pricing", "shuttle service", "terminal maps"]
    }
  ],
  "related_keywords": [
    {"keyword": "JFK long term parking", "volume": 4400, "difficulty": 45},
    {"keyword": "cheap parking near JFK", "volume": 2900, "difficulty": 38}
  ],
  "paa_questions": [
    "How much does parking cost at JFK?",
    "Is there free parking at JFK airport?",
    "What is the cheapest way to park at JFK?"
  ],
  "intent": "commercial",
  "avg_word_count": 1850,
  "content_gaps": ["shuttle frequency", "EV charging", "real-time availability"]
}

page.md frontmatter

---
title: "Airport Parking at JFK: Pricing, Lots & Shuttle Guide [2026]"
meta_description: "Compare JFK airport parking options from $8/day. Official lots, off-site alternatives, shuttle times, and terminal-specific tips."
target_keyword: "airport parking JFK"
secondary_keywords: ["JFK long term parking", "cheap parking near JFK"]
word_count: 2200
page_type: "service-location"
schema_type: "FAQPage, LocalBusiness"
created: "2026-03-17"
research_file: "~/.local/share/seo-agi/research/airport-parking-jfk-20260317.json"
---

Testing

# Run with mock fixtures (no API calls)
python3 scripts/research.py "test keyword" --mock

# Run tests
python3 -m pytest tests/

Fixtures in fixtures/ provide sample API responses for offline development.