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

> Learn to perform a technical SEO audit with GEO-SEO Claude. This guide explains how the agent-driven framework automates page fetching, schema validation, citability scoring, and PDF report generation.

- Repository: [Zubair Trabzada/geo-seo-claude](https://github.com/zubair-trabzada/geo-seo-claude)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/skills/geo-technical/SKILL.md), such as the **fetch page** skill that wraps [`scripts/fetch_page.py`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/website-searchaction.json) and [`organization.json`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/scripts/citability_scorer.py), implementing the proprietary algorithm detailed in [`docs/scoring-methodology.md`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/templates/geo-report-template.html) using Jinja-style templating. The skill applies styles from [`templates/geo-report-style.css`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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:

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

```

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

```python
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:

```python
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:

```python
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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/organization.json) and [`website-searchaction.json`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/website-searchaction.json) to flag structured data errors.
- **Citability scoring** in [`scripts/citability_scorer.py`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/templates/geo-report-template.html) and [`templates/geo-report-style.css`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/scripts/citability_scorer.py) uses the `compute_citability()` function to aggregate signals specified in [`docs/scoring-methodology.md`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/geo/SKILL.md), you can modify [`scripts/fetch_page.py`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/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`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/skills/geo-report-pdf/SKILL.md). This skill renders Jinja-style HTML templates (stored in [`templates/geo-report-template.html`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/templates/geo-report-template.html)) and applies CSS from [`templates/geo-report-style.css`](https://github.com/zubair-trabzada/geo-seo-claude/blob/main/templates/geo-report-style.css) before conversion. You can modify these templates to output different visual layouts while maintaining the PDF delivery format.