claude-seo Documentation

File: README.md Copy Chapter

Claude SEO: SEO Skill for Claude Code

Claude SEO is an open-source SEO analysis plugin for Claude Code. It runs 25 sub-skills and 18 specialist agents in parallel across technical SEO, content quality (E-E-A-T), Schema.org markup, AI search optimization (GEO), local SEO, e-commerce, and international SEO. Every audit produces a prioritized action plan with testable recommendations grounded in primary-source guidance from Google.

Two versions of this skill.

• 🌐 Public open-source → AgriciDaniel/claude-seo: MIT, public releases, no membership. Use this if you want stable + downloadable.
• 🔒 Community private mirror → AI-Marketing-Hub/claude-seo: early access to upcoming features and direct collaboration with the AI Marketing Hub Pro community. Requires membership.

Why Claude SEO Copy Section

• AI-search first. Aligned with Google's AI Optimization Guide. Question-based citability scoring, primary-source evidence on llms.txt, IPTC TrainedAlgorithmicMedia for AI-generated product images, agent-friendly page checks per web.dev.
• Parallel execution. Full site audits spawn up to 15 specialist agents simultaneously. Site-level audits complete in minutes rather than hours.
• Falsifiable, not promotional. Every recommendation carries the first-principle observation it rests on, its dependency relationships, an explicit "how would we know this failed?" check, and a leading indicator. See Methodology.

Real results Copy Section

Google Search Console for a site started 23 March 2026 and run on this workflow: total clicks and impressions across its first three months, through 12 June 2026.

Using Codex instead of Claude Code? Use Codex SEO, the Codex-first port with TOML agents, plugin packaging, deterministic runners, and the same SEO workflow surface.

Who this is for Copy Chapter

• SEO agencies running 5+ client sites. Replace quarterly deep audits with weekly automated runs. Same team capacity, 4× audit cadence, every recommendation comes with a falsifiability check the client can verify.
• In-house SEO leads at SaaS / publisher / e-commerce companies. Second-pair-of-eyes before executive reviews. Catches what GSC and Lighthouse hide: schema deprecation, AI-citability gaps, expired-domain heritage risk, parasite-SEO exposure, machine-translation drift.
• Freelance SEO consultants. Anchor day-one client scope with a 15-minute audit and a real 0-100 score. Win the engagement with concrete proof of value before you spend an hour writing the proposal.

Run a full audit and watch parallel agents fan out across the site:

Watch the full demo on YouTube

Table of Contents Copy Chapter

• Who this is for
• Installation
• Quick Start
• Commands
• Features
• Compared to manual / agency / commercial tools
• Use cases
• Sample Output
• Architecture
• Methodology
• What's New in v2
• Limitations
• Requirements
• Uninstall
• Extensions
• Ecosystem
• Documentation
• FAQ
• Community Contributors
• License
• Contributing
• Author

Installation Copy Chapter

ℹ️ Which version are you installing?

• Public open-source (default). The commands below install from AgriciDaniel/claude-seo — MIT, public releases, no membership required.
• AI Marketing Hub Pro member? Install the community version with early access instead: swap AgriciDaniel/claude-seo for AI-Marketing-Hub/claude-seo and the plugin slug claude-seo@agricidaniel-claude-seo for claude-seo@ai-marketing-hub-claude-seo. Requires gh auth login (or PAT) with access to the AI-Marketing-Hub org. If /plugin marketplace add 404s, DM in the Skool community to get added.

Plugin Install (Claude Code 1.0.33+) Copy Section

The fastest path. One-time marketplace add, then plugin install:

/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
/seo setup

The explicit setup step creates an isolated Python environment in Claude's
persistent plugin data and installs Playwright Chromium. Check it at any time
with /seo doctor. No global Python packages or PATH shims are created.

Manual Install (Unix / macOS / Linux) Copy Section

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/install.sh

One-liner (curl, review then run)

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
cat install.sh        # review before running
bash install.sh
rm install.sh

Windows (PowerShell) Copy Section

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1

Why git clone instead of irm | iex? Claude Code's own security guardrails flag irm ... | iex as a supply chain risk: downloading and executing remote code without verification. The git clone approach lets you inspect claude-seo\install.ps1 before running it.

Quick Start Copy Chapter

# Start Claude Code
claude

# Full site audit: parallel sub-agents produce a prioritized action plan
/seo audit https://example.com

# Deep single-page analysis: on-page elements, content quality, schema
/seo page https://example.com/about

# Schema markup audit: detect, validate, generate
/seo schema https://example.com

# AI search optimization: passage citability + primary-source-aligned recommendations
/seo geo https://example.com

# Generate a sitemap with industry templates
/seo sitemap generate

Commands Copy Chapter

32 user-invocable /seo commands across the orchestrator, its sub-skills, and 8 MCP extensions. Full reference in docs/COMMANDS.md.

Features Copy Chapter

What Core Web Vitals does Claude SEO check? Copy Section

Claude SEO measures the current three Core Web Vitals: LCP (Largest Contentful Paint, target under 2.5s), INP (Interaction to Next Paint, target under 200ms), and CLS (Cumulative Layout Shift, target under 0.1). INP replaced FID on March 12, 2024; FID was removed from Chrome's field-data tools (CrUX API, PageSpeed Insights) on September 9, 2024 (Lighthouse is a lab tool and never reported FID), and Claude SEO never references FID. Field data comes from the Chrome User Experience Report (CrUX) when available; lab data falls back to Lighthouse via PageSpeed Insights. LCP can be decomposed into subparts (TTFB, load delay, load duration, render delay) via the /seo google CrUX integration to localize bottlenecks. Mobile and desktop are measured separately. CrUX History (25-week trend) is included in the Tier 0 free credential set.

How does Claude SEO assess E-E-A-T? Copy Section

E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) is evaluated against the Search Quality Rater Guidelines, last updated September 2025 with YMYL expanded to include political and social topics. Experience signals: original research, case studies, first-hand photos. Expertise: author credentials and topical depth. Authoritativeness: external citations and brand mentions. Trustworthiness, the most heavily weighted of the four: contact info, secure HTTPS, transparent corrections, date stamps. Before scoring sub-factors, Claude SEO applies Google's own Who / How / Why heuristic from the helpful-content guide. Generative AI content is fine if it meets Search Essentials; it crosses into spam when used to scale low-value pages, which seo-content humanize and seo-content verify are designed to detect.

What Schema.org types does Claude SEO support? Copy Section

