AI & Development
A step-by-step guide to building a real SEO agent using Claude - what it should know, what tools it needs, how to separate editorial from technical SEO,
Most AI SEO tools are wrappers around keyword research APIs with a language model bolted on for content suggestions. Building an SEO agent with Claude from scratch is a different approach - one that produces a system deeply integrated with your specific website, your content pipeline, and the 2026 SEO landscape as it actually works. Here is the architecture and the reasoning behind it.
The most important architectural decision in an SEO agent system is separating editorial SEO from technical SEO. These are different kinds of expertise that produce different kinds of outputs, and conflating them into a single agent produces an agent that does both poorly.
The editorial SEO agent handles content strategy: E-E-A-T compliance, topic cluster architecture, search intent analysis, content differentiation, GEO optimization for AI citability, and quality audits against editorial standards. It reads content and makes recommendations. It does not touch code or configuration files.
The technical SEO agent handles implementation: meta tags, JSON-LD structured data, sitemap.xml updates, canonical tags, hreflang, Core Web Vitals monitoring, and robots.txt verification. It modifies files and runs validation checks. It does not rewrite editorial content.
The reason for this separation is specialization. An agent that tries to write beautiful editorial content while simultaneously maintaining technically correct JSON-LD schema will be mediocre at both. Two agents, each specialized and each restricted to its domain, produce better output than one generalist agent trying to cover the full scope.
The editorial SEO agent's system prompt must encode the current state of SEO - not the SEO from a training dataset that may be years old, but the landscape as it works today. In 2026, that means:
Google's intent-first ranking model. The agent must understand that Google ranks pages based on whether they comprehensively answer the search intent behind a query - not based on keyword density, meta keyword tags, or any of the older optimization signals. A page with low keyword frequency that answers a question completely will outrank a page that repeats the keyword twenty times without answering the question.
The E-E-A-T framework. Experience, Expertise, Authoritativeness, Trustworthiness - the four dimensions Google's quality raters use to evaluate content. The agent needs specific, actionable criteria for each dimension: what makes a piece of content demonstrate first-hand experience (specific metrics, named observations, design decisions only an insider could describe), what makes it authoritative (external citations, named author with verifiable credentials, referenced data sources).
GEO - Generative Engine Optimization. How to write content that gets cited in ChatGPT, Gemini, Perplexity, and Google AI Overviews. This requires short autonomous paragraphs (1 to 3 sentences, each making sense standalone), affirmative factual statements (not hedged possibilities), explicit entity definitions, and intermediate summaries after major sections. GEO optimization and traditional SEO optimization are compatible but require slightly different structural choices.
Topic cluster architecture. The modern SEO structure that outperforms individual page optimization: a pillar page covering the broad topic, surrounded by 10 to 15 cluster articles covering specific subtopics, with bidirectional internal linking between the pillar and all cluster articles. The agent must understand which cluster an article belongs to and what links it must include.
The editorial SEO agent needs: Read (to review content files), Bash (for word counts, character counts, grep searches of the content directory), and optionally WebSearch and WebFetch (to check the current SERP for a target keyword and understand what format is winning).
It should not have Write or Edit access. The editorial SEO agent makes recommendations; it does not implement them. This keeps it in the advisor role and prevents it from modifying content without the content author's review.
The technical SEO agent needs: Read (to review current implementation), Edit and Write (to update files), and Bash (to run validation commands). It should have a specific list of files it is authorized to modify - typically src/components/SEO/, public/sitemap.xml, public/robots.txt, and component files where meta tags are added.
It should not have access to content files (those belong to the editorial agent's domain) or deployment commands (those belong to a deployment skill). Tight tool scoping prevents the technical SEO agent from inadvertently modifying content or triggering deploys when all it was asked to do was update sitemap.xml.
The hardest part of a two-agent SEO system is the handoff. After the editorial agent reviews a piece of content, what information does it pass to the technical agent, and how?
The most reliable approach is a structured handoff block - a specific format that the editorial agent always produces at the end of its review, which the technical agent reads and acts on. The block specifies: the post slug, the publication date, the SEO metadata (title, description, canonical URL), the structured data needed (Article schema, FAQPage if applicable, HowTo if applicable), and the sitemap.xml update required.
When the handoff format is explicit and consistent, the technical agent can execute reliably without requiring the editorial agent to also know how to write code. When the handoff is implicit or inconsistent, the technical agent must interpret ambiguous instructions - and interpretation introduces errors.
An SEO agent without quality gates will produce output that passes a superficial review but fails on measurement. Encode these checks as mandatory steps:
echo -n "title" | wc -c)These checks should be automated where possible - a Bash command to count characters is faster and more reliable than asking the model to count characters in its head.
An SEO agent can enforce standards, apply known best practices, and catch obvious errors. It cannot replace the strategic judgment of understanding which topics to pursue, which keywords your site can realistically rank for given your current domain authority, or how to differentiate your content from the competition in ways that require genuine insight into your product and your users.
The SEO agent is a capable enforcer of defined standards. The strategy behind those standards - what to write, who to write for, what angle to take - is a human judgment that no agent should be expected to make autonomously.