Claude SEO Architecture: 3-Layer Skill and Agent Design

Claude SEO follows Anthropic’s Agent Skills standard with a modular, three-layer architecture. The directive layer (SKILL.md frontmatter) describes capability and activation keywords. The orchestration layer (the seo/ orchestrator) handles industry detection, parallel subagent dispatch, and synthesis. The execution layer consists of 25 sub-skills and 18 specialist agents that each perform focused analysis before handing results back to the orchestrator for scoring and action-plan generation.

Directory Structure

Skills are auto-discovered from any directory matching skills/seo-*/ and agents from any file matching agents/seo-*.md. Adding a new skill or agent is as simple as creating the file in the correct location — no registration step is required.

~/.claude/plugins/.../claude-seo/
├── skills/
│   ├── seo/                        # Main orchestrator
│   │   ├── SKILL.md
│   │   └── references/             # On-demand reference files (12 files)
│   │       ├── cwv-thresholds.md
│   │       ├── schema-types.md
│   │       ├── eeat-framework.md
│   │       ├── quality-gates.md
│   │       ├── local-seo-signals.md
│   │       ├── local-schema-types.md
│   │       ├── maps-geo-grid.md
│   │       ├── maps-gbp-checklist.md
│   │       ├── maps-api-endpoints.md
│   │       ├── maps-free-apis.md
│   │       ├── thinking-framework.md
│   │       └── scoring-weights.md
│   │
│   ├── seo-audit/                  # Full site audit (parallel subagents)
│   ├── seo-page/                   # Single page analysis
│   ├── seo-technical/              # Technical SEO (9 categories)
│   ├── seo-content/                # E-E-A-T and content quality
│   ├── seo-content-brief/          # Competitive content brief generation
│   ├── seo-schema/                 # Schema markup detection and generation
│   ├── seo-sitemap/                # XML sitemap analysis and generation
│   ├── seo-images/                 # Image optimization analysis
│   ├── seo-geo/                    # AI search optimization (GEO)
│   ├── seo-local/                  # Local SEO (GBP, citations, reviews)
│   ├── seo-maps/                   # Maps intelligence (geo-grid, GBP audit)
│   ├── seo-backlinks/              # Backlink profile analysis
│   ├── seo-cluster/                # Semantic topic clustering (SERP-based)
│   ├── seo-sxo/                    # Search Experience Optimization
│   ├── seo-drift/                  # SEO drift monitoring (baselines)
│   ├── seo-ecommerce/              # E-commerce SEO (product schema, marketplaces)
│   ├── seo-hreflang/               # International SEO and hreflang
│   ├── seo-plan/                   # Strategic SEO planning (industry templates)
│   ├── seo-programmatic/           # Programmatic SEO at scale
│   ├── seo-competitor-pages/       # Competitor comparison page generation
│   ├── seo-google/                 # Google SEO APIs (GSC, PSI, CrUX, GA4)
│   ├── seo-flow/                   # FLOW framework integration (CC BY 4.0)
│   ├── seo-dataforseo/             # DataForSEO MCP mirror (extension surface)
│   └── seo-image-gen/              # Banana MCP mirror (extension surface)
│
├── agents/
│   ├── seo-technical.md            # Crawlability, indexability, security
│   ├── seo-content.md              # E-E-A-T, readability, thin content
│   ├── seo-schema.md               # Structured data validation
│   ├── seo-sitemap.md              # Sitemap quality gates
│   ├── seo-performance.md          # Core Web Vitals
│   ├── seo-visual.md               # Screenshots, mobile rendering
│   ├── seo-geo.md                  # AI crawler access, citability
│   ├── seo-local.md                # GBP signals, NAP, reviews
│   ├── seo-maps.md                 # Geo-grid, competitor radius mapping
│   ├── seo-backlinks.md            # Moz, Bing Webmaster, Common Crawl
│   ├── seo-cluster.md              # Semantic clustering analysis
│   ├── seo-sxo.md                  # Page-type, user stories, personas
│   ├── seo-drift.md                # Baseline comparison, regression detection
│   ├── seo-ecommerce.md            # Product schema, marketplace intelligence
│   ├── seo-google.md               # GSC, PSI, CrUX, GA4 analyst
│   ├── seo-flow.md                 # FLOW framework prompt selection
│   ├── seo-dataforseo.md           # DataForSEO MCP mirror
│   └── seo-image-gen.md            # Banana MCP mirror
│
├── scripts/                        # Python execution scripts (50 tracked)
│   ├── render_page.py              # Shared headless renderer (SPA-aware)
│   ├── url_safety.py               # Canonical SSRF + DNS-rebinding module
│   ├── fetch_page.py               # Page fetcher with UA rotation
│   ├── parse_html.py               # HTML parser for SEO elements
│   └── ...                         # 46 additional scripts
│
└── extensions/                     # Opt-in MCP add-ons
    ├── dataforseo/
    ├── banana/
    └── firecrawl/