JSON-LD is the preferred format (Google's stated preference). Claude SEO detects, validates, and generates the active Schema.org types documented in skills/seo/references/schema-types.md, including organization, article, product, local, event, job, course, software/application, service, Q&A, and video patterns. FAQPage: Google stopped showing FAQ rich results for all sites on May 7, 2026; it has no Google rich-result benefit. Keep it only for non-Google or internal semantics if needed. Deprecated and never recommended: HowTo (rich results removed September 2023), SpecialAnnouncement (July 2025), ClaimReview, VehicleListing, EstimatedSalary, LearningVideo, CourseInfo carousel (all retired June 2025). Replacement guidance: skills/seo-schema/references/deprecated-types-2024-2026.md.

How does Claude SEO optimize for AI search? Copy Section

Aligned with Google's AI Optimization Guide, which states that "AEO" and "GEO" are rebranded labels for SEO. AI Overviews and AI Mode are grounded in the same ranking systems as classic Search; pages must be indexed and eligible for snippet display to appear in any AI feature. Claude SEO scores passage citability (optimal 134-167 word self-contained answer blocks), question-based heading hierarchy, attribution density, structured data coverage, and entity presence across Wikipedia, Reddit, YouTube, and LinkedIn. The seo-geo skill includes evidence-based reframes of three popular myths: llms.txt is not currently a citation lever (primary-source evidence), content chunking is not required, and AI-specific keyword rewriting is unnecessary because synonym understanding is sufficient.

Which Google SEO APIs does Claude SEO integrate with? Copy Section

A 4-tier credential system lets you start with zero keys and add data as needed. Every tier delivers real value at its level:

PDF reports are generated via WeasyPrint (A4 layout) with matplotlib charts at 200 DPI. Run /seo google setup for the credential wizard. All credentials live under ~/.config/claude-seo/ with 0o600 permissions; nothing is checked into the repo.

How does Claude SEO handle local SEO? Copy Section

Three layers. Google Business Profile signals: categories, hours, photos, posts, products, attributes. NAP consistency across citations: name, address, phone matched against major directories with deviation flagging. Review intelligence: rating trends, sentiment, response coverage. For multi-location businesses, Claude SEO enforces a 30-page warning threshold and a 50-page hard stop to prevent doorway-page violations (configurable). The /seo maps workflow adds geo-grid rank tracking, GBP profile auditing, and competitor radius mapping. Local schema generation covers LocalBusiness with all required and recommended properties (geo coordinates, opening hours, areaServed). Phase F (v2) added a GBP deprecation linter that detects retired chat-field references and .business.site URLs.

Compared to manual / agency / commercial tools Copy Chapter

Cost benchmarks: manual audit assumes a senior SEO consultant at typical agency billable rates; agency engagement based on common discovery/audit deliverable scopes; commercial-tool subscriptions reflect published mid-tier pricing across the SEO audit category (Ahrefs, Semrush, Sitebulb, Screaming Frog). Your numbers may differ.

Use cases Copy Chapter

SEO agency lead running 10 client sites. Replaces the quarterly "deep audit" ritual with a weekly Monday-morning /seo audit run per site. Time to deliver a client health-score email drops from 4 hours to 12 minutes; coverage goes from quarterly to weekly without billing more hours. The drift baseline catches regressions between audits so the client conversation moves from "look at this snapshot" to "here is what changed this week."

In-house SEO lead at a 50-person SaaS company. Runs /seo audit 24 hours before each quarterly business review. Catches the items the platform UI buries (broken canonical chains on programmatic pages, schema deprecation after Google's June 2025 retirement wave, AI-citability gaps that erode SERP-to-AI-Overview pickup, expired-domain heritage on acquired blog assets) before the CMO asks why organic traffic is down in front of the board.

Freelance SEO consultant onboarding a new client. Runs /seo audit on the discovery call. Anchors the engagement scope with a real 0-100 score, 3 prioritized critical findings, and a falsifiability check on each recommendation, instead of a vague "I'll take a look and get back to you." Closes more retainers because the proof of value happens during the call, not after the proposal.

Sample Output Copy Chapter

Claude SEO writes real markdown reports as its primary deliverable. Below is the first ~50 lines of a /seo schema https://rankenstein.pro/about audit verbatim. The actual structure, headers, and grading format the plugin produces follows.

SCHEMA-REPORT.md: first 50 lines of a real audit

/* Detailed source-code truncated for AI context efficiency. */

Other audit outputs follow the same shape: FULL-AUDIT-REPORT.md (umbrella audit), GEO-ANALYSIS.md (AI-search readiness), LOCAL-SEO-ANALYSIS.md (GBP and citations), and a production PDF via WeasyPrint + matplotlib (cover, TOC, executive summary, data sections, recommendations, methodology, roughly 32 A4 pages for a full site audit).

Architecture Copy Chapter

The plugin follows the Agent Skills standard with a 3-layer architecture (directive, orchestration, execution). Skills and agents are auto-discovered from skills/seo-*/ and agents/seo-*.md. The orchestrator (skills/seo/SKILL.md) handles industry detection (SaaS, local, ecommerce, publisher, agency), parallel sub-agent dispatch up to 15 simultaneously, and synthesis through the 10-principle framework before emitting the action plan. Full architecture: docs/ARCHITECTURE.md.

Methodology Copy Chapter

Every audit walks 10 principles grouped into four phases. Each emitted recommendation carries four fields: the first-principle observation it rests on, its dependency relationship to other recommendations, a "how would we know this failed?" check, and a leading indicator to monitor.

Full methodology: skills/seo/references/thinking-framework.md.

What's New in v2 Copy Chapter

v2.0.0 is the largest release in the plugin's history. Six build phases, all shipped:

• Phase A: Headless rendering everywhere. Shared scripts/render_page.py with Playwright Chromium plus trafilatura and htmldate. Every audit subagent gets SPA-aware fetching via --render auto (auto-detected on Next.js, React, Vue, Nuxt, Astro islands). Closes the SPA limitation that capped v1.x.
• Phase B: QRG-aligned content quality gates. Filler detector and AI-pattern humanizer keyed to QRG §4.6.5 and §4.6.6, claim-verification scanner, expired-domain heritage check via WHOIS, primary-source Google updates changelog.
• Phase C: Technical and CWV depth. LCP subparts via CrUX (TTFB, load delay, load duration, render delay), Speculation Rules and bfcache detection, IndexNow submitter for Bing / Yandex / Seznam / Naver, Unlighthouse multi-page Lighthouse wrapper.
• Phase D: Schema completeness. Four explicit generators (Reservation, OrderAction, DiscussionForumPosting, ProfilePage), e-commerce schema validator (hasMerchantReturnPolicy, shippingDetails, MemberProgram, EU energyEfficiencyClass, ProductGroup variants), dual validator (Rich Results Test plus Schema Markup Validator).
• Phase E: AI search reframing and 5 new MCP extensions. Ahrefs, SE Ranking (AI Share-of-Voice), Profound (LLM citation tracker), Bing Webmaster plus IndexNow, Unlighthouse. Plus the parasite-SEO risk scanner per Google's November 2024 site reputation abuse policy.
• Phase F: Local, international, and privacy polish. Google Business Profile deprecation linter (chat field and .business.site URLs, with Q&A treated as category/region-limited), DMA consent-mode-v2 click-through diagnostic, machine-translation QA flag per January 2025 QRG.

Test coverage grew from 39 (v1.9.9) to 410 across the v2 line; the url_safety suite alone runs 91 SSRF and DNS-rebinding bypass cases, closing the obfuscated-IPv4, FQDN-trailing-dot, and redirect-rebinding bypass classes. Full migration notes and breaking changes: docs/MIGRATION-v1-to-v2.md.

Since v2.0.0 Copy Section

• v2.1.0 (May 2026): currency refresh. May 2026 core update, Google I/O 2026 (custom version of Gemini 2.5 powers AI Mode), FAQ rich results retired 2026-05-07 (QAPage remains the type for genuine Q&A pages, FAQ markup itself just no longer yields rich results).
• v2.2.0 (June 2026): security + portability. Installer credential-injection fix, SSRF authority-confusion bypass closed, Google API keys moved to the X-Goog-Api-Key header, secret-scan CI gate, Windows/macOS fixes; suite at 326.
• v2.2.1 (June 2026): Google-currency reconfirmation + full command audit. Lighthouse 13.4.0 with the new Agentic Browsing category, Google Search ignores llms.txt, an internally-reweighted E-E-A-T scorecard (Trust highest, per Google's 'trust is most important'); every /seo command and subcommand audited and COMMANDS.md brought to 100% coverage.
• v2.2.2 (July 2026): full-review maintenance. Corrected GBP Q&A handling, AI Mode model naming, image-model IDs, hook input behavior, and added a strict reference-graph consistency gate.
• v2.2.3 (July 2026): prompt-hygiene alignment. Normalized emphasis and punctuation across the prompt surface without changing behavior, routing, or output contracts.
• v2.2.4 (July 2026): community maintenance. Added the managed cross-platform runtime and safe sitemap discovery, repaired GSC pagination and totals, replaced removed Bing endpoints, fixed extension and Windows portability gaps, and reconciled every open issue and pull request.

Limitations Copy Chapter

Two real boundaries worth being upfront about.

Heavy client-side hydration timing. Phase A's headless renderer handles most SPAs out of the box (--render auto detects empty `` shells and switches to Playwright). Edge cases that still produce noisy findings: pages with hydration tied to scroll position past the fold, pages that fetch critical content after user interaction (modal opens, tab clicks), pages with race-condition-prone third-party widget mounts. For these, manually triggering the seo-visual subagent and comparing its Playwright snapshot to the raw-HTML subagents' findings is the recommended workflow.

Local-only without enrichment. The free tier makes no third-party API calls by default (audits still fetch the target URLs you point them at). Adding Google API credentials (Tier 0 through 3) unlocks real field data and live indexation status; without them, Core Web Vitals are lab estimates only and indexation is inferred from page-level signals. Adding MCP extensions (Ahrefs, DataForSEO, SE Ranking, Profound) similarly unlocks competitive and AI-citation data but requires their respective accounts.

Requirements Copy Chapter

• Python 3.10+
• Claude Code CLI
• Optional: Playwright Chromium — install.sh offers to install it (you can skip the prompt); needed only for SPA rendering and screenshots
• Optional: Google API credentials for enriched CWV / GSC / GA4 data (see /seo google setup)

Uninstall Copy Chapter

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/uninstall.sh

One-liner (curl)

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/uninstall.sh | bash

Extensions Copy Chapter

Optional MCP servers add live data to the audit pipeline. Claude SEO ships extensions for 8 servers; the plugin core works without any of them.

DataForSEO Copy Section

Live SERP data, keyword research, backlinks, on-page analysis, content analysis, business listings, AI visibility checks, and LLM mention tracking. 23 data commands across 9 API modules.

./extensions/dataforseo/install.sh   # requires DataForSEO account
/seo dataforseo serp best coffee shops
/seo dataforseo ai-mentions your brand

Full DataForSEO docs: extensions/dataforseo/README.md.

Firecrawl Copy Section

Full-site crawling and URL discovery via the Firecrawl MCP server.

./extensions/firecrawl/install.sh
/seo firecrawl crawl https://example.com

Full Firecrawl docs: extensions/firecrawl/README.md.

Banana: AI image generation Copy Section

SEO image generation (OG previews, blog heroes, product photos, infographics) via the Claude Banana Creative Director pipeline.

./extensions/banana/install.sh
/seo image-gen og "Professional SaaS dashboard"

Full Banana docs: extensions/banana/README.md.

Ahrefs, SE Ranking, Profound, Bing Webmaster, Unlighthouse (new in v2) Copy Section

Five extensions added in Phase E:

• Ahrefs: official @ahrefs/mcp server with backlink and organic data
• SE Ranking: AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode
• Profound: LLM citation tracker with time-series data
• Bing Webmaster: Bing Webmaster Tools plus IndexNow unified
• Unlighthouse: MIT-licensed multi-page Lighthouse runner

Setup walkthroughs live under extensions/<name>/docs/; integration notes: docs/MCP-INTEGRATION.md.

Ecosystem Copy Chapter

Claude SEO is part of a family of Claude Code skills that interoperate cleanly:

Workflow example:

1. /seo audit https://example.com: identify content gaps and technical issues
2. /seo backlinks https://example.com: analyze link profile and competitor gaps
3. /seo geo https://example.com/blog/post: score AI-citation readiness
4. /blog write "target keyword": create SEO-optimized blog post (Claude Blog)
5. /seo image-gen hero "blog topic": generate hero image (Banana extension)

Documentation Copy Chapter

• Installation Guide
• Commands Reference: every /seo command in depth
• Architecture: 3-layer design, auto-discovery, parallel dispatch
• Migration v1 → v2: breaking changes, six phases of work
• MCP Integration: integration notes; extension setup lives under extensions/<name>/docs/
• Troubleshooting
• Contributors: community credits

FAQ Copy Chapter

What is Claude SEO? Copy Section

Claude SEO is an open-source SEO analysis plugin for Claude Code. It runs 25 sub-skills and 18 specialist agents in parallel across technical SEO, content quality, Schema.org markup, AI search optimization, local SEO, e-commerce, and international SEO. Audits produce a prioritized action plan where each recommendation carries the first-principle observation it rests on, its dependency relationship to other recommendations, a "how would we know this failed?" check, and a leading indicator. The plugin is MIT-licensed, ships zero proprietary tracking, and works without third-party API enrichment; audits still contact the target URLs you analyze. Aligned with Google's AI Optimization Guide and the September 2025 Quality Rater Guidelines.

How is Claude SEO different from Screaming Frog or Ahrefs Site Audit? Copy Section

Different surface area, different tradeoffs. Screaming Frog crawls deeper and faster at the link-graph level; it is purpose-built as a crawler and Claude SEO does not attempt to replace it. Ahrefs Site Audit brings a proprietary backlink index and link intelligence; Claude SEO integrates with Ahrefs via its MCP extension rather than competing. Where Claude SEO leads: conversational LLM-native workflow, recommendation falsifiability (every finding carries an explicit failure-mode check), open-source MIT licensing with zero per-domain pricing, AI search optimization aligned with Google's primary-source guidance, and primary-source schema-deprecation tracking. Use Screaming Frog or Ahrefs for what they are best at; use Claude SEO when you want LLM-driven synthesis, conversational iteration, and AI-search-first audits in the same environment as your other Claude Code workflows.

Does Claude SEO work on single-page applications (Next.js, React, Vue)? Copy Section

Yes. Phase A of v2 shipped a shared headless renderer (scripts/render_page.py) backed by Playwright Chromium. Audit subagents call render_page.py --mode auto, which auto-detects SPA hallmarks (empty `` shells, single bundle script, hydration markers) and switches to a rendered fetch. The lower-level scripts/fetch_page.py wrapper supports --render auto as an opt-in wrapper mode; its default is --render never for raw HTTP. Use render_page.py --mode always or fetch_page.py --render always to force rendering. Content extraction uses trafilatura for boilerplate removal. Publication dates come from htmldate. Known nuance: pages with scroll-bound hydration or post-interaction content fetches still produce noisy findings; see the Limitations section for the recommended seo-visual cross-check workflow on those edge cases.

What Google APIs does Claude SEO use, and are they required? Copy Section

None are required. Claude SEO is fully functional with zero API keys. A 4-tier credential system lets you upgrade gradually: Tier 0 (API key only) unlocks PageSpeed Insights, CrUX, and CrUX History (25-week trend data). Tier 1 (+ OAuth or service account) adds Search Console with queries, URL Inspection, sitemap status, and the Indexing API for eligible JobPosting pages or BroadcastEvent in VideoObject pages; the API does not guarantee indexing. Tier 2 (+ GA4 property config) adds organic traffic, top landing pages, and device / country breakdowns. Tier 3 (+ Ads developer token) adds Keyword Planner search volume and competition data. The credential setup wizard runs via /seo google setup. All credentials live under ~/.config/claude-seo/ with 0o600 file permissions; nothing is checked into the repo and nothing is transmitted beyond Google's own endpoints.

Is Claude SEO free? Copy Section

Yes. MIT licensed, fully open source, no per-domain pricing, no telemetry, no API quotas imposed by the plugin itself. The core plugin and all 25 sub-skills work without any paid service. Some optional MCP extensions wrap paid services (DataForSEO, Ahrefs, Profound, SE Ranking) where you bring your own account credentials; their use is opt-in and the plugin works fully without them. Google APIs (PageSpeed Insights, Search Console, Indexing, GA4) are free from Google with normal account quota limits and require your own credentials. If you want commercial support or enterprise features beyond the open-source plugin, that is not part of this project.

How is Claude SEO different from regular SEO tools when it comes to AI search? Copy Section

Most SEO tools treat AI search as a separate optimization discipline. Claude SEO follows Google's own position that AEO and GEO are rebranded labels for SEO. AI Overviews and AI Mode are grounded in the same ranking systems as classic Search; the eligibility floor is normal indexation. Claude SEO scores passage citability (134-167 word self-contained answer blocks), question-based heading hierarchy, attribution density, and entity presence across Wikipedia, Reddit, YouTube, and LinkedIn. It explicitly rejects three influencer myths: llms.txt as a citation lever, content chunking for AI, and AI-specific keyword rewriting. For commerce sites, Claude SEO audits the IPTC TrainedAlgorithmicMedia requirement on AI-generated product images per Google Merchant Center policy.

Community Contributors Copy Chapter

v1.9.0 includes contributions from the AI Marketing Hub Pro Hub Challenge:

See CONTRIBUTORS.md for full details and original repo links.

License Copy Chapter

MIT License. See LICENSE for details.

Contributing Copy Chapter

Contributions welcome. Please read CONTRIBUTING.md before submitting PRs and include the tests or checks you ran in the PR description.

Author Copy Chapter

Built by Agrici Daniel, AI Workflow Architect. Single maintainer, open to community contributions via the Pro Skool community. Background in marketing automation, AI-assisted content workflows, and open-source tooling for Claude Code.

• Blog: deep dives on AI marketing automation
• AI Marketing Hub (free): open community
• AI Marketing Hub Pro: Pro community, early access to this skill
• YouTube: tutorials and demos
• GitHub: all open-source tools

File: docs/ARCHITECTURE.md Copy Chapter

Architecture

Overview Copy Chapter

Claude SEO follows Anthropic's official Claude Code skill specification with a modular, multi-skill architecture.

Directory Structure Copy Chapter

The plugin ships 25 sub-skills (21 core + 1 orchestrator + 1 framework integration + 2 extension mirrors) and 18 sub-agents (15 core + 1 framework integration + 2 extension mirrors).

/* Detailed source-code truncated for AI context efficiency. */

Component Types Copy Chapter

Skills Copy Section

Skills are markdown files with YAML frontmatter that define capabilities and instructions.

SKILL.md Format:

---
name: skill-name
  When to use this skill. Include activation keywords
  and concrete use cases.
---

# Skill Title

Instructions and documentation...

Subagents Copy Section

Subagents are specialized workers that can be delegated tasks. They have their own context and tools.

Agent Format:

---
name: agent-name
tools: Read, Bash, Write, Glob, Grep
---

Instructions for the agent...

Reference Files Copy Section

Reference files contain static data loaded on-demand to avoid bloating the main skill.

Orchestration Flow Copy Chapter

Full Audit (`/seo audit`) Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Individual Command Copy Section

User Request (e.g., /seo page)
    │
    ▼
┌─────────────────┐
│   seo       │  ← Routes to sub-skill
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   seo-page      │  ← Sub-skill handles directly
│   (SKILL.md)    │
└─────────────────┘

Design Principles Copy Chapter

1. Progressive Disclosure Copy Section

• Main SKILL.md stays under 500 lines (per the development rules)
• Reference files loaded on-demand
• Detailed instructions in sub-skills

2. Parallel Processing Copy Section

• Subagents run concurrently during audits
• Independent analyses don't block each other
• Results aggregated after all complete

3. Quality Gates Copy Section

• Built-in thresholds prevent bad recommendations
• Location page limits (30 warning, 50 hard stop)
• Schema deprecation awareness
• FID → INP replacement enforced

4. Industry Awareness Copy Section

• Templates for different business types
• Automatic detection from homepage signals
• Tailored recommendations per industry

File Naming Conventions Copy Chapter

Extension Points Copy Chapter

Adding a New Sub-Skill Copy Section

1. Create skills/seo-newskill/SKILL.md
2. Add YAML frontmatter with name and description
3. Write skill instructions
4. Update main skills/seo/SKILL.md to route to new skill

Adding a New Subagent Copy Section

1. Create agents/seo-newagent.md
2. Add YAML frontmatter with name, description, tools
3. Write agent instructions
4. Reference from relevant skills

Adding a New Reference File Copy Section

1. Create file in appropriate references/ directory
2. Reference in skill with load-on-demand instruction

Extensions Copy Chapter

Managed Python runtime Copy Section

Bundled tools are dispatched through bin/claude-seo and
scripts/runtime.py, never through a working-directory-relative Python command.
The launcher resolves Python 3.10 or newer, while the standard-library runtime
provides three operations: run, setup, and read-only doctor.

Plugin environments live under persistent CLAUDE_PLUGIN_DATA. Manual installs
keep the compatible ~/.claude/skills/seo/.venv location. A state marker records
the runtime schema, requirements SHA-256, Python major and minor version, public
plugin version, and browser state. Requirements, runtime-schema, or Python ABI
changes require explicit setup; a version-only difference remains compatible and
is refreshed on the next setup. Environment replacement is staged and rolled
back if validation or marker publication fails.

run accepts only allowlisted script basenames or a contained extension script.
It forwards arguments without a shell, preserves child exit codes, forces UTF-8
child streams, and uses the same persistent Playwright browser directory created
by setup.

Extensions are opt-in add-ons that integrate external data sources via MCP servers. They live in extensions/<name>/ and ship their own install / uninstall scripts.

/* Detailed source-code truncated for AI context efficiency. */

Available Extensions Copy Section

Extension Convention Copy Section

1. Self-contained in extensions/<name>/
2. Own install.sh (and install.ps1 where Windows is supported) that copies files and configures MCP (where applicable)
3. Own uninstall.sh (and uninstall.ps1 where present) that reverses installation
4. Installs the sub-skill mirror to the plugin's skill directory
5. Installs the sub-agent mirror to the plugin's agent directory (extensions that ship one; lighter extensions are skill-only)
6. Merges MCP config into ~/.claude/settings.json non-destructively
7. MCP server versions are pinned (@<version>) for supply-chain stability

File: docs/COMMANDS.md Copy Chapter

Commands Reference

Overview Copy Chapter

All Claude SEO commands start with /seo followed by a subcommand.

Command List Copy Chapter

`/seo setup` Copy Section

Explicitly create or refresh the isolated Python runtime and Playwright Chromium.
This is required once after a marketplace plugin install. Manual installers run
the same setup automatically. It never installs packages globally.

`/seo doctor` Copy Section

Check runtime, dependency, and Chromium readiness without changing the system.
Diagnostic output omits absolute paths and environment values.

`/seo audit ` Copy Section

Full website SEO audit with parallel analysis.

Example:

/seo audit https://example.com

What it does:

1. Crawls up to 500 pages
2. Detects business type
3. Delegates to up to 15 specialist subagents in parallel (8 always-on + 7 conditional)
4. Generates SEO Health Score (0-100)
5. Creates prioritized action plan

Output:

• FULL-AUDIT-REPORT.md
• ACTION-PLAN.md
• screenshots/ (if Playwright available)

`/seo page ` Copy Section

Deep single-page analysis.

Example:

/seo page https://example.com/about

What it analyzes:

• On-page SEO (title, meta, headings, URLs)
• Content quality (word count, readability, E-E-A-T)
• Technical elements (canonical, robots, Open Graph)
• Schema markup
• Images (alt text, sizes, formats)
• Core Web Vitals potential issues

`/seo technical ` Copy Section

Technical SEO audit across 9 categories.

Example:

/seo technical https://example.com

Categories:

1. Crawlability
2. Indexability
3. Security
4. URL Structure
5. Mobile Optimization
6. Core Web Vitals (LCP, INP, CLS)
7. Structured Data
8. JavaScript Rendering
9. IndexNow Protocol

`/seo content ` Copy Section

E-E-A-T and content quality analysis.

Example:

/seo content https://example.com/blog/post

What it evaluates:

• Experience signals (first-hand knowledge)
• Expertise (author credentials)
• Authoritativeness (external recognition)
• Trustworthiness (transparency, security)
• AI citation readiness
• Content freshness

`/seo content-brief ` Copy Section

Generate a detailed SEO content brief: target keywords, search intent, heading outline, internal link targets, and competitor angle.

Example:

/seo content-brief "best running shoes for flat feet"

What it produces:

• Primary and secondary target keywords
• Search intent and audience
• Section-by-section heading outline
• Internal link recommendations
• Competitor content angles to beat

`/seo schema ` Copy Section

Schema markup detection, validation, and generation.

Example:

/seo schema https://example.com

What it does:

• Detects existing schema (JSON-LD, Microdata, RDFa)
• Validates against Google's requirements
• Identifies missing opportunities
• Generates ready-to-use JSON-LD

`/seo geo ` Copy Section

AI Overviews / Generative Engine Optimization.

Example:

/seo geo https://example.com/blog/guide

What it analyzes:

• Citability score (quotable facts, statistics)
• Structural readability (headings, lists, tables)
• Entity clarity (definitions, context)
• Authority signals (credentials, sources)
• Structured data support

`/seo images ` Copy Section

Image optimization analysis. Subcommands: serp <keyword> (image SERP / visual-search analysis), optimize (local file optimization + IPTC AI labeling).

Examples:

/seo images https://example.com
/seo images serp "running shoes"
/seo images optimize ./hero.webp

What it checks:

• Alt text presence and quality
• File sizes (flag >200KB)
• Formats (WebP/AVIF recommendations)
• Responsive images (srcset, sizes)
• Lazy loading
• CLS prevention (dimensions)

`/seo sitemap ` Copy Section

Analyze existing XML sitemap.

Example:

/seo sitemap https://example.com/sitemap.xml

What it validates:

• XML format
• URL count (<50k per file)
• URL status codes
• lastmod accuracy
• Deprecated tags (priority, changefreq)
• Coverage vs crawled pages

`/seo sitemap generate` Copy Section

Generate new sitemap with industry templates.

Example:

/seo sitemap generate

Process:

1. Select or auto-detect business type
2. Interactive structure planning
3. Apply quality gates (30/50 location page limits)
4. Generate valid XML
5. Create documentation

`/seo plan ` Copy Section

Strategic SEO planning.

Types: saas, local, ecommerce, publisher, agency

Example:

/seo plan saas

What it creates:

• Complete SEO strategy
• Competitive analysis
• Content calendar
• Implementation roadmap (4 phases)
• Site architecture design

`/seo competitor-pages [url|generate]` Copy Section

Competitor comparison page generation.

Examples:

/seo competitor-pages https://example.com/vs/competitor
/seo competitor-pages generate

Capabilities:

• Generate "X vs Y" comparison page layouts
• Create "Alternatives to X" page structures
• Build feature comparison matrices with scoring
• Generate Product + AggregateRating schema markup
• Apply conversion-optimized CTA placement
• Enforce fairness guidelines (accurate data, source citations)

`/seo hreflang [url]` Copy Section

Hreflang and international SEO audit and generation. Subcommand: audit <directory-or-url> (audit hreflang across a local build directory or a live URL set).

Examples:

/seo hreflang https://example.com
/seo hreflang audit ./dist

Capabilities:

• Validate self-referencing hreflang tags
• Check return tag reciprocity (A→B requires B→A)
• Verify x-default tag presence
• Validate ISO 639-1 language and ISO 3166-1 region codes
• Check canonical URL alignment with hreflang
• Detect protocol mismatches (HTTP vs HTTPS)
• Generate correct hreflang link tags and sitemap XML

`/seo programmatic [url|plan]` Copy Section

Programmatic SEO analysis and planning for pages generated at scale.

Examples:

/seo programmatic https://example.com/tools/
/seo programmatic plan

Capabilities:

• Assess data source quality (CSV, JSON, API, database)
• Plan template engines with unique content per page
• Design URL pattern strategies (/tools/[tool-name], /[city]/[service])
• Automate internal linking (hub/spoke, related items, breadcrumbs)
• Enforce thin content safeguards (quality gates, word count thresholds)
• Prevent index bloat (noindex low-value, pagination, faceted nav)

`/seo local ` Copy Section

Local SEO analysis covering Google Business Profile, citations, reviews, and the map pack.

Example:

/seo local https://example.com

What it analyzes:

• Google Business Profile signals (categories, hours, photos, posts)
• NAP (Name, Address, Phone) consistency across the page and external citations
• Review velocity, response rate, and sentiment
• Local schema markup (LocalBusiness, Restaurant, Service-specific types)
• Industry-specific local factors (brick-and-mortar, SAB, hybrid)
• Map pack visibility signals

`/seo maps [command] [args]` Copy Section

Maps intelligence: geo-grid rank tracking, GBP profile audits, review intelligence, cross-platform NAP verification, competitor radius mapping.

Examples:

/seo maps "Joe's Coffee" "austin tx"
/seo maps grid "coffee shop" "austin tx"
/seo maps gbp "Joe's Coffee" "austin tx"
/seo maps reviews "Joe's Coffee" "austin tx"
/seo maps competitors "auto repair" "denver"
/seo maps nap "Joe's Coffee" "austin tx"
/seo maps schema "Joe's Coffee" "austin tx"

Capabilities:

• Rank tracking on a geographic grid (typically 49 points)
• GBP profile audit with completeness scoring
• Review aggregation across Google, Yelp, Facebook, Bing
• Competitor discovery within a configurable radius

`/seo backlinks ` Copy Section

Backlink profile analysis with a 3-tier data cascade: free (Common Crawl + verification), free with signup (Moz, Bing Webmaster Tools), paid (DataForSEO).

Examples:

/seo backlinks https://example.com
/seo backlinks gap https://example.com https://competitor.com
/seo backlinks toxic https://example.com
/seo backlinks new https://example.com
/seo backlinks verify https://example.com --links known-links.txt
/seo backlinks setup

What it analyzes:

• Domain Authority and Page Authority (Moz)
• Referring domain count and growth
• Anchor text distribution (branded, exact, partial, naked URL)
• Toxic / spammy backlink detection
• Lost backlinks
• Competitor link gap

`/seo cluster [command] ` Copy Section

SERP-based semantic topic clustering for content architecture planning. Built on the Pro Hub Challenge Semantic Cluster Engine. Subcommands: plan <seed> (full planning workflow; also plan --from strategy to import a /seo plan output), execute (create content via claude-blog or output briefs), map (regenerate the interactive visualization). Bare /seo cluster <seed> is shorthand for plan.

Examples:

/seo cluster plan "claude code skills"
/seo cluster plan --from strategy
/seo cluster execute
/seo cluster map

What it produces:

• Keyword expansion from the seed (50-200 candidates)
• Pairwise SERP overlap comparison to detect semantic clusters
• Intent classification per cluster (informational, commercial, transactional, navigational)
• Hub-and-spoke content architecture proposal
• Internal link matrix between cluster pages
• Interactive cluster-map.html visualization

`/seo sxo ` Copy Section

Search Experience Optimization: SERP backwards analysis, page-type mismatch detection, persona scoring. Subcommands: <keyword> (analyze for a specific keyword), wireframe (IST/SOLL wireframe), personas (persona-only scoring, skips SERP).

Examples:

/seo sxo https://example.com/blog/how-to-x
/seo sxo https://example.com/page "target keyword"
/seo sxo wireframe https://example.com/page
/seo sxo personas https://example.com/page

What it produces:

• Page-type taxonomy classification (article, landing, product, tool, listing)
• SERP intent vs page-type alignment check
• User stories derived from SERP signals
• Multi-persona scoring (researcher, buyer, expert, casual visitor)
• Wireframe-level recommendations for fixing mismatches

`/seo drift baseline|compare|history ` Copy Section

SEO drift monitoring. Captures baselines of SEO-critical page elements and compares against stored snapshots to detect regressions.

Examples:

/seo drift baseline https://example.com
/seo drift compare https://example.com
/seo drift history https://example.com

What it tracks: title, meta description, canonical, hreflang, Open Graph, schema, headings, internal links, robots, sitemap entry, indexability, Core Web Vitals, response status, redirect chain.

17 comparison rules classify changes by severity (CRITICAL, HIGH, MEDIUM). SQLite-backed baselines.

`/seo ecommerce ` Copy Section

E-commerce SEO covering product schema, marketplace intelligence, and pricing gap analysis. Subcommands: products <keyword> (Google Shopping competitive analysis), gaps <domain> (organic-vs-Shopping visibility gap), schema (product schema validation + enhancement).

Examples:

/seo ecommerce https://shop.example.com/product/x
/seo ecommerce products "running shoes"
/seo ecommerce gaps shop.example.com
/seo ecommerce schema https://shop.example.com/product/x

What it analyzes:

• Product schema (Product, Offer, AggregateRating, Review)
• Google Shopping visibility
• Amazon marketplace presence
• Pricing gap vs competitors
• Out-of-stock and availability signals
• Faceted navigation crawl traps

`/seo flow [stage] [url|topic]` Copy Section

FLOW framework integration: evidence-led prompts for the Find, Leverage, Optimize, Win, and Local stages of a content campaign.

Examples:

/seo flow find "topic"
/seo flow leverage https://example.com
/seo flow optimize https://example.com/page
/seo flow win https://example.com/page
/seo flow local https://example.com
/seo flow prompts
/seo flow sync

41 prompts sourced from FLOW (CC BY 4.0). Each prompt is grounded in a specific evidence source (SERP data, GSC, GA4, customer interviews) with attribution preserved.

`/seo google [command] [url]` Copy Section

Google SEO APIs. 4-tier credential system covering PageSpeed Insights, CrUX, CrUX History, Search Console, URL Inspection, Indexing API, GA4, and Keyword Planner.

Setup & reporting:

/seo google setup                      # Configure/check credentials
/seo google quotas                     # Show per-API quota usage
/seo google report full                # Generate full PDF/HTML report
/seo google report cwv-audit           # CWV-focused report
/seo google report gsc-performance     # Search performance report
/seo google report indexation          # Indexation status report

PageSpeed / CrUX (Tier 0):

/seo google pagespeed             # PageSpeed Insights (lab) + CWV
/seo google crux                  # CrUX field data
/seo google crux-history          # 25-week CrUX history

Search Console / Indexing (Tier 1):

/seo google gsc              # Search Analytics (clicks/impressions/CTR/position)
/seo google inspect               # URL Inspection (indexation status)
/seo google inspect-batch <file>       # Batch URL inspection
/seo google sitemaps         # List submitted sitemaps + status
/seo google index                 # Indexing API notify
/seo google index-batch <file>         # Batch indexing notify

Use Indexing API commands only for pages with JobPosting or BroadcastEvent embedded in VideoObject. Route ordinary URLs to URL Inspection or sitemaps; URL_UPDATED does not guarantee indexing.

GA4 (Tier 2):

/seo google ga4 [property-id]          # Organic traffic report
/seo google ga4-pages [property-id]    # Top organic landing pages

NLP / Keywords / YouTube:

/seo google nlp           # NLP content analysis
/seo google entities      # Entity extraction
/seo google entity <query>             # Entity lookup
/seo google keywords <seed>            # Keyword Planner ideas (Tier 3)
/seo google volume <keywords>          # Keyword search volume (Tier 3)
/seo google youtube <query>            # YouTube search
/seo google youtube-video <video_id>   # YouTube video analysis
/seo google safety                # Safe Browsing check

Tiers:

• Tier 0 (API key only): PSI, CrUX, CrUX History
• Tier 1 (+ OAuth or Service Account): GSC, URL Inspection, Indexing API
• Tier 2 (+ GA4 property config): GA4 organic traffic
• Tier 3 (+ Google Ads developer token): Keyword Planner

PDF and HTML reports generated via WeasyPrint and matplotlib.

`/seo image-gen [use-case] ` Copy Section

AI image generation for SEO assets (extension). Powered by Gemini via nanobanana-mcp.

Prerequisites: Banana extension installed (./extensions/banana/install.sh)

Use Cases:

/seo image-gen og <description>          # OG/social preview image (16:9, 1K)
/seo image-gen hero <description>        # Blog hero image (16:9, 2K)
/seo image-gen product <description>     # Product photography (4:3, 2K)
/seo image-gen infographic <description> # Infographic visual (2:3, 4K)
/seo image-gen custom <description>      # Custom with full Creative Director pipeline
/seo image-gen batch <description> [N]   # Generate N variations (default: 3)

What it does:

1. Maps SEO use case to optimized domain mode, aspect ratio, and resolution
2. Constructs 6-component Reasoning Brief (Creative Director pipeline)
3. Generates image via Gemini API
4. Provides SEO checklist (alt text, file naming, WebP, schema markup)

`/seo firecrawl [command] ` Copy Section

Full-site crawling and URL discovery via Firecrawl MCP (extension).

Prerequisites: Firecrawl extension installed (./extensions/firecrawl/install.sh)

Examples:

/seo firecrawl crawl https://example.com
/seo firecrawl map https://example.com
/seo firecrawl scrape https://example.com/page
/seo firecrawl search "query" https://example.com

What it does:

• crawl walks the site discovering URLs and capturing content
• map returns the full URL inventory for a domain
• scrape extracts a single page in a model-friendly format
• search searches within a crawled site for a query

`/seo dataforseo [command]` Copy Section

Live SEO data via DataForSEO MCP server (extension). 23 data commands across 9 API modules, plus cost-tracking commands.

Prerequisites: DataForSEO extension installed (./extensions/dataforseo/install.sh)

SERP Analysis:

/seo dataforseo serp <keyword>              # Google organic results (also Bing/Yahoo)
/seo dataforseo serp-images <keyword>       # Google Images SERP results
/seo dataforseo serp-youtube <keyword>      # YouTube search results
/seo dataforseo youtube <video_id>          # YouTube video deep analysis

Keyword Research:

/seo dataforseo keywords <seed>             # Keyword ideas and suggestions
/seo dataforseo volume <keywords>           # Search volume metrics
/seo dataforseo difficulty <keywords>       # Keyword difficulty scores
/seo dataforseo intent <keywords>           # Search intent classification
/seo dataforseo trends <keyword>            # Google Trends data

Domain & Competitors:

/seo dataforseo backlinks <domain>          # Full backlink profile
/seo dataforseo competitors <domain>        # Competitor analysis
/seo dataforseo ranked <domain>             # Ranked keywords
/seo dataforseo intersection <domains>      # Keyword/backlink overlap
/seo dataforseo traffic <domains>           # Traffic estimation
/seo dataforseo subdomains <domain>         # Subdomains with ranking data
/seo dataforseo top-searches <domain>       # Top queries mentioning domain

Technical / On-Page:

/seo dataforseo onpage                 # On-page analysis (Lighthouse)
/seo dataforseo tech <domain>               # Technology detection
/seo dataforseo whois <domain>              # WHOIS data

Content & Business Data:

/seo dataforseo content <keyword/url>       # Content analysis and trends
/seo dataforseo listings <keyword>          # Business listings search

AI Visibility / GEO:

/seo dataforseo ai-scrape <query>           # ChatGPT web scraper for GEO
/seo dataforseo ai-mentions <keyword>       # LLM mention tracking

Cost Tracking:

/seo dataforseo costs today                            # Today's DataForSEO spend
/seo dataforseo costs summary                          # Spend summary across periods
/seo dataforseo costs config --mode threshold --threshold 0.50   # Set cost-control mode/threshold

`/seo ahrefs [command] ` Copy Section

Ahrefs API metrics (extension). Prerequisites: Ahrefs extension installed (./extensions/ahrefs/install.sh).

/seo ahrefs metrics        # DR/UR, referring-domain count, organic traffic estimate
/seo ahrefs backlinks      # Top referring domains, anchor distribution, follow/nofollow ratio
/seo ahrefs organic        # Organic keywords, ranking distribution, traffic by country
/seo ahrefs content <topic>     # Content Explorer top results, social shares, referring domains

`/seo bing [command]` Copy Section

Bing Webmaster Tools + IndexNow (extension). Prerequisites: Bing extension installed (./extensions/bing-webmaster/install.sh).

/seo bing links                  # Inbound links from Bing Webmaster
/seo bing compare         # Compare two URLs' Bing link profiles
/seo bing submit  --host <host>                # IndexNow single-URL submit (requires key)
/seo bing submit-batch <file> --host <host>         # IndexNow batch submit (requires key)
/seo bing verify-indexnow --host <host>             # Verify the IndexNow key is published

`/seo profound [command] ` Copy Section

LLM brand-citation tracking via Profound (extension). Prerequisites: Profound extension installed.

/seo profound citations      # Citation rate per LLM + 30-day trend
/seo profound prompts        # Top prompts that surface (or miss) the brand
/seo profound competitors    # Brands cited alongside yours for the same prompts
/seo profound alerts         # Spike/drop alerts vs 7-day baseline

`/seo seranking [command] ` Copy Section

AI-visibility + SERP via SE Ranking (extension). Prerequisites: SE Ranking extension installed.

/seo seranking ai-visibility    # Share-of-voice across ChatGPT/Gemini/Perplexity/AI Overviews/AI Mode
/seo seranking serp <keyword>          # Top 100 organic positions + SERP features
/seo seranking backlinks          # Backlink profile (free-tier alternative to Ahrefs/DataForSEO)
/seo seranking competitors        # Top 10 organic competitors + shared-keyword gaps

`/seo unlighthouse ` Copy Section

Multi-page Lighthouse audit via Unlighthouse (extension, MIT, no API quota). Prerequisites: Node 18+ and the unlighthouse npm package (./extensions/unlighthouse/install.sh).

/seo unlighthouse https://example.com
/seo unlighthouse https://example.com --device desktop
/seo unlighthouse https://example.com --max-routes 50 --output-dir ./reports

Quick Reference Copy Chapter

File: docs/INSTALLATION.md Copy Chapter

Installation Guide

Prerequisites Copy Chapter

• Python 3.10+ with pip
• Git for cloning the repository
• Claude Code CLI installed and configured

Optional:

• Playwright Chromium - install.sh attempts this automatically; failure is non-fatal; needed only for SPA rendering and screenshots

Quick Install Copy Chapter

Plugin Install (Claude Code 1.0.33+) Copy Section

The recommended path. Inside Claude Code:

/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo
/seo setup

Plugin installation does not run package managers. /seo setup is an explicit,
one-time provisioning step that writes the virtual environment and browser only
to Claude's persistent plugin data. Use /seo doctor for a read-only check.

Manual Install (Unix, macOS, Linux) Copy Section

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/install.sh

Review-then-run alternative:

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh
cat install.sh        # review
bash install.sh       # run when satisfied
rm install.sh

Manual Install (Windows, PowerShell) Copy Section

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
powershell -ExecutionPolicy Bypass -File claude-seo\install.ps1

The Windows path uses git clone rather than irm | iex because Claude Code's own security guardrails flag piped remote-script execution. Inspect install.ps1 before running.

Manual Installation Copy Chapter

1. Clone the repository

git clone https://github.com/AgriciDaniel/claude-seo.git
cd claude-seo

2. Run the installer

./install.sh

3. Verify the managed runtime

The installer delegates dependency and Chromium provisioning to the same runtime
used by every skill. It creates ~/.claude/skills/seo/.venv/ and never falls
back to global or user package installation.

~/.claude/skills/seo/bin/claude-seo doctor

If core setup failed, rerun the inspected installer. If only Chromium failed,
the installer reports a degraded result and raw-fetch analysis remains available.

Installation Paths Copy Chapter

The installer copies files to:

Verify Installation Copy Chapter

1. Start Claude Code:

claude

2. Check that the skill is loaded:

/seo

You should see a help message or prompt for a URL.

Uninstallation Copy Chapter

If installed as a plugin:

/plugin uninstall claude-seo@agricidaniel-claude-seo
/plugin marketplace remove AgriciDaniel/claude-seo

If installed manually, run the uninstaller from a fresh clone:

git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git
bash claude-seo/uninstall.sh

uninstall.sh removes all installed sub-skills, sub-agents, and the plugin's MCP entries from ~/.claude/settings.json. Do not maintain a hand-coded rm list. The shipped uninstaller is the canonical source.

Upgrading Copy Chapter

To upgrade to the latest version:

Caution: Prefer downloading, inspecting, then running remote scripts; the pipe-to-shell form below is the less-safe convenience option.

# Uninstall current version
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/uninstall.sh | bash

# Install new version
curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash

Troubleshooting Copy Chapter

"Skill not found" error Copy Section

Ensure the skill is installed in the correct location:

ls ~/.claude/skills/seo/SKILL.md

If the file doesn't exist, re-run the installer.

Python dependency errors Copy Section

Run the managed setup again:

~/.claude/skills/seo/bin/claude-seo setup

Playwright screenshot errors Copy Section

Run the managed setup again and inspect the result:

~/.claude/skills/seo/bin/claude-seo setup
~/.claude/skills/seo/bin/claude-seo doctor

Permission errors on Unix Copy Section

Make sure scripts are executable:

chmod +x ~/.claude/skills/seo/scripts/*.py

File: docs/MCP-INTEGRATION.md Copy Chapter

MCP Integration

Overview Copy Chapter

Claude SEO can integrate with Model Context Protocol (MCP) servers to access external APIs and enhance analysis capabilities.

Available Integrations Copy Chapter

PageSpeed Insights API Copy Section

Use Google's PageSpeed Insights API directly for real Core Web Vitals data.

Configuration:

1. Get an API key from Google Cloud Console
2. Enable the PageSpeed Insights API
3. Use in your analysis:

curl -H "X-Goog-Api-Key: $GOOGLE_API_KEY" \
  "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL"

Google Search Console Copy Section

For organic search data, use the mcp-server-gsc MCP server by ahonn. Provides search performance data, URL inspection, and sitemap management.

Configuration:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "mcp-server-gsc"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

PageSpeed Insights MCP Server Copy Section

Use mcp-server-pagespeed by enemyrr for Lighthouse audits, CWV metrics, and performance scoring via MCP.

Configuration:

{
  "mcpServers": {
    "pagespeed": {
      "command": "npx",
      "args": ["-y", "mcp-server-pagespeed"],
      "env": {
        "PAGESPEED_API_KEY": "your-api-key"
      }
    }
  }
}

Official SEO MCP Servers (2025-2026) Copy Section

The MCP ecosystem for SEO has matured significantly. These are production-ready integrations:

API Usage Examples Copy Chapter

PageSpeed Insights Copy Section

import requests

def get_pagespeed_data(url: str, api_key: str) -> dict:
    """Fetch PageSpeed Insights data for a URL."""
    endpoint = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
    params = {
        "url": url,
        "strategy": "mobile",  # or "desktop"
        "category": ["performance", "accessibility", "best-practices", "seo"]
    }
    headers = {"X-Goog-Api-Key": api_key}
    response = requests.get(endpoint, params=params, headers=headers)
    return response.json()

Core Web Vitals from CrUX Copy Section

def get_crux_data(url: str, api_key: str) -> dict:
    """Fetch Chrome UX Report data for a URL."""
    endpoint = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"
    payload = {
        "url": url,
        "formFactor": "PHONE"  # or "DESKTOP"
    }
    headers = {"Content-Type": "application/json", "X-Goog-Api-Key": api_key}
    response = requests.post(endpoint, json=payload, headers=headers)
    return response.json()

Metrics Available Copy Chapter

From PageSpeed Insights Copy Section

From CrUX (Field Data) Copy Section

Best Practices Copy Chapter

1. Rate Limiting: Respect API quotas (typically 25k requests/day for PageSpeed)
2. Caching: Cache results to avoid redundant API calls
3. Field vs Lab: Prioritize field data (CrUX) for ranking signals
4. Error Handling: Handle API errors gracefully

Without API Keys Copy Chapter

If you don't have API keys, Claude SEO can still:

1. Analyze HTML source for potential issues
2. Identify common performance problems
3. Check for render-blocking resources
4. Evaluate image optimization opportunities
5. Detect JavaScript-heavy implementations

The analysis will note that actual Core Web Vitals measurements require field data from real users.

File: docs/TROUBLESHOOTING.md Copy Chapter

Troubleshooting

Common Issues Copy Chapter

Skill Not Loading Copy Section

Symptom: /seo command not recognized

Solutions:

For plugin installs, verify and reinstall through Claude Code:

/plugin list
/plugin marketplace add AgriciDaniel/claude-seo
/plugin install claude-seo@agricidaniel-claude-seo

For manual installs:

1. Verify installation:

ls ~/.claude/skills/seo/SKILL.md

2. Check SKILL.md has proper frontmatter:

head -5 ~/.claude/skills/seo/SKILL.md

Should start with --- followed by YAML.

3. Restart Claude Code:

claude

4. Re-run installer:

Caution: Prefer downloading, inspecting, then running remote scripts; the pipe-to-shell form below is the less-safe convenience option.

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh | bash

Python Dependency Errors Copy Section

Symptom: ModuleNotFoundError: No module named 'requests'

Solution:

Dependencies belong in the managed runtime. For a plugin install, run:

/seo doctor
/seo setup

For a manual install, run:

~/.claude/skills/seo/bin/claude-seo doctor
~/.claude/skills/seo/bin/claude-seo setup

Do not install individual packages, use pip --user, or create a PATH shim.

requirements.txt Not Found Copy Section

Symptom: No such file: requirements.txt after install

Solution: For plugin installs, reinstall the plugin first:

/plugin install claude-seo@agricidaniel-claude-seo

For manual installs, requirements.txt is copied to the skill directory:

ls ~/.claude/skills/seo/requirements.txt

If missing, download it directly:

curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/requirements.txt \
  -o ~/.claude/skills/seo/requirements.txt

Windows Python Detection Issues Copy Section

Symptom: python is not recognized or pip points to wrong Python

Solution (v1.2.0+): The Windows installer now tries both python and py -3. If both fail:

1. Install Python from python.org and check "Add to PATH"
2. Rerun install.ps1; it resolves py -3, python3, then python
3. Run /seo doctor after installation

Playwright Screenshot Errors Copy Section

Symptom: playwright._impl._errors.Error: Executable doesn't exist

Solution: rerun managed setup so the browser is installed through the same
interpreter and persistent browser directory:

/seo setup
/seo doctor

Permission Denied Errors Copy Section

Symptom: Permission denied when running scripts

Solution:

chmod +x ~/.claude/skills/seo/scripts/*.py

Subagent Not Found Copy Section

Symptom: Agent 'seo-technical' not found

Solution:

For plugin installs, check /plugin list and reinstall claude-seo@agricidaniel-claude-seo; subagents load from the plugin, not ~/.claude/agents/.

For manual installs:

1. Verify agent files exist:

ls ~/.claude/agents/seo-*.md

2. Check agent frontmatter:

head -5 ~/.claude/agents/seo-technical.md

3. Re-install agents:

cp /path/to/claude-seo/agents/*.md ~/.claude/agents/

Timeout Errors Copy Section

Symptom: Request timed out after 30 seconds

Solutions:

1. The target site may be slow: try again
2. Increase timeout in script calls
3. Check your network connection
4. Some sites block automated requests

Schema Validation False Positives Copy Section

Symptom: Hook blocks valid schema

Check:

1. Ensure placeholders are replaced
2. Verify @context is https://schema.org
3. Check for deprecated/retired types: HowTo and SpecialAnnouncement, plus the June 2025 retirements (ClaimReview, VehicleListing, EstimatedSalary, LearningVideo, and the CourseInfo carousel)
4. FAQPage rich results were retired for all sites on 2026-05-07. The hook does not block it because it remains a valid Schema.org type, but no AI or ranking benefit is confirmed.
5. Validate at Google's Rich Results Test

Slow Audit Performance Copy Section

Symptom: Full audit takes too long

Solutions:

1. Audit crawls up to 500 pages: large sites take time
2. Subagents run in parallel to speed up analysis
3. For faster checks, use /seo page on specific URLs
4. Check if site has slow response times

Getting Help Copy Chapter

1. Check the docs: Review COMMANDS.md and ARCHITECTURE.md

2. GitHub Issues: Report bugs at the repository

3. Logs: Check Claude Code's output for error details

Debug Mode Copy Chapter

To see detailed output, check Claude Code's internal logs or run scripts directly:

# Test fetch
python3 ~/.claude/skills/seo/scripts/fetch_page.py https://example.com

# Test parse
python3 ~/.claude/skills/seo/scripts/parse_html.py page.html --json

# Test screenshot
python3 ~/.claude/skills/seo/scripts/capture_screenshot.py https://example.com