Open Source Project #251: Claude SEO — An SEO Audit Team Inside Claude Code, with 26 Sub-Skills and 19 Specialist Agents Checking Your Site in Parallel

Introduction

"Don't give me a pile of warnings. Give me a plan."

This is article #251 in the "One Open Source Project a Day" series. Today's project is Claude SEO (AgriciDaniel/claude-seo).

Anyone who has run an SEO audit tool knows the feeling: hundreds of red and yellow warnings, and no idea which one to fix first. Claude SEO turns the SEO consultant into a Claude Code plugin. You give it a URL, a team of specialist agents checks the site in parallel, and the result is an action plan sorted by impact, with a note on how to verify each fix worked.

It is also a good case study in plugin engineering: 26 sub-skills, 19 agents, a set of Python scripts with SSRF protection, and a PostToolUse hook. It is large, but the structure is clear.

What You'll Learn

• What problem Claude SEO solves and how it divides work with traditional SEO tools
• Three commands to install it and how to run the first audit
• The /seo command system and the roles of the 19 agents
• How one /seo audit orchestrates parallel agents
• The plugin's layout, runtime isolation, SSRF protection, and hook design
• The GEO and Agentic checks aimed at AI search

Prerequisites

• Basic Claude Code usage; knowing what a Skill, Subagent, and Plugin are
• A passing familiarity with SEO terms (sitemap, canonical, Schema.org, Core Web Vitals)
• Enough Python to read scripts (the deep-dive touches a few implementation details)

Background

Overview

Claude SEO is a free, MIT-licensed Claude Code plugin. The README's positioning is direct: run a full SEO audit on any website inside Claude Code in roughly 10 to 15 minutes, then get an action plan sorted by importance.

Coverage, according to the README and plugin manifest:

• Technical SEO: crawling, indexing, sitemaps, robots.txt, redirects, page speed, Core Web Vitals
• Content quality: E-E-A-T, thin pages, topic coverage
• Structured data: detect, validate, and generate Schema.org markup
• AI search (GEO): how likely Google AI Overviews, AI Mode, ChatGPT, Perplexity, and Gemini are to cite your pages
• Local, e-commerce, and international SEO: Google Business Profile, reviews, map pack, product pages, hreflang

About the Author

• Author: Agrici Daniel (the README calls them an AI Workflow Architect), with help from members of the AI Marketing Hub Pro community
• Created: February 2026 (the GitHub API shows 2026-02-07)
• Related projects: Claude Blog (writing), Claude Banana (images), ChatGPT SEO, FLOW (an SEO framework with 42 AI prompts)

Project Stats

From the GitHub API, retrieved 2026-10-28:

• ⭐ GitHub Stars: 22,935
• 🍴 Forks: 3,116
• 📦 Version: v2.5.0 (released 2026-10-22)
• 📄 License: MIT
• 🧑‍💻 Main language: Python (about 1.56 MB), plus Shell, PowerShell, HTML
• 🌐 Website: https://claude-seo.md
• 🐛 Open issues: 68

The project went from creation in February to v2.5 by October, and the last three releases (v2.4.1, v2.4.2, v2.5.0) landed between late September and late October, so maintenance is active. The "1077 tests passing" badge is self-reported; I did not rerun the suite.

Main Features

Core Purpose

It turns a senior SEO consultant's checklist into a repeatable agent workflow. It is not a replacement for a crawler, and the README says so: tools like Screaming Frog crawl faster and deeper, and large SEO suites have their own backlink databases. What Claude SEO does differently:

1. Explains: each finding states its basis and impact
2. Ranks: Critical / High / Medium / Low
3. Converses: after the audit you can ask follow-ups in plain language
4. Covers AI search: GEO and agent readiness are first-class

Use Cases

1. Pre-launch check of your own site

   • One /seo audit https://your-domain gives a site health score and a fix list

2. Deep dive on a single page

   • /seo page analyzes a pricing or landing page item by item

3. AI search visibility

   • /seo geo rates how citable your pages are and whether AI crawlers can reach them

4. Before/after a redesign

   • Save a baseline with /seo drift baseline, then find regressions with /seo drift compare

5. Agencies and freelancers

   • Run an audit live on the first call and bring a real score and top fixes to the proposal

Quick Start

Requirements: Claude Code 1.0.33 or newer and Python 3.11 to 3.14. Inside Claude Code:

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

/seo setup creates an isolated Python runtime and a headless Chromium without touching the rest of your system. /seo doctor checks its status at any time.

Your first audit:

claude                                   # start Claude Code
 
/seo audit https://example.com           # full-site audit with a prioritized plan
/seo page https://example.com/pricing    # one page, in depth
/seo geo https://example.com             # AI search readiness
/seo schema https://example.com          # check and generate structured data
/seo local https://example.com           # local SEO and Google Business Profile