The Three Layers

Layer 1 — Directive (SKILL.md Frontmatter)

Every skill is a Markdown file with YAML frontmatter. The frontmatter tells Claude Code when to activate the skill, what arguments to expect, and metadata like version and license. The orchestrator’s frontmatter covers the full activation surface so a single /seo invocation routes correctly to any sub-skill.

---
name: seo
description: >
  Comprehensive SEO analysis for any website or business type.
  Full site audits, single-page analysis, technical SEO (crawlability,
  indexability, Core Web Vitals with INP), schema markup, content quality
  (E-E-A-T), image optimization, sitemap analysis, and GEO for AI
  Overviews/ChatGPT/Perplexity. Industry detection for SaaS, e-commerce,
  local, publishers, agencies.
user-invocable: true
argument-hint: "[command] [url]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.2.0"
  category: seo
---

Layer 2 — Orchestration (`skills/seo/SKILL.md`)

The orchestrator is the brain of the system. It runs industry detection from homepage signals, decides which agents to spawn, dispatches them in parallel (up to 15 simultaneously), collects their results, and synthesizes findings through the 10-principle framework before emitting the prioritized action plan. Industry detection signals:

Type	Signals
SaaS	Pricing page, `/features`, `/integrations`, `/docs`, “free trial”, “sign up”
Local Service	Phone number, address, service area, “serving [city]”, Google Maps embed
E-commerce	`/products`, `/collections`, `/cart`, “add to cart”, product schema
Publisher	`/blog`, `/articles`, `/topics`, article schema, author pages, publication dates
Agency	`/case-studies`, `/portfolio`, `/industries`, “our work”, client logos

Layer 3 — Execution (Specialist Skills + Agents)

Each specialist skill and agent performs focused work: one reads schema, another measures Core Web Vitals, another checks NAP consistency for local businesses. Agents declare their own tool access in YAML frontmatter and run with isolated context so parallel execution is safe.

---
name: seo-technical
description: Crawlability, indexability, and security audit agent.
tools: Read, Bash, Write, Glob, Grep
---

Instructions for the agent...

Audit Execution Flow

User invokes /seo audit

The orchestrator receives the URL and loads the main skills/seo/SKILL.md. No reference files are loaded at startup — they are pulled on demand to keep context lean.

Industry detection

The orchestrator fetches the homepage and matches signals against five industry templates (SaaS, local, ecommerce, publisher, agency). Ambiguous detections present the top two candidates and ask the user to confirm.

Core agent dispatch

Seven agents always spawn in parallel: seo-technical, seo-content, seo-schema, seo-sitemap, seo-performance, seo-visual, and seo-geo.

Conditional agent dispatch

Additional agents spawn based on detected signals: seo-google when Google API credentials exist, seo-local when a local business is detected, seo-maps when local + DataForSEO MCP is available, seo-backlinks when Moz/Bing API keys or Common Crawl metrics are available, seo-cluster when content-strategy signals appear, seo-ecommerce when e-commerce is detected, and seo-drift when a baseline snapshot exists for the URL. seo-sxo is always included in full audits.

