Claude SEO runs 19 specialist agents across 26 sub-skills to audit websites for technical SEO, schema markup, Core Web Vitals, E-E-A-T signals, and AI search readiness. The architecture has no central orchestrator. Instead, agents coordinate through a flat skill composition pattern where each sub-skill wraps one or more agents and exposes a uniform interface to Claude Code's skill system.
This design choice surfaces interesting trade-offs. You get simpler failure modes (no single point of coordination failure), easier agent reuse (skills compose without routing logic), and clearer boundaries (each agent owns a domain). You lose explicit dependency graphs, centralized state management, and the ability to optimize cross-agent workflows.
The system defines 26 sub-skills that wrap 19 specialist agents:
Each skill exposes a standard interface:
class SEOSkill:
def analyze(self, url: str, context: AuditContext) -> SkillResult:
"""Run analysis, return structured findings."""
pass
def get_dependencies(self) -> list[str]:
"""Declare which other skills must run first."""
pass
def merge_context(self, result: SkillResult, context: AuditContext):
"""Write findings back to shared context."""
pass
Claude Code invokes skills in dependency order. A skill that needs crawl data declares a dependency on the crawl skill. The skill system resolves the graph and runs crawl first, then passes the enriched context to dependent skills.
Traditional multi-agent systems use a central orchestrator to route tasks, manage state, and handle failures. Claude SEO skips this layer. Coordination happens through three mechanisms:
1. Dependency declarations
Skills declare dependencies explicitly. The schema validation skill depends on the crawl skill (needs HTML) and the render skill (needs JavaScript-rendered DOM). The skill system builds a directed acyclic graph and executes in topological order.
2. Shared context object
All skills read from and write to a single AuditContext object. The crawl skill writes page HTML, status codes, and redirect chains. The schema skill reads HTML and writes structured data findings. The E-E-A-T skill reads both and writes authority signals.
This is a shared-memory model. No message passing, no event bus, no coordination primitives. Skills trust the context object to be consistent.
3. Skill result merging
Each skill returns a SkillResult with findings, warnings, and recommendations. The skill system merges results into the final audit report. No skill sees another skill's output during execution (only through the shared context).
The shared context model creates predictable failure modes:
Missing dependencies: If skill A depends on skill B but B fails, A receives incomplete context. The skill system catches this at graph-build time (missing dependency) or runtime (null context fields). The audit continues with warnings.
Context pollution: If skill A writes malformed data to context, skill B may crash or produce garbage output. No schema validation on context writes. The skill system logs exceptions but doesn't roll back context state.
Concurrent access: Skills run sequentially (no parallelism). This avoids race conditions but makes audits slower. A full audit takes 10-15 minutes for a medium site.
Partial failures: If the crawl skill fetches 80% of pages before hitting rate limits, dependent skills see incomplete data. No retry logic, no partial result handling. The audit completes with gaps.
The 26 sub-skills layer on top of 19 agents through composition:
| Skill | Agent(s) | Composition Type |
|---|---|---|
| Technical SEO | Crawl + Robots + Sitemap | Sequential pipeline |
| Core Web Vitals | Lighthouse + Render | Parallel then merge |
| Schema validation | JSON-LD parser + Validator | Sequential with fallback |
| E-E-A-T analysis | Author + Citation + Expertise | Parallel aggregation |
| AI search readiness | llms.txt + WebMCP + Agentic Browsing | Independent checks |
This pattern lets you reuse agents across skills. The crawl agent appears in technical SEO, schema validation, and E-E-A-T skills. The Lighthouse agent appears in Core Web Vitals and performance skills.
Composition types:
The base system runs offline analysis (crawl, parse, validate). Nine optional extensions add live SEO data:
Extensions follow the same skill interface. They declare dependencies (e.g., Search Console skill depends on crawl skill for URL list) and write to shared context.
This creates a second failure mode: API rate limits. If the Search Console extension hits quota limits mid-audit, dependent skills see partial data. No backoff, no queue, no retry. The audit completes with warnings.
The final audit report renders as PDF or Excel using Google Docs and Sheets APIs. The skill system:
This is a synchronous blocking operation. If the Google API is slow or rate-limited, the entire audit stalls. No async rendering, no background jobs.
Claude SEO's flat agent hierarchy works because:
Task boundaries are clear: Each agent owns a well-defined SEO domain. No ambiguity about which agent handles schema validation vs. crawl analysis.
Dependencies are static: The dependency graph doesn't change per audit. Crawl always runs before schema validation. No dynamic routing needed.
Failures are local: If the backlink agent fails, the rest of the audit completes. No cascading failures (except for hard dependencies like crawl).
State is append-only: Skills write findings to context but don't modify existing data. No coordination needed to prevent conflicts.
Execution is sequential: No parallelism means no race conditions, no distributed state, no consensus protocols.
This pattern breaks down when:
from dataclasses import dataclass
from typing import Optional
@dataclass
class AuditContext:
url: str
html: Optional[str] = None
status_code: Optional[int] = None
redirects: list[str] = None
structured_data: Optional[dict] = None
core_web_vitals: Optional[dict] = None
class CrawlSkill:
def get_dependencies(self) -> list[str]:
return [] # No dependencies
def analyze(self, url: str, context: AuditContext) -> dict:
response = self._fetch_with_redirects(url)
context.html = response.text
context.status_code = response.status_code
context.redirects = response.history
return {
"status": "success",
"findings": {
"crawlable": response.status_code == 200,
"redirect_chain_length": len(response.history),
"html_size_kb": len(response.text) / 1024
}
}
class SchemaSkill:
def get_dependencies(self) -> list[str]:
return ["crawl"] # Needs HTML from crawl skill
def analyze(self, url: str, context: AuditContext) -> dict:
if not context.html:
return {"status": "error", "message": "No HTML available"}
structured_data = self._extract_jsonld(context.html)
validation_errors = self._validate_schema(structured_data)
context.structured_data = structured_data
return {
"status": "success",
"findings": {
"schema_types": list(structured_data.keys()),
"validation_errors": validation_errors,
"rich_snippet_eligible": len(validation_errors) == 0
}
}
Use Claude SEO's flat agent pattern when:
Avoid this pattern when:
The flat hierarchy trades orchestrator complexity for simpler agent interfaces and clearer failure modes. It works when your domain naturally decomposes into independent specialists. It breaks when coordination becomes the hard problem.