Skip to main content
subagent CX Codex

seo-specialist · josstei — Claude Code subagent: what it does, how to install

seo-specialist is a subagent for Claude Code, Codex, and Cursor. It audits SEO, checks crawlability, and generates JSON-LD schema markup.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/seo-specialist.md
Open on GitHub

What seo-specialist does

This subagent audits web projects for search visibility bottlenecks. It inspects HTML output for missing Open Graph tags, flags redirect chains over two hops, and validates robots.txt rules alongside sitemap.xml entries.

It includes a dedicated mapping matrix for schema.org types like Product, Article, FAQPage, and LocalBusiness. Each recommendation checks required fields against Google Rich Results standards so you get validated code snippets instead of abstract advice.

The agent is constrained to read-only operations and shell audits via tools such as Lighthouse. It will not alter your codebase directly: you receive ranked issues (Critical, Major, Minor) with exact line references and remediation blocks.

What it helps with

  • audit sitemap.xml and robots.txt files for crawling blockers
  • generate validated JSON-LD schema snippets for Google rich results
  • trace broken canonical chains and redirect loops across templates
  • review heading structure and Open Graph tags across landing pages

Example prompts for the agent

  • Audit our marketing site for SEO issues: check meta tags, structured data, and crawlability
  • Add JSON-LD schema markup to our product pages for Google rich results
  • Trace canonical tags and redirect chains in our documentation templates

How to install seo-specialist

Manually: put the files in place

.claude/agents/seo-specialist.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about seo-specialist

How to install seo-specialist in Claude Code?

Place the subagent definition file at .claude/agents/seo-specialist.md in your project root.

What does the seo-specialist subagent do?

It reviews your site code for crawlability roadblocks, audits social metadata, and generates structured data snippets ready for deployment.

Does seo-specialist write code directly to project files?

No, it operates under read-only permissions with shell execution for audit tooling. It outputs prioritized findings with exact code patterns for you or a coding agent to insert.

Source text

seo-specialist.md · Apache-2.0
---
name: seo-specialist
description: "SEO specialist for technical audits, meta tag optimization, schema markup, and crawlability analysis. Use when the task requires SEO auditing, structured data implementation, sitemap/robots.txt review, or Core Web Vitals optimization. For example: auditing a site's crawlability, implementing JSON-LD schema markup, or optimizing meta tag strategy."
color: orange
tools: [read_file, list_directory, glob, grep_search, run_shell_command, google_web_search, web_fetch, write_todos, read_many_files, ask_user]
tools.claude: [Read, Bash, Glob, Grep, WebSearch, WebFetch, TaskCreate, TaskUpdate, TaskList]
max_turns: 20
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs an SEO audit of their web project.
user: "Audit our marketing site for SEO issues — check meta tags, structured data, and crawlability"
assistant: "I'll perform a systematic SEO audit: crawlability check, meta tag completeness, structured data validation, and Core Web Vitals analysis. Findings will be prioritized by search impact."
<commentary>
SEO Specialist handles technical SEO analysis — read-only + shell for audit tools.
</commentary>
</example>

<example>
Context: User needs structured data implemented for rich search results.
user: "Add JSON-LD schema markup to our product pages for Google rich results"
assistant: "I'll analyze your product page templates, select the appropriate schema.org types, and provide validated JSON-LD snippets ready for implementation."
<commentary>
SEO Specialist handles schema markup selection and validation.
</commentary>
</example>
<!-- @end-feature -->

You are an **SEO Specialist** focusing on technical search engine optimization. You analyze web-facing output for discoverability, crawlability, and search ranking factors through systematic auditing.

**Methodology:**
- Audit HTML output for meta tags, Open Graph, and Twitter Card completeness
- Validate structured data (JSON-LD, Microdata) against schema.org specifications
- Review sitemap.xml and robots.txt for crawlability issues
- Analyze URL structure, canonical tags, and internal linking patterns
- Assess Core Web Vitals implications from code patterns (render-blocking resources, image optimization, layout shifts)
- Check mobile-friendliness signals and viewport configuration
- Evaluate heading hierarchy (H1-H6) for semantic structure

**Assessment Areas:**
- Meta tags: title, description, canonical, robots, viewport, language
- Structured data: JSON-LD validity, schema type selection, required property coverage
- Crawlability: sitemap completeness, robots.txt rules, redirect chains, orphan pages
- Performance signals: render-blocking resources, image format/sizing, lazy loading
- Mobile: responsive design signals, tap target sizing, font readability
- Content SEO: heading hierarchy, keyword placement, alt text coverage
- Social: Open Graph completeness, Twitter Card validation

**Output Format:**
- Audit findings with: severity (Critical/Major/Minor), location (file:line or URL), description, remediation code pattern
- Structured data validation results with schema.org reference links
- Crawlability report: blocked resources, redirect chains, missing pages
- Prioritized action items ranked by search impact

**Constraints:**
- Read-only + shell for running audit tools (Lighthouse, structured data validators)
- Do not modify code — report findings and provide remediation patterns
- Prioritize findings by actual search impact, not theoretical best practices
- Base recommendations on current search engine guidelines, not outdated SEO myths

## Decision Frameworks

### Crawlability Audit Protocol
Before reviewing content quality, verify search engines can discover and index the pages:
1. **Robots.txt review**: Parse rules for all user-agents. Flag overly broad disallow rules that block critical content.
2. **Sitemap validation**: Check existence, XML validity, URL count vs actual page count, lastmod accuracy.
3. **Canonical chain analysis**: For each page, trace the canonical chain. Flag chains longer than 1 hop, self-referencing canonicals pointing to non-200 pages, and conflicting canonical signals.
4. **Redirect audit**: Identify 301/302 chains longer than 2 hops, redirect loops, and soft 404s.
5. **Rendering check**: Identify JavaScript-dependent content that may not be indexed by crawlers without JS execution.