Result aggregation

The orchestrator collects all agent outputs and walks the 10-principle PERCEIVE → ANALYZE → VALIDATE → ACT framework before bucketing findings into Critical / High / Medium / Low.

Scoring and action plan

A weighted SEO Health Score (0–100) is computed across seven categories. The final action plan lists each finding with its first-principle observation, dependency relationships, falsifiability check, and a leading indicator the user can monitor without re-running the audit.

Parallel Dispatch Diagram

User: /seo audit https://example.com
          │
          ▼
    ┌─────────────┐
    │  Orchestrator│  skills/seo/SKILL.md
    └──────┬──────┘
           │  Industry detection → spawn in parallel
           │
   ┌───────┼───────┬───────┬───────┬───────┬───────┐
   ▼       ▼       ▼       ▼       ▼       ▼       ▼
 tech  content  schema  sitemap  perf  visual   geo
           │
           │  Conditional spawns:
           ├─ seo-google    (Google API creds detected)
           ├─ seo-local     (local business detected)
           ├─ seo-maps      (local + DataForSEO MCP)
           ├─ seo-backlinks (Moz / Bing / Common Crawl)
           ├─ seo-cluster   (content strategy signals)
           ├─ seo-sxo       (always in full audits)
           ├─ seo-drift     (baseline exists for URL)
           └─ seo-ecommerce (e-commerce detected)
                  │
                  ▼
         ┌─────────────────┐
         │ Aggregate Results│
         └────────┬─────────┘
                  ▼
         ┌─────────────────┐
         │  Health Score   │
         │  + Action Plan  │
         └─────────────────┘

Reference Files

The skills/seo/references/ directory holds 12 on-demand knowledge files. The orchestrator does not load all of them at startup — each is pulled only when a skill genuinely needs it. This keeps the working context small and avoids token bloat.

File	Purpose
`cwv-thresholds.md`	Current Core Web Vitals thresholds and INP measurement details
`schema-types.md`	All supported Schema.org types with deprecation status
`eeat-framework.md`	E-E-A-T evaluation criteria (Sept 2025 QRG update)
`quality-gates.md`	Content length minimums, uniqueness thresholds by page type
`local-seo-signals.md`	Local ranking factors, review benchmarks, citation tiers, GBP status
`local-schema-types.md`	LocalBusiness subtypes and industry-specific citation sources
`maps-geo-grid.md`	Geo-grid methodology and rank-tracking parameters
`maps-gbp-checklist.md`	GBP completeness checklist
`maps-api-endpoints.md`	Maps API endpoint reference
`maps-free-apis.md`	Free maps data sources
`thinking-framework.md`	Full 10-principle methodology with per-principle SEO mappings
`scoring-weights.md`	Health score category weights and priority thresholds

Scripts Directory

The scripts/ directory holds over 50 tracked Python execution scripts. The most architecturally significant are:

render_page.py — shared headless renderer backed by Playwright Chromium. All fetching subagents call it with --mode auto so SPA sites (React, Next.js, Vue, Nuxt, Svelte, Astro islands) are audited correctly. Content extraction uses trafilatura; publication dates use htmldate.
url_safety.py — canonical SSRF and DNS-rebinding protection module. Every script that accepts a user URL routes through it before making any network call.
fetch_page.py — raw page fetcher with user-agent rotation, used when rendering is not needed.
parse_html.py — extracts SEO-relevant elements (title, meta, headings, canonical, hreflang, schema blocks) from HTML.
google_auth.py — manages the 4-tier Google credential system (API key → OAuth/SA → GA4 → Ads).

SEO Health Score Weights

Technical SEO      22%
Content Quality    23%
On-Page SEO        20%
Schema / Structured Data  10%
Performance (CWV)  10%
AI Search Readiness 10%
Images              5%

Extensions