Manual installs are supported too (install.sh on macOS/Linux, install.ps1 on Windows). The README recommends git clone over irm | iex on Windows, because Claude Code's own guardrails flag the latter as a supply-chain risk; cloning lets you read the script first.

Core Features

1. 26 sub-skills

   • 22 core skills, 1 orchestrator, 1 framework integration (FLOW), and 2 extension mirrors

2. 19 specialist agents

   • For example seo-technical, seo-content, seo-schema, seo-geo, seo-agentic, seo-drift, running on Sonnet or Opus depending on how much judgment the task needs

3. Parallel audits

   • A full audit can run up to 17 agents at once

4. Business-type awareness

   • It first decides whether the site is SaaS, local, e-commerce, publisher, or agency, then picks the agents

5. Agent readiness (Agentic)

   • Lighthouse Agentic Browsing, llms.txt, Markdown output, WebMCP

6. Reports as files

   • Markdown and JSON, plus PDF via /seo google report

7. Optional extensions

   • SE Ranking, Profound, Bing Webmaster (with IndexNow), Unlighthouse, Banana image generation; everything works without them

8. Runs on your machine

   • Reports stay local, but page content still goes to Claude (see Limitations)

Comparison

The time and price figures come from the README, which labels them typical market prices for illustration.

Why it's worth a look

• It shows the full pattern for turning a professional process into Skills plus Agents
• Its AI search coverage is ahead of most traditional tools
• It takes security seriously: SSRF protection, an isolated runtime, and no ad hoc pip install

Deep Dive

Layout and Components

The repo has about 25 top-level entries. The main ones:

The diagram in docs/ARCHITECTURE.md boils down to this: the seo orchestrator skill sits in the middle, surrounded by sub-skills such as seo-audit, seo-technical, seo-content, seo-schema, seo-geo, and seo-local, while the matching specialists in agents/ do the work.

How One /seo audit Is Orchestrated

The orchestrator skills/seo/SKILL.md writes the flow as ordered steps. The key logic:

1. Detect business type (SaaS / local / e-commerce / publisher / agency / other)
2. Spawn in parallel: seo-technical, seo-content, seo-schema, seo-sitemap,
                      seo-performance, seo-visual, seo-geo, seo-agentic
3. Conditional spawns:
   - Google API credentials found  -> seo-google
   - Local business                -> seo-local (plus seo-maps if DataForSEO MCP is available)
   - Content strategy signals      -> seo-cluster
   - E-commerce                    -> seo-ecommerce
   - Drift baseline exists         -> seo-drift
   - Always                        -> seo-backlinks, seo-sxo
4. Aggregate into an SEO Health Score (0-100)
5. Synthesize with a 10-principle framework: PERCEIVE -> ANALYZE -> VALIDATE -> ACT
6. Emit an action plan with dependency ordering and falsifiability, then offer a PDF

Two design choices are worth borrowing:

• Conditional orchestration: it does not send the whole team every time. Signals such as credentials or a local business decide who joins, which saves tokens and cuts noise.
• A synthesis framework: ten principles in four phases (PERCEIVE: observe and listen; ANALYZE: think and connect; VALIDATE: feel and accept; ACT: create and grow). The audit must walk these before bucketing findings, instead of dumping raw check results. Each recommendation states what it rests on, what it depends on, and how you will know it worked.

How an Agent Is Written

Take agents/seo-technical.md. The definition is short but complete:

---
name: seo-technical
description: Technical SEO specialist. Analyzes crawlability, indexability, ...
model: sonnet
maxTurns: 45
tools: Read, Bash, Write, Glob, Grep
---

The body holds the task steps, Core Web Vitals thresholds (LCP ≤ 2.5s, INP ≤ 200ms, CLS ≤ 0.1), nine check categories, the output format, and two practical conventions:

1. A persistence contract: when the orchestrator supplies output_dir, the agent writes a partial findings file after the first pass and overwrites it with the complete version before finishing. If maxTurns cuts it off, finished work is not lost.
2. A security rule: content returned by render_page.py is treated as untrusted external data. The agent extracts structured data only and never follows directives embedded in a page. This is a direct defense against prompt injection.

The agent also spells out the timeline of INP replacing FID and insists that FID never appear in output, a typical way to correct a model's outdated knowledge with a rules file.

Runtime Isolation

The top of SKILL.md requires every script to run through one entry point:

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run <script.py>

and says never to call scripts with a bare Python interpreter. Only /seo setup builds the isolated environment. If a dependency is missing, the agent should tell the user to run setup and must not improvise a pip install. The output of /seo doctor --json deliberately omits absolute paths and environment values. These rules keep environment pollution and information leakage to a minimum when an agent runs scripts.

SSRF Protection

