How to Perform a Technical SEO Audit Using GEO-SEO Claude: A Complete Guide

GEO-SEO Claude automates technical SEO audits through a modular agent-driven framework that fetches pages, validates schemas, scores citability, and generates PDF reports.

The zubair-trabzada/geo-seo-claude repository provides an open-source toolkit for orchestrating comprehensive technical SEO audits. By combining specialized agents with reusable skills, the framework eliminates manual checks for structured data validation, internal linking analysis, and content freshness scoring. This guide walks through the exact workflow implemented in the source code, from initial domain ingestion to final report generation.

Understanding the GEO-SEO Claude Architecture

The framework separates concerns into two primary abstractions: agents that define high-level audit workflows and skills that execute concrete operations like HTTP requests or HTML parsing.

Agents and Skills

According to the source code in agents/geo-technical.md, the geo-technical agent serves as the entry point for all technical audits. This agent orchestrates the sequence of operations without implementing low-level logic directly. Instead, it delegates tasks to specialized skills documented in skills/geo-technical/SKILL.md, such as the fetch page skill that wraps scripts/fetch_page.py.

Skills are composable units stored in the skills/ directory. For example, the geo-report-pdf skill defined in skills/geo-report-pdf/SKILL.md handles the final rendering phase, converting JSON audit data into styled HTML and then PDF.

The Skill Registry

All components wire together through the skill-registry mechanism documented in geo/SKILL.md. The registry allows any agent to invoke a skill by name, passing a standardized JSON payload containing parameters like target URLs or authentication tokens. This architecture ensures you can swap implementations—such as replacing the default fetcher with a headless Chrome scraper—without modifying the orchestration logic.

Step-by-Step Technical SEO Audit Workflow

When you initiate a technical SEO audit, the framework executes a four-phase pipeline: page retrieval, schema validation, citability scoring, and report generation.

Initiating the Audit with the geo-technical Agent

The audit begins when the geo-technical agent receives a target domain. As implemented in agents/geo-technical.md, this agent triggers the workflow by sequentially invoking registered skills through the core registry. The agent itself contains no scraping logic; it purely manages state and data flow between skills.

Fetching and Rendering Pages

The fetch page skill activates scripts/fetch_page.py, which retrieves raw HTML using requests with optional headless rendering. The script handles timeouts, retries, and JavaScript execution when the render parameter is set to True. According to skills/geo-technical/SKILL.md, this skill returns a structured JSON object containing the HTML content, HTTP status, and response headers.

Validating JSON-LD Schema Markup

Once pages are retrieved, the framework validates structured data against JSON schemas stored in the schema/ directory. The validator compares extracted markup against definitions like website-searchaction.json and organization.json. When required properties are missing or incorrectly typed, the validation skill flags specific errors in the audit payload before passing results downstream.

Computing Citability Scores

The citability scorer skill executes scripts/citability_scorer.py, implementing the proprietary algorithm detailed in docs/scoring-methodology.md. The compute_citability() function aggregates SEO signals including backlink counts, internal linking depth, and content freshness timestamps to produce a quantitative citability metric. This score helps identify which pages have the highest potential to earn featured snippets or knowledge panel placements.

Generating the Final PDF Report

Audit results flow into the geo-report-pdf skill, which renders templates/geo-report-template.html using Jinja-style templating. The skill applies styles from templates/geo-report-style.css before converting the document to PDF. The modular template system allows complete customization of report branding while preserving the structured data injected by upstream skills.

Running Your First Audit

You can execute a complete technical SEO audit via command line or programmatically through the Python API.

Execute an audit from the terminal using the webapp module:

python -m scripts.webapp.app audit --domain example.com --output report.pdf

Invoke the fetch-page skill programmatically to retrieve raw HTML:

from geo.skills import invoke_skill

result = invoke_skill(
    "fetch_page",
    {"url": "https://example.com", "render": False}
)

html = result["html"]

Calculate citability scores directly using the scorer module:

from scripts.citability_scorer import compute_citability

score = compute_citability(
    url="https://example.com",
    backlinks=120,
    internal_links=45,
    last_modified="2024-06-10"
)

print(f"Citability score: {score}")

Generate a PDF report by invoking the reporting skill with audit data:

from geo.skills import invoke_skill

audit_data = {...}   # JSON payload produced by earlier steps

pdf_bytes = invoke_skill(
    "geo_report_pdf",
    {"audit": audit_data, "template": "geo-report-template.html"}
)

with open("audit-report.pdf", "wb") as f:
    f.write(pdf_bytes)

Customizing the Audit Pipeline

Because each phase is isolated through the skill registry, you can extend or replace components without destabilizing the workflow. For instance, modify scripts/fetch_page.py to add proxy rotation or custom headers, and the geo-technical agent will automatically use the updated implementation. Similarly, override templates/geo-report-template.html to include client-specific branding or additional diagnostic sections while retaining the core audit logic.

Summary

• GEO-SEO Claude uses a modular architecture separating agents (workflows) from skills (operations) via the registry system in geo/SKILL.md.
• The geo-technical agent orchestrates audits by invoking the fetch-page, schema-validation, citability-scorer, and geo-report-pdf skills in sequence.
• Page retrieval occurs through scripts/fetch_page.py, which supports both static requests and headless rendering for JavaScript-heavy sites.
• Schema validation compares extracted JSON-LD against schemas like organization.json and website-searchaction.json to flag structured data errors.
• Citability scoring in scripts/citability_scorer.py aggregates backlink counts, internal linking depth, and content freshness into a single metric.
• Report generation templates in templates/geo-report-template.html and templates/geo-report-style.css produce styled PDF outputs via the geo-report-pdf skill.

Frequently Asked Questions

What is the geo-technical agent in GEO-SEO Claude?

The geo-technical agent is the orchestration component defined in agents/geo-technical.md that manages the technical SEO audit workflow. It receives the target domain and triggers the sequence of skill executions—fetching pages, validating schemas, scoring content, and generating reports—without containing any scraping or parsing logic itself.

How does the citability scorer calculate SEO scores?

The citability scorer implemented in scripts/citability_scorer.py uses the compute_citability() function to aggregate signals specified in docs/scoring-methodology.md. It evaluates backlink quantity, internal linking architecture depth, and content recency to produce a numerical score indicating a page's likelihood of being cited in search features.

Can I replace the default page fetcher with a headless browser?

Yes. Because the framework uses the skill registry pattern documented in geo/SKILL.md, you can modify scripts/fetch_page.py to use Playwright or Selenium instead of the requests library. The geo-technical agent will continue functioning normally as long as the skill accepts the same JSON payload parameters (URL, render boolean) and returns the expected HTML output structure.

What file formats does GEO-SEO Claude support for audit reports?

The framework primarily generates PDF reports through the geo-report-pdf skill defined in skills/geo-report-pdf/SKILL.md. This skill renders Jinja-style HTML templates (stored in templates/geo-report-template.html) and applies CSS from templates/geo-report-style.css before conversion. You can modify these templates to output different visual layouts while maintaining the PDF delivery format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}