Extensions are opt-in add-ons that install MCP servers and their corresponding skill/agent mirrors into the plugin directory. They ship self-contained in extensions/<name>/ with their own install.sh / install.ps1 and uninstall.sh / uninstall.ps1.

Extension	Package (pinned)	What it adds
DataForSEO	`dataforseo-mcp-server@2.8.10`	Live SERP data, keyword research, backlinks, on-page analysis, AI visibility, LLM mention tracking
Banana Image Gen	`@ycse/nanobanana-mcp@1.1.1`	AI image generation for SEO assets via Gemini (OG images, hero images, product photos, infographics)
Firecrawl	`firecrawl-mcp@3.11.0`	Full-site crawling and URL discovery for audits
Ahrefs	`@ahrefs/mcp`	Official Ahrefs backlink and organic data
SE Ranking	—	AI Share-of-Voice across ChatGPT / Gemini / Perplexity / AI Overviews / AI Mode
Profound	—	Time-series LLM citation tracker
Bing Webmaster	—	Bing Webmaster Tools plus IndexNow unified
Unlighthouse	—	MIT multi-page Lighthouse runner

Extending Claude SEO

Adding a Custom Sub-Skill

Create skills/seo-newskill/SKILL.md with YAML frontmatter (name, description).
Write the skill instructions in Markdown below the frontmatter.
Update skills/seo/SKILL.md to route the new command (add a row to the Quick Reference table and an entry to the Orchestration Logic).
Optionally add a reference file to skills/seo-newskill/references/ for static data loaded on-demand.

Adding a Custom Subagent

Create agents/seo-newagent.md with YAML frontmatter (name, description, tools: Read, Bash, Write, Glob, Grep).
Write the agent instructions.
Reference the agent from the relevant skill’s spawn list.

File Naming Conventions

Type	Pattern	Example
Skill	`seo-{name}/SKILL.md`	`seo-audit/SKILL.md`
Agent	`seo-{name}.md`	`seo-technical.md`
Reference	`{topic}.md`	`cwv-thresholds.md`
Script	`{action}_{target}.py`	`fetch_page.py`
Template	`{industry}.md`	`saas.md`

Get Started

Core Commands

Specialized Commands

Extensions

Reference

Claude SEO Architecture: 3-Layer Skill and Agent Design

Directory Structure

The Three Layers

Layer 1 — Directive (SKILL.md Frontmatter)

Layer 2 — Orchestration (`skills/seo/SKILL.md`)

Layer 3 — Execution (Specialist Skills + Agents)

Audit Execution Flow

Parallel Dispatch Diagram

Reference Files

Scripts Directory

SEO Health Score Weights

Extensions

Extending Claude SEO

Adding a Custom Sub-Skill

Adding a Custom Subagent

File Naming Conventions

Build docs developers (and LLMs) love

Get Started

Core Commands

Specialized Commands

Extensions

Reference

Documentation Index

​Directory Structure

​The Three Layers

​Layer 1 — Directive (SKILL.md Frontmatter)

​Layer 2 — Orchestration (skills/seo/SKILL.md)

​Layer 3 — Execution (Specialist Skills + Agents)

​Audit Execution Flow

​Parallel Dispatch Diagram

​Reference Files

​Scripts Directory

​SEO Health Score Weights

​Extensions

​Extending Claude SEO

​Adding a Custom Sub-Skill

​Adding a Custom Subagent

​File Naming Conventions

Build docs developers (and LLMs) love

Directory Structure

The Three Layers

Layer 1 — Directive (SKILL.md Frontmatter)

Layer 2 — Orchestration (`skills/seo/SKILL.md`)

Layer 3 — Execution (Specialist Skills + Agents)

Audit Execution Flow

Parallel Dispatch Diagram

Reference Files

Scripts Directory

SEO Health Score Weights

Extensions

Extending Claude SEO

Adding a Custom Sub-Skill

Adding a Custom Subagent

File Naming Conventions