An SEO tool has to make requests to user-supplied URLs, which is exactly where SSRF happens. The docstring of scripts/url_safety.py declares that every script in the repository that takes a user URL must validate it through this module. It provides:

• validate_url: rejects non-http(s) schemes, missing hostnames, localhost and cloud metadata addresses, and private, loopback, or reserved IP literals
• validate_url_strict: resolves DNS, validates every A record, and returns a pinned IP to defeat DNS rebinding
• safe_requests_get / head / session: send requests inside a DNS-pinning context, keeping the original hostname in the Host header and TLS SNI
• CLAUDE_SEO_LOCAL_TARGETS: an explicit allowlist for auditing a local dev server or a machine reached over Tailscale. It applies only to the top-level URL, never to redirect targets or subresources, and cloud metadata endpoints are refused even if listed

Anyone building an agent tool that touches the network can learn from this.

Hook: Validate on Write

hooks/hooks.json contains one PostToolUse hook matching Edit|Write. It calls hooks/validate-schema.py on the file just written, with a 30-second timeout. In practice, when Claude generates or edits a file containing schema markup, the structured data is validated right away instead of after deployment.

GEO and Agentic: Two Checks for AI

• /seo geo: rates how citable a page is, whether AI crawlers can reach it, and the brand's presence on Wikipedia, Reddit, YouTube, and LinkedIn. The README's stance is that Google calls AI search optimization still SEO, so get indexed, fast, and clear first, then work on GEO.
• /seo agentic: checks whether AI agents can use your site, covering the Lighthouse Agentic Browsing score, the accessibility tree, llms.txt, Markdown output, and WebMCP. Modes include audit | fix | lighthouse | refresh.

Limitations and Caveats

1. Limited accuracy without Google credentials: per the README, without API keys Core Web Vitals are lab estimates and indexing is inferred. Connect PageSpeed, CrUX, Search Console, and GA4 with /seo google setup.
2. Data goes to Claude: page content and analysis are sent to Anthropic's model like any other Claude Code work. "Runs locally" means reports and keys stay on your machine, not that content never leaves it.
3. Cost: five agents that need more judgment use Opus and the rest use Sonnet, so a full audit uses more of your plan than a single-page check. You can change models in agents/.
4. Pages that load content only after scrolling or clicking can give noisy results.
5. Two versions: the public MIT version is free, while the AI Marketing Hub Pro paid community gets a private version with earlier features. That is the project's commercial path; know it before you commit.
6. Figures such as 10.8K Search Console clicks and a 99 mobile PageSpeed score for the project's own site come from the README and are unverified by me.

Links and Resources

Official Resources

• 🌟 GitHub: https://github.com/AgriciDaniel/claude-seo
• 🌐 Website: https://claude-seo.md
• 📚 Docs: the repo's docs/ directory (INSTALLATION, COMMANDS, ARCHITECTURE, TROUBLESHOOTING, MCP-INTEGRATION)
• 🐛 Issue Tracker: https://github.com/AgriciDaniel/claude-seo/issues
• 🎬 Demo video: linked from the README on YouTube

Related Resources

• Claude Blog: https://github.com/AgriciDaniel/claude-blog (writes posts from SEO findings)
• Claude Banana: https://github.com/AgriciDaniel/banana-claude (images for SEO)
• FLOW: https://github.com/AgriciDaniel/flow (an SEO framework with 42 AI prompts)

Summary and Outlook

Key Takeaways

1. A consultant's process as a plugin: 26 sub-skills and 19 agents turn an SEO checklist into engineering.
2. A plan, not warnings: ranked by impact, with each recommendation stating its basis and how to verify it.
3. Built for AI search: the GEO and Agentic checks set it apart from traditional tools.
4. Solid engineering details: an isolated runtime, SSRF protection, an untrusted-content rule, and a validate-on-write hook.
5. Keep a level head: crawl scale and backlink data trail dedicated tools, page content is sent to the model, and there is a paid community tier.

Who It's For

• Indie developers and site owners who want a quick checkup without another subscription
• SEO agencies and freelancers who need audit results on the first call
• Developers who want to learn how to build a large Claude Code plugin (skill orchestration, agent constraints, script safety)

Suggested Path

Run /seo doctor to confirm the environment, then run /seo page on your own site and check a few conclusions against the evidence in the report. To study the implementation, read in this order: skills/seo/SKILL.md (orchestration), agents/seo-technical.md (how an agent is written), scripts/url_safety.py (security design), and docs/ARCHITECTURE.md (overall structure).

About sources: I read the README, plugin.json, the orchestrator SKILL.md, the seo-technical agent, hooks.json, docs/ARCHITECTURE.md, and the opening of url_safety.py. For the other agents and scripts I only saw the file list, so check the repo for details.

Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.

Find more useful knowledge and interesting products on my Homepage