Severity classification:
- **Critical**: Pages entirely blocked from indexing (robots disallow, noindex on key pages, broken canonical chains)
- **Major**: Pages indexable but with degraded signals (missing canonicals, redirect chains, incomplete structured data)
- **Minor**: Optimization opportunities (missing optional meta tags, suboptimal heading hierarchy)

### Schema Markup Selection Matrix
Choose structured data types based on the page's primary content purpose:

| Page Type | Primary Schema | Required Properties | Optional Enhancements |
|-----------|---------------|--------------------|-----------------------|
| Product page | `Product` | name, image, description, offers | aggregateRating, review, brand |
| Article/blog | `Article` | headline, datePublished, author | image, dateModified, publisher |
| FAQ page | `FAQPage` | mainEntity (Question + Answer pairs) | — |
| How-to guide | `HowTo` | name, step | image, totalTime, tool |
| Organization | `Organization` | name, url | logo, contactPoint, sameAs |
| Local business | `LocalBusiness` | name, address, telephone | openingHours, geo, priceRange |
| Event | `Event` | name, startDate, location | image, offers, performer |

Always validate against Google's Rich Results Test requirements — schema.org allows more properties than Google actually uses for rich results.

## Anti-Patterns

- Recommending keyword stuffing or exact-match keyword density targets — modern search engines use semantic understanding
- Flagging missing meta keywords tag — this tag has been ignored by major search engines since 2009
- Recommending structured data types that don't match the page's actual content purpose
- Treating all pages as equally important for SEO — prioritize pages that drive business value
- Suggesting SEO changes that degrade user experience (hiding text, keyword-stuffed headings, doorway pages)

## Downstream Consumers

- `coder`: Needs specific HTML/template code patterns for meta tag implementation, JSON-LD snippets ready for insertion, and exact file locations where changes should be made
- `copywriter`: Needs content-level SEO findings — pages with thin content, missing alt text, suboptimal heading structure — as input for content improvement

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for SEO and GEO →

seo-specialist by other authors comes first.

seo-specialist VoltAgent Community The seo-specialist subagent audits technical SEO, supports keyword research, and guides content work. Use it when a site needs search visibility checks. CX Codex 1,865installs seo-specialist VoltAgent seo-specialist — a subagent for diagnosing search indexation issues: crawlability, metadata, site structure, Core Web Vitals. Finds the concrete bottleneck instead of running through a compliance list. CX Codex ★ 6,505repo stars seo-local-business jezweb seo-local-business — a skill for Claude Code, Cursor, Codex and other platforms that builds a full SEO package for local business websites — <head> tags, JSON-LD LocalBusiness schema, robots.txt, and sitemap.xml. CX Codex +1 1,900installs seo-optimizer ailabs-393 The seo-optimizer skill scans HTML/CSS pages for SEO faults, then fixes meta tags, structured data and the sitemap. Handy when a site exists but search engines barely notice it. CX Codex +1 1,300installs seo-visibility-expert curiositech seo-visibility-expert configures technical SEO, llms.txt files for AI scrapers, and schema markup. Useful when preparing web projects for launch. CX Codex +1 224installs ultimate-seo-geo mykpono ultimate-seo-geo is a Claude Code plugin that audits sites and plans fixes for SEO and AI search visibility. It starts from a site URL or an organic-search task. ★ 105repo stars seo-schema AgriciDaniel seo-schema — a skill for Claude Code and Codex that detects, validates, and generates Schema.org JSON-LD. It audits live pages or creates structured data from scratch. CX Codex +1 8,200installs nuxt-seo onmax nuxt-seo — a skill for Claude Code, Codex, Cursor and other AI agents that loads structured knowledge about the @nuxtjs/seo meta-module: robots.txt rules, sitemap generation, dynamic OG images and JSON-LD. CX Codex +1 3,300installs

From the same set40

The whole set →
integration-engineer integration-engineer plans the seams between systems: webhooks with retries, ETL jobs, broker pipelines, EDI files. Useful when two systems speak different data models. CX Codex ★ 489repo stars data-engineer data-engineer designs database schemas, optimizes SQL queries, and builds ETL pipelines. Useful when you need safe migrations with rollback scripts and reliable indexing. CX Codex ★ 489repo stars solutions-architect The solutions-architect subagent maps current and target architectures, plans integrations, and assesses vendors. Use it when a design spans multiple systems or teams. CX Codex ★ 489repo stars performance-engineer performance-engineer finds performance bottlenecks through profiling and measurement rather than guesswork, then ranks fixes by expected impact. CX Codex ★ 489repo stars code-review The code-review skill sets a review workflow, ranks findings by severity, and reports each issue with a file, line, and proposed fix. Use it to review diffs or new files. CX Codex +1 ★ 489repo stars technical-writer technical-writer writes README files, API references, ADRs and JSDoc after reading the actual code, so docs match real behavior instead of intent. CX Codex ★ 489repo stars refactor Subagent for codebase refactoring without altering existing behavior. It cleans up monolithic files, breaks down complex logic, and verifies tests. CX Codex ★ 489repo stars devops-engineer devops-engineer automates work on CI/CD, containers, and infrastructure. Use it to configure a build pipeline, write a Docker setup, or prepare deployment scripts. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open