Claude SEO Configuration — Rendering, Credentials, Skills

Claude SEO ships with sensible defaults that work without any configuration. You can override rendering behaviour, add Google API credentials for richer data, adjust multi-location safeguards, and tune per-skill thresholds by editing the local SKILL.md files the installer places in your Claude Code directory. This page documents every configurable surface.

File Locations

Manual Install

After running bash install.sh or the PowerShell equivalent, files land in your Claude Code user directory:

~/.claude/
├── skills/
│   ├── seo/
│   │   ├── SKILL.md              # Main orchestrator — edit to change routing or thresholds
│   │   ├── references/           # 12 on-demand knowledge files
│   │   └── .venv/                # Python virtual environment (created by installer)
│   │       └── bin/pip           # Use this pip to install/update dependencies
│   ├── seo-audit/SKILL.md
│   ├── seo-content/SKILL.md
│   ├── seo-local/SKILL.md        # Edit for multi-location page limits
│   ├── seo-schema/SKILL.md
│   └── ...                       # All 24 sub-skill SKILL.md files
│
└── agents/
    ├── seo-technical.md
    ├── seo-content.md
    └── ...                       # All 18 agent files

Plugin Install (Claude Code 1.0.33+)

When you install via /plugin install, files land in the plugin-managed directory:

~/.claude/plugins/
└── claude-seo@agricidaniel-claude-seo/
    ├── skills/
    ├── agents/
    ├── scripts/
    └── requirements.txt

The ~/.claude/skills/seo/.venv/ path is the same regardless of install method — the installer always creates the virtual environment there.

Google API Credentials

~/.config/claude-seo/
├── google-api.json               # API key + tier detection config (0o600)
├── client_secret.json            # OAuth 2.0 client secret (0o600)
├── oauth-token.json              # OAuth token — auto-chmod'd to 0o600 on every load
├── service_account.json          # Service account key (0o600) — alternative to OAuth
└── backlinks-api.json            # Moz and Bing Webmaster API credentials (0o600)

All credential files under ~/.config/claude-seo/ are created with 0o600 permissions (owner read/write only). Legacy files with 0o644 permissions from pre-v2 installs are automatically remediated to 0o600 the first time any script loads them. Nothing under ~/.config/claude-seo/ is ever checked into the repository.

Python Virtual Environment

The installer creates a virtual environment at ~/.claude/skills/seo/.venv/. All Python scripts use this venv’s interpreter at runtime. The requirements.txt is copied to ~/.claude/skills/seo/requirements.txt so you can reinstall dependencies without cloning the repo again.

# Reinstall all dependencies into the venv
~/.claude/skills/seo/.venv/bin/pip install -r ~/.claude/skills/seo/requirements.txt

# Check which packages are installed
~/.claude/skills/seo/.venv/bin/pip list

# Upgrade a single package
~/.claude/skills/seo/.venv/bin/pip install --upgrade trafilatura

Python Dependencies

The following packages are installed by requirements.txt (current versions as of v2.0.0):

# Core scraping and parsing
beautifulsoup4>=4.12.0,<5.0.0
requests>=2.32.4,<3.0.0
lxml>=6.1.1,<7.0.0
urllib3>=2.7.0,<3.0.0
validators>=0.22.0,<1.0.0
Pillow>=12.2.0,<13.0.0

# SPA rendering (Phase A, v2.0.0)
playwright>=1.59.0,<2.0.0
trafilatura>=2.0.0,<3.0.0
htmldate>=1.9.0,<2.0.0
courlan>=1.3.0,<2.0.0

# Report generation
matplotlib>=3.8.0,<4.0.0
weasyprint>=68.1,<70.0
openpyxl>=3.1.5,<4.0.0

# Google API integrations
google-api-python-client>=2.196.0,<3.0.0
google-auth>=2.20.0,<3.0.0
google-auth-oauthlib>=1.4.0,<2.0.0
google-auth-httplib2>=0.4.0,<1.0.0
google-analytics-data>=0.18.0,<1.0.0

Python version requirement: 3.10 or higher. The pyproject.toml enforces requires-python = ">=3.10".

Rendering Modes

scripts/render_page.py is the shared headless renderer used by every fetching subagent. It wraps Playwright Chromium with SPA-detection logic, trafilatura for boilerplate-free content extraction, and htmldate for publication-date extraction.

Flag	Behaviour
`--render auto`	Default. Detects SPA hallmarks (empty `<div id="root">` shell, single bundle script, hydration markers) and switches to Playwright rendering only when needed. Static sites get raw HTML for speed.
`--render always`	Force Playwright rendering on every page regardless of SPA detection. Use for sites with aggressive client-side routing.
`--render never`	Raw HTML only. Disables Playwright entirely. Useful when Playwright is not installed or for fast CI-only analysis.

The --render flag is passed at the CLI layer. The underlying fetch_page() Python function stays raw-mode by default for backward compatibility with v1.x scripts.

Google API Credentials

