agentic-seo-skill

Agentic SEO Skill

Skill by ara.so — AI Agent Skills collection.

The Agentic SEO Skill is an LLM-first SEO analysis framework designed for AI coding assistants and agent IDEs. It provides 16 specialized sub-skills, 10 specialist agents, and 89 Python scripts for evidence-based SEO analysis. The skill follows a reasoning-first workflow: collect evidence, analyze with LLM proof, apply confidence labels, prioritize by impact, and produce actionable plans.

Installation

Quick Install (No Cloning Required)

Linux/macOS:

# Install to all supported IDEs
curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online

# Install to Claude Code only
curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target claude

Install to specific project

curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target all --project-dir /path/to/project


**Windows (PowerShell 7+):**
```powershell
irm https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 --online

From Source

git clone https://github.com/Bhanunamikaze/Agentic-SEO-Skill.git
cd Agentic-SEO-Skill

# Install to Claude Code with dependencies
bash install.sh --target claude --install-deps

# Install with Playwright for visual analysis
bash install.sh --target claude --install-deps --install-playwright

Installation Targets

Target	Location	Format
`claude`	`~/.claude/skills/seo`	Skill directory
`codex`	`~/.codex/skills/seo`	Skill directory
`cursor`	`<project>/.cursor/rules/seo.mdc`	MDC rule
`windsurf`	`<project>/.windsurf/rules/seo.md`	Windsurf rule
`copilot`	`<project>/.github/copilot-instructions.md`	Repo instructions
`cline`	`<project>/.clinerules`	Project rules
`continue`	`<project>/.continue/prompts/seo.prompt`	Slash command
`antigravity`	`<project>/.agent/skills/seo`	Skill directory

Core Workflow

The skill follows an LLM-first analysis pattern:

Collect Evidence — Use read_url_content MCP tool or evidence collection scripts
Analyze with LLM — Apply explicit proof and reasoning for each finding
Label Confidence — Mark findings as Confirmed, Likely, or Hypothesis
Prioritize — Rank by impact and implementation effort
Generate Action Plan — Produce structured, evidence-backed recommendations

All audits must follow the resources/references/llm-audit-rubric.md standard.

16 Specialized Sub-Skills

1. SEO Audit (Full Site)

Run comprehensive site-wide audits with evidence-backed scoring:

# Quick full audit with all outputs
python3 scripts/audit_runner.py https://example.com

# Outputs:
# - audit_results.json
# - audit_report.html
# - FULL-AUDIT-REPORT.md
# - ACTION-PLAN.md

Agent prompt:

Use the seo audit sub-skill to analyze https://example.com — follow the LLM audit rubric, collect evidence first with read_url_content, then reason through technical, content, and performance issues.

2. SEO Page (Single Page Analysis)

Deep analysis of individual pages:

# Fetch page content
python3 scripts/fetch_page.py https://example.com/page

# Parse HTML for SEO signals
python3 scripts/parse_html.py example_com_page.html

# Check Core Web Vitals
python3 scripts/pagespeed.py https://example.com/page

Agent prompt:

Analyze this single page for SEO: https://example.com/about — check title, meta description, headings hierarchy, internal links, schema markup, and Core Web Vitals.

3. SEO Technical

Crawlability, indexability, security, mobile-friendliness, and AI crawler policies:

# Check robots.txt policies
python3 scripts/robots_checker.py https://example.com

# Run indexability matrix (robots, meta robots, canonicals, status codes)
python3 scripts/indexability_matrix.py https://example.com

# Multi-page crawl audit
python3 scripts/crawl_audit.py https://example.com --max-depth 3

Agent prompt:

Run a technical SEO audit on https://example.com — check robots.txt, XML sitemaps, HTTPS, mobile responsiveness, JS rendering, and AI crawler access (GPTBot, ClaudeBot).

4. SEO Content

Content quality assessment with E-E-A-T framework (September 2025 Quality Rater Guidelines):

# Extract article content
python3 scripts/fetch_page.py https://example.com/article

# Run content quality checks (agent analyzes with LLM)
# Check: word count, readability, E-E-A-T signals, topical depth

Agent prompt:

Assess content quality for https://example.com/blog/post using E-E-A-T criteria — check expertise signals, author credentials, content depth, readability, and December 2025 core update alignment.

5. SEO Schema

Schema.org detection, validation, and JSON-LD generation:

# Validate existing schema markup
python3 scripts/validate_schema.py example_com.html

# Check for deprecated schema types
python3 scripts/parse_html.py example_com.html --extract-schema

Agent prompt:

Validate schema markup on https://example.com — check JSON-LD syntax, required fields, deprecated types, and suggest appropriate schema.org types (Article, Product, LocalBusiness, etc.).

Example JSON-LD generation:

# Agent generates schema based on page content
schema = {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Page Title",
    "author": {
        "@type": "Person",
        "name": "Author Name"
    },
    "datePublished": "2026-01-15",
    "dateModified": "2026-05-27",
    "image": "https://example.com/image.jpg",
    "publisher": {
        "@type": "Organization",
        "name": "Publisher Name",
        "logo": {
            "@type": "ImageObject",
            "url": "https://example.com/logo.png"
        }
    }
}

6. SEO Sitemap

XML sitemap validation and generation:

# Discover and validate sitemaps
python3 scripts/sitemap_checker.py https://example.com

# Check for issues: 404s, lastmod quality, URL limits (50,000 per file)

Agent prompt:

Audit XML sitemaps for https://example.com — check discovery (robots.txt reference), URL limits, 404s, lastmod accuracy, and sitemap index structure.

7. SEO Images

Image optimization audit (alt text, formats, lazy loading, CLS):

# Generate image inventory
python3 scripts/image_inventory.py https://example.com

# Outputs: alt text coverage, dimensions, loading behavior, LCP candidates

Agent prompt:

Analyze image SEO for https://example.com — check alt text, file formats (WebP), lazy loading, responsive images (srcset), and LCP image optimization.

8. SEO GEO (Generative Engine Optimization)

Optimize for AI Overviews, ChatGPT, Perplexity:

Agent prompt:

Optimize this content for AI search engines (ChatGPT, Perplexity, Google AI Overviews) — add clear definitions, structured facts, citations, and FAQ sections.

Pattern:

Use concise definitions (20-30 words)
Add structured lists and tables
Include citations and sources
Create FAQ sections for common queries

9. SEO AEO (Answer Engine Optimization)

Optimize for Featured Snippets, People Also Ask, Knowledge Panels:

Agent prompt:

Optimize for Featured Snippets — structure content with clear question headers, concise answers (40-60 words), and bulleted/numbered lists.

Pattern:

## What is [Topic]?

[Topic] is [concise 40-60 word definition].

### Key Benefits:
1. Benefit one
2. Benefit two
3. Benefit three

10. SEO Links

Link profile analysis — internal links, backlinks, anchor text, orphan pages:

# Extract all links from page
python3 scripts/parse_html.py example_com.html --extract-links

# Agent analyzes: internal link structure, anchor text distribution, orphan pages

Agent prompt:

Audit internal linking structure for https://example.com — identify orphan pages, check anchor text diversity, analyze link depth, and suggest hub pages.

11. SEO Programmatic

Quality gates for programmatic SEO pages:

Agent prompt:

Review programmatic SEO pages for quality — check for thin content, duplicate patterns, template issues, and unique value signals on each page.

Quality gates:

Minimum 800 words unique content per page
No placeholder text (e.g., "[City]", "Lorem ipsum")
Unique titles and meta descriptions
3+ internal links to related pages

12. SEO Competitors

Comparison and alternatives page generation:

Agent prompt:

Generate a "Competitors" or "Alternatives" comparison page for [Product] — include feature tables, pricing comparison, use case fit, and neutral tone.

13. SEO Hreflang

International SEO and hreflang validation:

# Parse hreflang tags
python3 scripts/parse_html.py example_com.html --extract-hreflang

Agent prompt:

Validate hreflang implementation for multi-language site — check bidirectional links, correct language codes (ISO 639-1), regional variants (en-US, en-GB), and x-default fallback.

14. SEO Plan

Strategic SEO planning with topical clusters and industry templates:

Agent prompt:

Create an SEO content strategy for a SaaS product — build topical clusters, identify pillar pages, keyword themes, and internal linking structure.

Industry templates available:

SaaS
E-commerce
Local Business
Publisher/Media
Agency
Generic

15. SEO GitHub

GitHub repository SEO optimization:

# Generate GitHub SEO report
python3 scripts/github_seo_report.py owner/repo

# Outputs:
# - GITHUB-SEO-REPORT.md
# - GITHUB-ACTION-PLAN.md

Agent prompt:

Optimize GitHub repository SEO for [owner/repo] — improve description, add topics, enhance README structure, optimize title/headline, and benchmark against query results.

Key checks:

Repository description (160 chars, keyword-rich)
Topics (8-12 relevant tags)
README structure (clear headline, features, installation)
Social preview image
Community health files (CODE_OF_CONDUCT.md, CONTRIBUTING.md)

16. SEO Article

Article data extraction and LLM-driven content optimization:

Agent prompt:

Extract article content and optimize — check headline, readability, keyword density, internal links, meta description, and suggest improvements.

10 Specialist Agents

The skill includes specialized agents for domain-specific analysis:

Technical SEO Agent — Crawlability, indexability, security, mobile, JS rendering
Content Quality Agent — E-E-A-T scoring, AI content detection
Performance Agent — Core Web Vitals (LCP, INP, CLS)
Schema Markup Agent — JSON-LD validation and generation
Sitemap Agent — XML sitemap quality gates
Visual Analysis Agent — Screenshots, above-the-fold analysis (requires Playwright)
GitHub Analyst Agent — Repository metadata and README optimization
GitHub Benchmark Agent — Query ranking and competitor intelligence
GitHub Data Agent — API fallback and traffic archival
Verifier Agent (Global) — Deduplication and contradiction suppression

Key Scripts Reference

Evidence Collection

# Fetch page with SEO crawler headers
python3 scripts/fetch_page.py https://example.com
# Output: example_com.html

# Parse HTML for all SEO signals
python3 scripts/parse_html.py example_com.html
# Extracts: title, meta, headings, links, images, schema, canonical

# Check robots.txt and crawler policies
python3 scripts/robots_checker.py https://example.com

# Multi-page crawl
python3 scripts/crawl_audit.py https://example.com --max-depth 2 --max-pages 50

Performance & Core Web Vitals

# PageSpeed Insights + Core Web Vitals
python3 scripts/pagespeed.py https://example.com
# Returns: LCP, INP, CLS scores + recommendations

# Note: Requires PAGESPEED_API_KEY environment variable
# Get free key: https://developers.google.com/speed/docs/insights/v5/get-started

Indexability & Crawlability

# Comprehensive indexability matrix
python3 scripts/indexability_matrix.py https://example.com
# Checks: robots.txt, meta robots, X-Robots-Tag, canonical, status codes, sitemaps

# Sitemap validation
python3 scripts/sitemap_checker.py https://example.com
# Validates: URL limits, 404s, lastmod, discovery

Schema Validation

# Validate JSON-LD schema
python3 scripts/validate_schema.py page.html
# Checks: syntax, required fields, deprecated types, placeholders

Report Generation

# Full audit with all outputs
python3 scripts/audit_runner.py https://example.com

# Generate HTML dashboard
python3 scripts/generate_report.py audit_results.json --output seo-report.html

# Verify findings (deduplicate + prioritize)
python3 scripts/finding_verifier.py audit_results.json

Configuration

Environment Variables

# PageSpeed Insights API key (optional but recommended)
export PAGESPEED_API_KEY=your_api_key_here

# GitHub token for repository analysis (optional)
export GITHUB_TOKEN=your_github_token_here

Script Dependencies

Install Python dependencies:

# From project root
pip install -r requirements.txt

# Or with installer flag
bash install.sh --target claude --install-deps

Core dependencies:

requests — HTTP requests
beautifulsoup4 — HTML parsing
lxml — Fast XML/HTML parser
playwright (optional) — Visual analysis and screenshots

Install Playwright browsers:

playwright install chromium
# Or use installer flag
bash install.sh --target claude --install-deps --install-playwright

Common Patterns

Pattern 1: Quick Page Audit

# 1. Fetch page
python3 scripts/fetch_page.py https://example.com/page

# 2. Parse HTML
python3 scripts/parse_html.py example_com_page.html > page_data.json

# 3. Check Core Web Vitals
python3 scripts/pagespeed.py https://example.com/page > cwv_data.json

# 4. Agent analyzes JSON outputs with LLM reasoning

Agent prompt:

Analyze page_data.json and cwv_data.json — identify Critical/Warning/Pass findings, apply confidence labels, prioritize by impact, output structured action plan following llm-audit-rubric.md.

Pattern 2: Multi-Page Crawl Audit

# 1. Crawl site (respects robots.txt)
python3 scripts/crawl_audit.py https://example.com --max-depth 3 --max-pages 100 > crawl_results.json

# 2. Generate indexability matrix
python3 scripts/indexability_matrix.py https://example.com > indexability.json

# 3. Agent identifies issues: orphan pages, redirect chains, indexability blocks

Pattern 3: Schema Validation & Generation

# 1. Parse existing schema
python3 scripts/parse_html.py page.html --extract-schema > existing_schema.json

# 2. Validate
python3 scripts/validate_schema.py page.html

# 3. Agent generates improved schema based on page content and validation errors

Pattern 4: GitHub Repository SEO

# Generate full GitHub SEO report
python3 scripts/github_seo_report.py owner/repo

# Outputs:
# - GITHUB-SEO-REPORT.md (current state + benchmarks)
# - GITHUB-ACTION-PLAN.md (prioritized improvements)

Agent workflow:

Check repository metadata (description, topics, social preview)
Analyze README structure and keyword optimization
Benchmark title against search results
Suggest query-aligned title improvements
Identify missing community health files

Pattern 5: Full Site Audit with Reports

# One command generates all outputs
python3 scripts/audit_runner.py https://example.com

# Generates:
# 1. audit_results.json (structured data)
# 2. audit_report.html (interactive dashboard)
# 3. FULL-AUDIT-REPORT.md (markdown report)
# 4. ACTION-PLAN.md (prioritized tasks)

LLM Audit Rubric

All SEO analyses must follow the standard rubric at resources/references/llm-audit-rubric.md:

Finding Format

### [Severity]: [Finding Title]

**Evidence:**
[Specific, verifiable proof — URLs, code snippets, metrics]

**Impact:**
[SEO consequence — traffic, rankings, crawlability, user experience]

**Confidence:**
- Confirmed / Likely / Hypothesis

**Fix:**
[Actionable, specific remediation steps]

**Priority:**
- Impact: High / Medium / Low
- Effort: High / Medium / Low

Severity Levels

Critical — Blocks indexing, causes crawl errors, security issues
Warning — Degrades SEO performance, suboptimal implementation
Pass — Meets best practices
Info — Opportunities, neutral observations

Confidence Labels

Confirmed — Direct evidence (status codes, parsed HTML, API responses)
Likely — Strong inference from multiple signals
Hypothesis — Reasoned speculation requiring validation

Troubleshooting

Script Errors

Issue: ModuleNotFoundError: No module named 'requests'

Fix:

pip install -r requirements.txt
# Or
pip install requests beautifulsoup4 lxml

Issue: playwright._impl._errors.Error: Executable doesn't exist

Fix:

pip install playwright
playwright install chromium

Issue: PageSpeed API rate limit (403 or 429 errors)

Fix:

# Get free API key (100 queries/day)
# https://developers.google.com/speed/docs/insights/v5/get-started

export PAGESPEED_API_KEY=your_key_here
python3 scripts/pagespeed.py https://example.com

Installation Issues

Issue: Skill not detected after installation

Fix:

# Verify installation path
ls -la ~/.claude/skills/seo/

# Restart IDE
# Claude Code: restart extension
# Cursor: restart application

# Re-run installer with verbose output
bash install.sh --target claude -v

Issue: Windows PowerShell execution policy error

Fix:

# Run once per session
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

# Then run installer
.\install.ps1 --online --target claude

Audit Quality Issues

Issue: Too many low-confidence findings

Fix:

# Run finding verifier to deduplicate and prioritize
python3 scripts/finding_verifier.py audit_results.json

# Agent: focus on Confirmed/Likely findings first, mark Hypothesis clearly

Issue: Missing evidence in audit reports

Fix:

Always collect evidence first (fetch_page.py, parse_html.py, pagespeed.py)
Reference specific URLs, line numbers, metric values
Use read_url_content MCP tool before reasoning
Apply llm-audit-rubric.md standard for every finding

Reference Data

The skill includes up-to-date reference files (checked by CI):

Core Web Vitals — LCP (2.5s), INP (200ms), CLS (0.1)
E-E-A-T Framework — September 2025 Quality Rater Guidelines
Schema.org Types — Active, restricted, deprecated lists
Content Quality Gates — Word count minimums, readability thresholds
Google SEO Quick Reference — Best practices snapshot
LLM Audit Rubric — Standardized output contract

Reference freshness is validated with:

python3 scripts/reference_freshness.py resources/references --max-age-days 90

Advanced Usage

Custom Industry Strategy

# Agent generates topical cluster strategy
# Example for SaaS product:

# Pillar page: /seo-tools
# Cluster pages:
#   /seo-tools/keyword-research
#   /seo-tools/link-building
#   /seo-tools/technical-audit
# Each cluster page links back to pillar

# Agent uses industry template from:
# resources/skills/seo-plan.md

Multi-Language Hreflang

<!-- Agent generates hreflang tags -->
<link rel="alternate" hreflang="en" href="https://example.com/page" />
<link rel="alternate" hreflang="es" href="https://example.com/es/page" />
<link rel="alternate" hreflang="de" href="https://example.com/de/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/page" />

Validation checklist:

Bidirectional links (each page references all others)
Correct ISO 639-1 language codes
Regional variants (en-US, en-GB) where applicable
x-default fallback for unmatched locales
Self-referential link included

Programmatic SEO Quality Gates

# Agent validates programmatic pages before deployment

quality_gates = {
    "min_words": 800,
    "unique_title": True,
    "unique_meta_description": True,
    "no_placeholders": True,
    "min_internal_links": 3,
    "unique_content_ratio": 0.7  # 70% unique vs template
}

# Reject pages that fail gates
# Log failures for content team review

Wiki & Documentation

Full documentation available at: https://github.com/Bhanunamikaze/Agentic-SEO-Skill/wiki

Key wiki pages:

Script Inventory — All 89 scripts with purpose notes
Installation Guide — Detailed per-IDE setup
Example Prompts — 50+ tested agent prompts
Troubleshooting — Common issues and fixes
Report Generation — Custom report templates

License

MIT License — free for commercial and personal use.

About this skill

Installation

Quick Install (No Cloning Required)

From Source

Installation Targets

Core Workflow

16 Specialized Sub-Skills

1. SEO Audit (Full Site)

2. SEO Page (Single Page Analysis)

3. SEO Technical

4. SEO Content

5. SEO Schema

6. SEO Sitemap

7. SEO Images

8. SEO GEO (Generative Engine Optimization)

9. SEO AEO (Answer Engine Optimization)

10. SEO Links

11. SEO Programmatic

12. SEO Competitors

13. SEO Hreflang

14. SEO Plan

15. SEO GitHub

16. SEO Article

10 Specialist Agents

Key Scripts Reference

Evidence Collection

Performance & Core Web Vitals

Indexability & Crawlability

Schema Validation

Report Generation

Configuration

Environment Variables

Script Dependencies

Common Patterns

Pattern 1: Quick Page Audit

Pattern 2: Multi-Page Crawl Audit

Pattern 3: Schema Validation & Generation

Pattern 4: GitHub Repository SEO

Pattern 5: Full Site Audit with Reports

LLM Audit Rubric

Finding Format

Severity Levels

Confidence Labels

Troubleshooting

Script Errors

Installation Issues

Audit Quality Issues

Reference Data

Advanced Usage

Custom Industry Strategy

Multi-Language Hreflang

Programmatic SEO Quality Gates

Wiki & Documentation

License