Claude SEO uses a 4-tier credential system. Start at Tier 0 with no accounts and add tiers as you need richer data.

Tier	Credentials required	APIs unlocked
0	Google API key only	PageSpeed Insights, CrUX, CrUX History (25-week trends)
1	+ OAuth 2.0 or Service Account	+ Search Console (queries, URL Inspection, sitemap status), Indexing API
2	+ GA4 property config	+ GA4 organic traffic, top landing pages, device/country breakdown
3	+ Ads developer token	+ Keyword Planner search volume and competition data

Run the credential wizard to configure any tier:

/seo google setup

The wizard walks through each tier, validates connectivity, and writes the credential files to ~/.config/claude-seo/ with the correct 0o600 permissions. To check which tiers are currently active without running a full audit:

python3 ~/.claude/skills/seo/scripts/google_auth.py --check

Multi-Location Safeguards

The seo-local skill enforces two hard limits to prevent doorway-page violations when auditing or generating location pages for multi-location businesses.

Threshold	Behaviour	Where to configure
30 pages	Warning emitted; 60% minimum unique content enforced per page	`skills/seo-local/SKILL.md` quality-gates section
50 pages	Hard stop; user must explicitly justify before proceeding	`skills/seo-local/SKILL.md` quality-gates section

To adjust these limits for a client whose site legitimately has more than 50 location pages, edit the local ~/.claude/skills/seo-local/SKILL.md file and update the threshold values in the quality-gates section. Do not change them globally — document the justification in a comment alongside the new values.

DataForSEO Cost Guardrails

The DataForSEO extension ships with configurable per-request budget controls managed by scripts/dataforseo_costs.py. The cost guardrail prevents runaway API spending when running large-scale audits. Default behaviour:

Budget tracking is cumulative per session.
A warning is emitted when estimated spend for the current command exceeds the configured per-request limit.
The command aborts if estimated spend exceeds the hard-stop budget.

To adjust the budget limits, edit the extensions/dataforseo/field-config.json file:

{
  "cost_guardrail": {
    "warn_at_usd": 0.50,
    "stop_at_usd": 2.00
  }
}

Customising a Skill

Every sub-skill is a plain Markdown file you own. Because skills live in your ~/.claude/ directory, edits are local, version-controlled by you, and never overwritten by a plugin update unless you explicitly re-run the installer. Common customisations: Adjusting content length thresholds — edit references/quality-gates.md in the orchestrator’s reference directory to change minimum word counts per page type. Changing industry detection signals — edit the Industry Detection section of skills/seo/SKILL.md to add or remove signal patterns for your client’s vertical. Tuning schema validation severity — edit skills/seo-schema/SKILL.md to reclassify certain finding types from Critical to High if your site intentionally uses a non-standard schema pattern. Adding industry-specific templates — add a Markdown file to skills/seo-plan/templates/ with the naming pattern {industry}.md. The seo-plan skill auto-discovers templates in that directory.

Keep SKILL.md files under 500 lines / 5,000 tokens. Reference files should stay under 200 lines. Scripts must include a docstring, a CLI interface, and JSON output for the orchestrator to parse. These limits keep context windows lean during parallel dispatch.

Environment Requirements

Requirement	Version	Notes
Python	3.10+	Enforced by `pyproject.toml`
Claude Code CLI	Any	Required to load skills and agents
Playwright Chromium	Optional	Required for `--render auto` / `--render always`; auto-installed by `install.sh`
Google API credentials	Optional	Required for Tier 0–3 data enrichment
MCP extensions	Optional	Required for DataForSEO, Ahrefs, Profound, SE Ranking, Bing Webmaster, Unlighthouse

Install Playwright’s Chromium browser separately if the auto-install did not run or if you are on a headless server:

playwright install chromium

Or using the module syntax if the playwright binary is not on your PATH:

python3 -m playwright install chromium

Get Started

Core Commands

Specialized Commands

Extensions

Reference

Claude SEO Configuration — Rendering, Credentials, Skills

File Locations

Manual Install

Plugin Install (Claude Code 1.0.33+)

Google API Credentials

Python Virtual Environment

Python Dependencies

Rendering Modes

Google API Credentials

Multi-Location Safeguards

DataForSEO Cost Guardrails

Customising a Skill

Environment Requirements

Build docs developers (and LLMs) love

Get Started

Core Commands

Specialized Commands

Extensions

Reference

Documentation Index

​File Locations

​Manual Install

​Plugin Install (Claude Code 1.0.33+)

​Google API Credentials

​Python Virtual Environment

​Python Dependencies

​Rendering Modes

​Google API Credentials

​Multi-Location Safeguards

​DataForSEO Cost Guardrails

​Customising a Skill

​Environment Requirements

Build docs developers (and LLMs) love

File Locations

Manual Install

Plugin Install (Claude Code 1.0.33+)

Google API Credentials

Python Virtual Environment

Python Dependencies

Rendering Modes

Google API Credentials

Multi-Location Safeguards

DataForSEO Cost Guardrails

Customising a Skill

Environment Requirements