seo
Deterministic LLM-first SEO audits for websites, blog posts, and GitHub repositories. Use this when the user asks to "perform SEO analysis", "run SEO audit", "analyze SEO", "check technical SEO", "review schema", "Core Web Vitals", "E-E-A-T", "hreflang", "GEO", "AEO", or GitHub repository SEO optimization. For full/page/repo audits, run bundled scripts for evidence and return prioritized, confidence-labeled fixes.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bhanunamikaze-agentic-seo-skill)HTML
<a href="/listings/bhanunamikaze-agentic-seo-skill"><img src="/api/listings/bhanunamikaze-agentic-seo-skill/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
All `--online` commands below download the latest release package from GitHub automatically. With no `--target`, `--online` installs to every supported IDE.
Quick install (no cloning required)
**Linux / macOS:**
# Default: installs to every target at once curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online # Claude Code only curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target claude # User-wide (Claude + Codex) curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target global # Every target, scoped to a project curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target all --project-dir /path/to/your/project
**Windows (PowerShell 7+):**
# Download installer, then run with --online irm https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.ps1 -OutFile install.ps1 # Default: installs to every target at once powershell -ExecutionPolicy Bypass -File .\install.ps1 --online # Claude Code only powershell -ExecutionPolicy Bypass -File .\install.ps1 --online --target claude # Every target, scoped to a project powershell -ExecutionPolicy Bypass -File .\install.ps1 --online --target all --project-dir C:\path\to\your\project
From source
git clone https://github.com/Bhanunamikaze/Agentic-SEO-Skill.git cd Agentic-SEO-Skill # Claude Code (most common) bash install.sh --target claude # Codex bash install.sh --target codex # Claude Cowork / project-scoped (installs to .claude/skills/, commit to git to share with team) bash install.sh --target cowork --project-dir /path/to/your/project # GitHub Copilot Chat (writes .github/copilot-instructions.md) bash install.sh --target copilot --project-dir /path/to/your/project # Cursor AI (writes .cursor/rules/seo.mdc) bash install.sh --target cursor --project-dir /path/to/your/project # Windsurf (writes .windsurf/rules/seo.md) bash install.sh --target windsurf --project-dir /path/to/your/project # Cline (writes .clinerules) bash install.sh --target cline --project-dir /path/to/your/project # Continue.dev (writes .continue/prompts/seo.prompt) bash install.sh --target continue --project-dir /path/to/your/project # Antigravity (writes .agent/skills/seo) bash install.sh --target antigravity --project-dir /path/to/your/project # User-wide (Claude + Codex) bash install.sh --target global # All project-local IDEs at once bash install.sh --target project --project-dir /path/to/your/project # Every target at once bash install.sh --target all --project-dir /path/to/your/project # With Python deps + Playwright (for visual analysis scripts) bash install.sh --target claude --install-deps --install-playwright
**Windows (PowerShell) — from source:**
powershell -ExecutionPolicy Bypass -File .\install.ps1 --target claude powershell -ExecutionPolicy Bypass -File .\install.ps1 --target cursor --project-dir C:\path\to\project powershell -ExecutionPolicy Bypass -File .\install.ps1 --target all --project-dir C:\path\to\project
**Safer remote install (download, inspect, run):**
curl -fsSLO https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh less install.sh # review before running bash install.sh --online
All flags
| Flag | Default | Purpose | |---|---|---| | `--target <name>` | `claude` | Pick a target (see IDE Compatibility table). With `--online` and no flag, defaults to `all`. | | `--project-dir <path>` | cwd | Where to install project-local targets. | | `--skill-name <name>` | `seo` | Override the installed folder name for skills-dir targets. | | `--online` | off | Fetch the latest release/branch archive from GitHub instead of using the local tree. |
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 369 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- ---
- name: seo
- description: >
- Deterministic LLM-first SEO audits for websites, blog posts, and GitHub
- repositories. Use this when the user asks to "perform SEO analysis", "run SEO
- audit", "analyze SEO", "check technical SEO", "review schema", "Core Web
- Vitals", "E-E-A-T", "hreflang", "GEO", "AEO", or GitHub repository SEO
- optimization. For full/page/repo audits, run bundled scripts for evidence and
- return prioritized, confidence-labeled fixes.
- ---
- # SEO Skill (Agentic / Claude / Codex)
- LLM-first SEO analysis skill with 16 specialized sub-skills, 10 specialist agents, and 89 scripts for website, blog, and GitHub repository optimization.
- ## Deterministic Trigger Mapping
- For prompt reliability in Codex/agent IDEs, map common user wording to a fixed workflow:
- - If user says `perform seo analysis on <url>` (or similar generic SEO request with a URL), treat it as a **single-URL full audit**.
- - If no explicit sub-skill is specified, run the full/page audit path with **LLM-first reasoning** and script-backed evidence.
- - For full/page audits, always produce:
- - `FULL-AUDIT-REPORT.md` (detailed findings)
- - `ACTION-PLAN.md` (prioritized fixes)
- - If `generate_report.py` is run, also return the saved HTML path (for example `SEO-REPORT.html`).
- ## Available Commands
- | Command | Sub-Skill | Description |
- |---------|-----------|-------------|
- | `seo audit <url>` | [seo-audit](resources/skills/seo-audit.md) | Full website audit with scoring |
- | `seo page <url>` | [seo-page](resources/skills/seo-page.md) | Deep single-page analysis |
- | `seo technical <url>` | [seo-technical](resources/skills/seo-technical.md) | Technical SEO checks |
- | `seo content <url>` | [seo-content](resources/skills/seo-content.md) | Content quality & E-E-A-T |
- | `seo schema <url>` | [seo-schema](resources/skills/seo-schema.md) | Schema detection/validation/generation |
- | `seo sitemap <url>` | [seo-sitemap](resources/skills/seo-sitemap.md) | Sitemap analysis & generation |
- | `seo images <url>` | [seo-images](resources/skills/seo-images.md) | Image optimization audit |
- | `seo geo <url>` | [seo-geo](resources/skills/seo-geo.md) | AI search optimization (GEO) |
- | `seo programmatic <url>` | [seo-programmatic](resources/skills/seo-programmatic.md) | Programmatic SEO safeguards |
- | `seo competitors <url>` | [seo-competitor-pages](resources/skills/seo-competitor-pages.md) | Comparison/alternatives pages |
- | `seo hreflang <url>` | [seo-hreflang](resources/skills/seo-hreflang.md) | International SEO validation |
- | `seo plan <url>` | [seo-plan](resources/skills/seo-plan.md) | Strategic SEO planning |
- | `seo github <repo_or_url>` | [seo-github](resources/skills/seo-github.md) | GitHub repository discoverability, README, topics, community health, and traffic archival |
- | `seo article <url>` | [seo-article](resources/skills/seo-article.md) | Article data extraction & LLM optimization |
- | `seo links <url>` | [seo-links](resources/skills/seo-links.md) | External backlink profile & link health |
- | `seo aeo <url>` | [seo-aeo](resources/skills/seo-aeo.md) | Answer Engine Optimization (Featured Snippets, PAA, Knowledge Panel) |
- ---
- ## Orchestration Logic
- When the user requests SEO analysis, follow this routing:
- ### Step 1 — Identify the Task
- Parse the user's request to determine which sub-skill(s) to activate:
- - **Full audit**: Read `resources/skills/seo-audit.md` — crawl multiple pages, delegate to agents, score and report
- - **Single page**: Read `resources/skills/seo-page.md` — deep dive on one URL
- - **Specific area**: Read the matching `resources/skills/seo-*.md` file
- - **Strategic plan**: Read `resources/skills/seo-plan.md` and the matching `resources/templates/*.md` for the detected industry
- - **GitHub repository SEO**: Read `resources/skills/seo-github.md` and use GitHub scripts with `--provider auto` for API/`gh` fallback.
- - **Generic `perform seo analysis on <url>` request**: treat as single-page full audit, read `resources/skills/seo-page.md`, and generate `FULL-AUDIT-REPORT.md` + `ACTION-PLAN.md`.
- ### Step 2 — Collect Evidence
- **Primary method (LLM-first)** — use the built-in `read_url_content` tool first:
- ```
- read_url_content(url) → returns parsed HTML content directly
- ```
- Use this as the baseline evidence for reasoning.
- **Deterministic verification (recommended when script execution is available)**:
- ```bash
- # Fetch/parse raw HTML for structured checks
- python3 <SKILL_DIR>/scripts/fetch_page.py <url> --output /tmp/page.html
- python3 <SKILL_DIR>/scripts/parse_html.py /tmp/page.html --url <url> --json
- # Optional: generate shareable HTML dashboard artifact
- python3 <SKILL_DIR>/scripts/generate_report.py <url> --output SEO-REPORT.html
- ```
- > **Do not use third-party mirrors (e.g., `r.jina.ai`) as primary evidence when direct site fetch or bundled scripts are available.**
- > `<SKILL_DIR>` = absolute path to this skill directory (the folder containing this SKILL.md).
- ### Step 3 — Perform LLM-First Analysis
- Use the LLM as the primary SEO analyst:
- 1. Synthesize evidence from page content, metadata, and optional script outputs.
- 2. Produce findings with explicit proof:
- - `Finding`
- - `Evidence` (specific element, metric, or snippet)
- - `Impact` (why it matters for ranking/indexing/UX)
- - `Fix` (clear implementation step)
- 3. Prioritize by impact and implementation effort.
- 4. Separate confirmed issues, likely issues, and unknowns (missing data).
- Always read and apply `resources/references/llm-audit-rubric.md` to keep scoring, severity, confidence, and output structure consistent across audit types.
- ### Step 4 — Run Baseline Verification Scripts (When execution is available)
- For full/page audits, run baseline checks to avoid hypothesis-only reporting. Do not replace LLM reasoning with script-only scoring.
- ```bash
- # Check robots.txt and AI crawler management
- python3 <SKILL_DIR>/scripts/robots_checker.py <url>
- # Check llms.txt for AI search readiness
- python3 <SKILL_DIR>/scripts/llms_txt_checker.py <url>
- # Get Core Web Vitals from PageSpeed Insights (free API, no key needed)
- python3 <SKILL_DIR>/scripts/pagespeed.py <url> --strategy mobile
- # Check security headers (HSTS, CSP, X-Frame-Options, etc.)
- python3 <SKILL_DIR>/scripts/security_headers.py <url>
- # Detect broken links on a page (404s, timeouts, connection errors)
- python3 <SKILL_DIR>/scripts/broken_links.py <url> --workers 5
- # Trace redirect chains, detect loops and mixed HTTP/HTTPS
- python3 <SKILL_DIR>/scripts/redirect_checker.py <url>
- # Analyze readability from fetched HTML (Flesch-Kincaid, grade level, sentence stats)
- python3 <SKILL_DIR>/scripts/readability.py /tmp/page.html --json
- # Validate Open Graph and Twitter Card meta tags
- python3 <SKILL_DIR>/scripts/social_meta.py <url>
- # Analyze internal link structure, find orphan pages
- python3 <SKILL_DIR>/scripts/internal_links.py <url> --depth 1 --max-pages 20
- # Extract article content and perform keyword research for LLM-driven optimization
- python3 <SKILL_DIR>/scripts/article_seo.py <url> --keyword "<optional_target_keyword>" --json
- # Credentials for paid/auth APIs (PageSpeed, GitHub, GSC, Knowledge Graph)
- # are loaded from CLI flags, then env vars, then a `.env` file in the repo
- # root / cwd / `~/.agentic-seo/.env`. Copy `.env.example` to `.env` and fill
- # in only the keys you have. Never paste secrets in prompts.
- # GitHub repository SEO (provider fallback: auto|api|gh)
- # Auth setup (choose one):
- # export GITHUB_TOKEN="ghp_xxx" # or export GH_TOKEN="ghp_xxx"
- # gh auth login -h github.com && gh auth status -h github.com
- python3 <SKILL_DIR>/scripts/github_repo_audit.py --repo <owner/repo> --provider auto --json
- python3 <SKILL_DIR>/scripts/github_readme_lint.py README.md --json
- python3 <SKILL_DIR>/scripts/github_community_health.py --repo <owner/repo> --provider auto --json
- # Benchmark/competitor inputs should be provided by LLM/web-search discovery when possible.
- # If omitted, github_seo_report.py auto-derives repo-specific benchmark queries.
- python3 <SKILL_DIR>/scripts/github_search_benchmark.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --json
- python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --top-n 6 --json
- python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --competitor <owner/repo> --competitor <owner/repo> --provider auto --json
- python3 <SKILL_DIR>/scripts/github_traffic_archiver.py --repo <owner/repo> --provider auto --archive-dir .github-seo-data --json
- python3 <SKILL_DIR>/scripts/github_seo_report.py --repo <owner/repo> --provider auto --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
- # Optional: increase/reduce auto-derived query volume (default: 6)
- # python3 <SKILL_DIR>/scripts/github_seo_report.py --repo <owner/repo> --provider auto --auto-query-max 8 --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
- ```
- If a check fails due network, DNS, permissions, or API rate limits:
- - Report it explicitly as an **environment limitation**, not a confirmed site issue.
- - Keep confidence as `Hypothesis` for impacted categories.
- - Continue with available evidence instead of stopping the audit.
- - Do not enter repeated fallback loops. Retry a failed source at most once, then finalize the audit.
- - Do not pivot into repeated web-search scraping loops for the same URL.
- **Visual analysis** (requires Playwright — use `conda activate pentest` if available):
- ```bash
- # Capture screenshots (desktop, laptop, tablet, mobile)
- python3 <SKILL_DIR>/scripts/capture_screenshot.py <url> --all
- # Analyze visual layout, above-the-fold, mobile responsiveness
- python3 <SKILL_DIR>/scripts/analyze_visual.py <url> --json
- ```
- **HTML Report Generator** — generates a self-contained interactive HTML dashboard:
- ```bash
- # Generate full SEO report (runs scripts automatically, saves HTML to PWD)
- python3 <SKILL_DIR>/scripts/generate_report.py <url>
- python3 <SKILL_DIR>/scripts/generate_report.py <url> --output custom-report.html
- ```
- ### Step 5 — Delegate to Specialist Agents
- For comprehensive audits, read the relevant agent file from `resources/agents/` to adopt the specialist role:
- | Agent | File | Focus Area |
- |-------|------|------------|
- | Technical SEO | [seo-technical.md](resources/agents/seo-technical.md) | Crawlability, indexability, security, URLs, mobile, CWV, JS rendering |
- | Content Quality | [seo-content.md](resources/agents/seo-content.md) | E-E-A-T assessment, content metrics, AI content detection |
- | Performance | [seo-performance.md](resources/agents/seo-performance.md) | Core Web Vitals (LCP, INP, CLS), optimization recommendations |
- | Schema Markup | [seo-schema.md](resources/agents/seo-schema.md) | Detection, validation, generation of JSON-LD structured data |
- | Sitemap | [seo-sitemap.md](resources/agents/seo-sitemap.md) | XML sitemap validation, generation, quality gates |
- | Visual Analysis | [seo-visual.md](resources/agents/seo-visual.md) | Screenshots, above-the-fold, responsiveness, layout |
- | Verifier (global) | [seo-verifier.md](resources/agents/seo-verifier.md) | Deduplicate findings, suppress contradictions, and validate evidence relevance before final report |
- ### Step 6 — Apply Quality Gates
- Reference the quality standards in `resources/references/`:
- - **Content minimums**: Read [quality-gates.md](resources/references/quality-gates.md) for word counts, unique content %, title/meta requirements
- - **Schema validation**: Read [schema-types.md](resources/references/schema-types.md) for active/deprecated/restricted types
- - **Core Web Vitals**: Read [cwv-thresholds.md](resources/references/cwv-thresholds.md) for current metric thresholds
- - **E-E-A-T framework**: Read [eeat-framework.md](resources/references/eeat-framework.md) for scoring criteria
- - **Google reference**: Read [google-seo-reference.md](resources/references/google-seo-reference.md) for quick reference
- - **LLM report rubric**: Read [llm-audit-rubric.md](resources/references/llm-audit-rubric.md) for mandatory evidence format, confidence labels, and output contract
- ### Step 6.5 — Verify Findings (All Workflows)
- Before writing final reports, run verification:
- ```bash
- python3 <SKILL_DIR>/scripts/finding_verifier.py --findings-json <raw_findings.json> --json
- ```
- Use verified output for final report tables, not raw findings.
- ### Step 7 — Score and Report
- Use numeric scores as guidance, not as a replacement for evidence quality and judgment.
- #### Default Scoring Weights (Full Audit)
- > **Canonical source of truth** — These weights are defined here and in `resources/skills/seo-audit.md`.
- > Do not modify weights in individual sub-skill files; update only these two locations to keep scores consistent.
- | Category | Weight |
- |----------|--------|
- | Technical SEO | 25% |
- | Content Quality | 20% |
- | On-Page SEO | 15% |
- | Schema / Structured Data | 15% |
- | Performance (CWV) | 10% |
- | Image Optimization | 10% |
- | AI Search Readiness (GEO) | 5% |
- > If using `scripts/generate_report.py`, the automated dashboard uses script-level category weights defined in that script. Keep the narrative audit LLM-first and evidence-first.
- ### Step 8 — Mandatory Deliverables
- For `seo audit`, `seo page`, and generic `perform seo analysis on <url>` flows:
- 1. Create `FULL-AUDIT-REPORT.md` in the current working directory at the start of the audit, then update it as evidence is collected.
- 2. Create `ACTION-PLAN.md` in the current working directory at the start of the audit, then update it with prioritized fixes.
- 3. If HTML dashboard was generated, include its exact saved path (for example `SEO-REPORT.html` or an absolute path).
- 4. In the final response, explicitly list generated artifacts and paths.
- 5. If technical checks are blocked by environment limits, still write both markdown files and include an "Environment Limitations" section.
- #### Score Interpretation
- | Score | Rating |
- |-------|--------|
- | 90-100 | Excellent |
- | 70-89 | Good |
- | 50-69 | Needs Improvement |
- | 30-49 | Poor |
- | 0-29 | Critical |
- ---
- ## Industry Detection
- When running `seo plan`, detect the business type and load the matching template:
- | Industry | Template File |
- |----------|---------------|
- | SaaS / Software | [saas.md](resources/templates/saas.md) |
- | Local Service Business | [local-service.md](resources/templates/local-service.md) |
- | E-commerce / Retail | [ecommerce.md](resources/templates/ecommerce.md) |
- | Publisher / Media | [publisher.md](resources/templates/publisher.md) |
- | Agency / Consultancy | [agency.md](resources/templates/agency.md) |
- | Other / Generic | [generic.md](resources/templates/generic.md) |
- **Detection signals:**
- - SaaS: pricing page, feature pages, /docs, /api, trial/demo CTAs
- - Local: address, phone, Google Business Profile, service area pages
- - E-commerce: product pages, cart, checkout, /collections, /categories
- - Publisher: article dates, author pages, /news, high content volume
- - Agency: case studies, /work, /portfolio, team pages, service offerings
- ---
- ## Schema Templates
- Pre-built JSON-LD templates are available in [templates.json](resources/schema/templates.json) for:
- - **Common**: BlogPosting, Article, Organization, LocalBusiness, BreadcrumbList, WebSite (with SearchAction)
- - **Video**: VideoObject, BroadcastEvent, Clip, SeekToAction
- - **E-commerce**: ProductGroup (variants), OfferShippingDetails, Certification
- - **Other**: SoftwareSourceCode, ProfilePage (E-E-A-T author pages)
- ---
- ## Validation Scripts
- Two validation scripts are available for CI/CD integration:
- ### Pre-commit SEO Check
- ```bash
- bash <SKILL_DIR>/scripts/pre_commit_seo_check.sh
- ```
- Checks staged HTML files for: placeholder text in schema, title tag length, missing alt text, deprecated schema types, FID references (should be INP), meta description length.
- ### Schema Validator
- ```bash
- python3 <SKILL_DIR>/scripts/validate_schema.py <file_path>
- ```
- Validates JSON-LD blocks in HTML files: JSON syntax, @context/@type presence, placeholder text, deprecated/restricted types.
- ### Skill Inventory Validator
- ```bash
- python3 <SKILL_DIR>/scripts/validate_skill_inventory.py
- ```
- Validates documented sub-skill, agent, and script counts against files on disk. CI uses this to prevent README/SKILL inventory drift.
- ### Reference Freshness Validator
- ```bash
- python3 <SKILL_DIR>/scripts/reference_freshness.py <SKILL_DIR>/resources/references --max-age-days 90
- ```
- Checks that every reference file has a `<!-- Updated: YYYY-MM-DD -->` marker and flags references older than the configured freshness window.
- ---
- ## Output Format
- All sub-skill reports should use consistent severity levels:
- - 🔴 **Critical** — Directly impacts rankings or indexing (fix immediately)
- - ⚠️ **Warning** — Optimization opportunity (fix within 1 month)
- - ✅ **Pass** — Meets or exceeds standards
- - ℹ️ **Info** — Not applicable or informational only
- Structure reports as:
- 1. Summary table with element, value, and severity
- 2. Detailed findings grouped by category
- 3. Actionable recommendations ordered by impact
- ---
- ## Critical Rules
- 1. **INP not FID** — FID was removed September 9, 2024. The sole interactivity metric is INP (Interaction to Next Paint). Never reference FID.
- 2. **FAQ schema is restricted** — FAQPage schema is limited to government and healthcare authority sites only (August 2023). Do NOT recommend for commercial sites.
- 3. **HowTo schema is deprecated** — Rich results fully removed September 2023. Never recommend.
- 4. **JSON-LD only** — Always use `<script type="application/ld+json">`. Never recommend Microdata or RDFa.
- 5. **E-E-A-T everywhere** — As of December 2025, E-E-A-T applies to ALL competitive queries, not just YMYL.
- 6. **Mobile-first is complete** — 100% mobile-first indexing since July 5, 2024.
- 7. **Location page limits** — Warning at 30+ pages, hard stop at 50+ pages. Enforce unique content requirements.
- 8. **AI crawler management** — Check robots.txt for GPTBot, ClaudeBot, PerplexityBot, Applebot-Extended, Google-Extended, Bytespider, CCBot.
- 9. **LLM-first, resilient pipeline** — Start by reading the page with `read_url_content`, then always run relevant scripts for structured evidence. Scripts are the **preferred** evidence source — use them actively. However, if any script fails (timeout, network, parsing), the LLM MUST still produce a complete analysis using its own reasoning (confidence: `Likely`). Never block a report on a single script failure.
- 10. **Always produce file artifacts for audit flows** — `FULL-AUDIT-REPORT.md` and `ACTION-PLAN.md` are required outputs for full/page audit requests.
- 11. **Bound evidence retries** — Avoid long search/retry loops. If core checks fail due DNS/network, finalize promptly with confidence labels and file outputs.
- 12. **Avoid redundant web fallbacks** — If direct fetch/scripts fail and one fallback also fails, stop retrying and finish the report with explicit limitations.
- 13. **Signal freshness tracking** — Every reference file should contain a `<!-- Updated: YYYY-MM-DD -->` comment. Flag any reference file older than 90 days for review. When Google announces algorithm changes, verify affected reference files within 7 days. Key dates to track: core updates (quarterly), schema deprecations (schema-types.md), CWV threshold changes (cwv-thresholds.md).
- ---
- ## Dependencies
- ### Optional Script Dependencies
- - Python 3.8+
- - `requests` (for network analysis scripts)
- - `beautifulsoup4` (for HTML parsing scripts)
- - Playwright (for `capture_screenshot.py` and `analyze_visual.py`)
- ```bash
- pip install playwright && playwright install chromium
- ```
- Or if using conda: `conda activate pentest` (if Playwright is pre-installed)
- ### Install Script Dependencies
- ```bash
- pip install requests beautifulsoup4
- ```
README.md · README · 621 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # SEO Skill (Antigravity / Claude / Codex / Cursor)
- An LLM-first SEO analysis skill for agent IDEs and AI coding assistants, with 16 specialized sub-skills, 10 specialist agents, and 89 scripts used as evidence collectors and workflow automation.
- For detailed installation guidance, example prompts, report generation, troubleshooting, and the full script inventory, see the **[Agentic SEO Skill Wiki](https://github.com/Bhanunamikaze/Agentic-SEO-Skill/wiki)**.
- ## IDE Compatibility
- The installer ships native formats for each tool — not just a generic copy:
- | Tool | Install location | Native format |
- |---|---|---|
- | Claude Code | `~/.claude/skills/seo` | Skill directory |
- | Codex CLI | `~/.codex/skills/seo` | Skill directory |
- | Antigravity IDE | `<project>/.agent/skills/seo` | Skill directory |
- | Claude Cowork | `<project>/.claude/skills/seo` | Project-scoped skill (commit to git) |
- | Cursor | `<project>/.cursor/rules/seo.mdc` + `.cursor/skills/seo/` | MDC rule |
- | Windsurf | `<project>/.windsurf/rules/seo.md` + `.windsurf/skills/seo/` | Windsurf rule |
- | Continue.dev | `<project>/.continue/prompts/seo.prompt` + `.continue/skills/seo/` | Slash command |
- | GitHub Copilot | `<project>/.github/copilot-instructions.md` + `.github/skills/seo/` | Repo instructions |
- | Cline | `<project>/.clinerules` + `.cline/skills/seo/` | Project rules |
- ## 📦 Current Inventory
- - Specialized sub-skills: `16`
- - Specialist agents: `10`
- - Scripts in `scripts/`: `89` (`88` Python + `1` shell validation helper)
- Inventory drift is checked by CI with:
- ```bash
- python3 scripts/validate_skill_inventory.py
- python3 scripts/reference_freshness.py resources/references --max-age-days 90
- ```
- ### Key Script Inventory
- The README only highlights the scripts most users reach for first. See the full 89-script list with purpose notes in the [Script Inventory wiki](https://github.com/Bhanunamikaze/Agentic-SEO-Skill/wiki/Script-Inventory).
- | Script | Best for |
- |---|---|
- | `audit_runner.py` | One-command full audit that writes JSON, HTML, `FULL-AUDIT-REPORT.md`, and `ACTION-PLAN.md`. |
- | `generate_report.py` | Self-contained browser dashboard for sharing SEO findings. |
- | `fetch_page.py` | Reliable page fetch with SEO crawler headers and local HTML output. |
- | `parse_html.py` | Extract titles, metadata, headings, links, images, schema, and canonical signals. |
- | `pagespeed.py` | Core Web Vitals and PageSpeed Insights evidence. |
- | `crawl_audit.py` | Multi-page crawl evidence for status, metadata, depth, and duplicate signals. |
- | `indexability_matrix.py` | Per-URL indexability verdicts from robots, meta robots, canonicals, status, and sitemaps. |
- | `robots_checker.py` | Search and AI crawler policy checks from `robots.txt`. |
- | `sitemap_checker.py` | XML sitemap discovery, parsing, limits, status checks, and `lastmod` quality. |
- | `image_inventory.py` | Image alt text, dimensions, loading behavior, responsive image, and LCP-candidate evidence. |
- | `validate_schema.py` | JSON-LD syntax, required fields, placeholders, and deprecated schema checks. |
- | `github_seo_report.py` | GitHub repository SEO report and action plan generation. |
- | `finding_verifier.py` | Deduplicate, prioritize, and validate findings before final reporting. |
- ## 🐙 GitHub SEO Metadata
- Recommended GitHub repository description (About field):
- ```text
- LLM-first SEO skill for Claude Code, Codex, Antigravity, Cursor, Windsurf, Continue, Copilot, and Cline — 16 sub-skills, 10 specialist agents, and GitHub SEO workflows that output GITHUB-SEO-REPORT.md and GITHUB-ACTION-PLAN.md.
- ```
- Suggested GitHub topics:
- ```text
- seo, llm, github-seo, ai-search, geo, aeo, technical-seo, schema, core-web-vitals, codex, claude-code, antigravity, cursor, windsurf, copilot
- ```
- ## ✨ Features
- | Sub-Skill | Description |
- |-----------|-------------|
- | [seo audit](resources/skills/seo-audit.md) | Full website audit with evidence-backed scoring |
- | [seo article](resources/skills/seo-article.md) | Article data extraction & LLM-driven content optimization |
- | [seo page](resources/skills/seo-page.md) | Deep single-page analysis |
- | [seo technical](resources/skills/seo-technical.md) | Crawlability, indexability, security, Core Web Vitals, AI crawlers |
- | [seo content](resources/skills/seo-content.md) | Content quality & E-E-A-T assessment (Sept 2025 QRG) |
- | [seo schema](resources/skills/seo-schema.md) | Schema.org detection, validation & JSON-LD generation |
- | [seo sitemap](resources/skills/seo-sitemap.md) | XML sitemap analysis & generation |
- | [seo images](resources/skills/seo-images.md) | Image optimization audit (alt text, formats, lazy loading, CLS) |
- | [seo geo](resources/skills/seo-geo.md) | Generative Engine Optimization — AI Overviews, ChatGPT, Perplexity |
- | [seo aeo](resources/skills/seo-aeo.md) | Answer Engine Optimization — Featured Snippets, PAA, Knowledge Panel |
- | [seo links](resources/skills/seo-links.md) | Link profile analysis — internal links, backlinks, anchor text, orphan pages |
- | [seo programmatic](resources/skills/seo-programmatic.md) | Programmatic SEO safeguards & quality gates |
- | [seo competitors](resources/skills/seo-competitor-pages.md) | Comparison & alternatives page generation |
- | [seo hreflang](resources/skills/seo-hreflang.md) | International SEO / hreflang validation |
- | [seo plan](resources/skills/seo-plan.md) | Strategic SEO planning with topical clusters & industry templates |
- | [seo github](resources/skills/seo-github.md) | GitHub repository SEO: metadata/topics, README quality, community profile, query benchmarking, traffic archiving |
- ## 🧠 LLM-First Workflow
- This skill is designed for reasoning-first SEO analysis:
- 1. Collect page evidence (`read_url_content` first, scripts optional).
- 2. Analyze with LLM using explicit proof for each finding.
- 3. Apply confidence labels (`Confirmed`, `Likely`, `Hypothesis`).
- 4. Prioritize by impact and effort.
- 5. Produce a structured action plan.
- ### Required Rubric
- All audits should apply:
- - `resources/references/llm-audit-rubric.md`
- The rubric standardizes:
- - evidence format (`Finding`, `Evidence`, `Impact`, `Fix`)
- - severity (`Critical`, `Warning`, `Pass`, `Info`)
- - confidence labeling
- - output contract for audit reports
- ## 🤖 Specialist Agents
- - **Technical SEO** — crawlability, indexability, security, mobile, JS rendering
- - **Content Quality** — E-E-A-T scoring, AI content detection
- - **Performance** — Core Web Vitals (LCP, INP, CLS) analysis
- - **Schema Markup** — JSON-LD detection, validation, generation
- - **Sitemap** — XML sitemap validation, quality gates
- - **Visual Analysis** — screenshots, above-the-fold, responsiveness (Playwright)
- - **GitHub Analyst** — metadata, topics, README, trust, title strategy
- - **GitHub Benchmark** — query ranking and competitor intelligence
- - **GitHub Data** — API/auth fallback and traffic archival continuity
- - **Verifier (Global)** — dedupe/contradiction suppression before final reporting
- ## 📚 Reference Data
- - Core Web Vitals thresholds (INP replaced FID)
- - E-E-A-T framework (Sept 2025 QRG + Dec 2025 core update)
- - Schema.org types — active, restricted, deprecated
- - Content quality gates & word count minimums
- - Google SEO quick reference
- - LLM audit rubric for consistent outputs
- Each reference file carries its own `<!-- Updated: YYYY-MM-DD -->` marker. CI checks those markers with `scripts/reference_freshness.py` and flags stale references for review.
- ## 🏭 Industry Templates
- Pre-built strategy templates for: **SaaS**, **E-commerce**, **Local Business**, **Publisher/Media**, **Agency**, and **Generic** businesses.
- ---
- ## 🔧 Installation
- All `--online` commands below download the latest release package from GitHub automatically. With no `--target`, `--online` installs to every supported IDE.
- ### Quick install (no cloning required)
- **Linux / macOS:**
- ```bash
- # Default: installs to every target at once
- curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online
- # Claude Code only
- curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target claude
- # User-wide (Claude + Codex)
- curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target global
- # Every target, scoped to a project
- curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target all --project-dir /path/to/your/project
- ```
- **Windows (PowerShell 7+):**
- ```powershell
- # Download installer, then run with --online
- irm https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.ps1 -OutFile install.ps1
- # Default: installs to every target at once
- powershell -ExecutionPolicy Bypass -File .\install.ps1 --online
- # Claude Code only
- powershell -ExecutionPolicy Bypass -File .\install.ps1 --online --target claude
- # Every target, scoped to a project
- powershell -ExecutionPolicy Bypass -File .\install.ps1 --online --target all --project-dir C:\path\to\your\project
- ```
- ### From source
- ```bash
- git clone https://github.com/Bhanunamikaze/Agentic-SEO-Skill.git
- cd Agentic-SEO-Skill
- # Claude Code (most common)
- bash install.sh --target claude
- # Codex
- bash install.sh --target codex
- # Claude Cowork / project-scoped (installs to .claude/skills/, commit to git to share with team)
- bash install.sh --target cowork --project-dir /path/to/your/project
- # GitHub Copilot Chat (writes .github/copilot-instructions.md)
- bash install.sh --target copilot --project-dir /path/to/your/project
- # Cursor AI (writes .cursor/rules/seo.mdc)
- bash install.sh --target cursor --project-dir /path/to/your/project
- # Windsurf (writes .windsurf/rules/seo.md)
- bash install.sh --target windsurf --project-dir /path/to/your/project
- # Cline (writes .clinerules)
- bash install.sh --target cline --project-dir /path/to/your/project
- # Continue.dev (writes .continue/prompts/seo.prompt)
- bash install.sh --target continue --project-dir /path/to/your/project
- # Antigravity (writes .agent/skills/seo)
- bash install.sh --target antigravity --project-dir /path/to/your/project
- # User-wide (Claude + Codex)
- bash install.sh --target global
- # All project-local IDEs at once
- bash install.sh --target project --project-dir /path/to/your/project
- # Every target at once
- bash install.sh --target all --project-dir /path/to/your/project
- # With Python deps + Playwright (for visual analysis scripts)
- bash install.sh --target claude --install-deps --install-playwright
- ```
- **Windows (PowerShell) — from source:**
- ```powershell
- powershell -ExecutionPolicy Bypass -File .\install.ps1 --target claude
- powershell -ExecutionPolicy Bypass -File .\install.ps1 --target cursor --project-dir C:\path\to\project
- powershell -ExecutionPolicy Bypass -File .\install.ps1 --target all --project-dir C:\path\to\project
- ```
- **Safer remote install (download, inspect, run):**
- ```bash
- curl -fsSLO https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh
- less install.sh # review before running
- bash install.sh --online
- ```
- ### All flags
- | Flag | Default | Purpose |
- |---|---|---|
- | `--target <name>` | `claude` | Pick a target (see IDE Compatibility table). With `--online` and no flag, defaults to `all`. |
- | `--project-dir <path>` | cwd | Where to install project-local targets. |
- | `--skill-name <name>` | `seo` | Override the installed folder name for skills-dir targets. |
- | `--online` | off | Fetch the latest release/branch archive from GitHub instead of using the local tree. |
- | `--ref <branch-or-tag>` | `main` | Branch or tag to use in `--online` mode. |
- | `--repo-url <url>` | upstream | Override the source repo for remote clone. |
- | `--source <auto\|local\|remote>` | `auto` | Force the source resolution mode. |
- | `--repo-path <path>` | — | Use a specific local checkout as the install source. |
- | `--install-deps` | off | Also `pip install --user requests beautifulsoup4`. |
- | `--install-playwright` | off | Also install Playwright + Chromium (for visual analysis). |
- | `--force` | off | Overwrite an existing installed skill. (`--online` implies `--force`.) |
- | `-h`, `--help` | — | Show the full usage block. |
- ### Python dependencies (manual)
- If you skipped `--install-deps`:
- ```bash
- pip install requests beautifulsoup4
- # Optional — for visual analysis (screenshots & layout checks):
- pip install playwright && playwright install chromium
- ```
- ### Verify Triggering
- The skill will auto-trigger when you mention SEO-related keywords in your IDE. Try:
- - *"Run an SEO audit on example.com"*
- - *"Check the schema markup on my homepage"*
- - *"Analyze Core Web Vitals for my site"*
- - *"Create an SEO plan for my SaaS product"*
- - *"Run GitHub SEO analysis for owner/repo"*
- ---
- ## 💬 Example Prompts (hackingdream.net)
- For expanded copy-paste prompt templates across full audits, technical SEO, schema, content, GEO/AEO, local SEO, ecommerce, and GitHub SEO, see the [Example Prompts wiki](https://github.com/Bhanunamikaze/Agentic-SEO-Skill/wiki/Example-Prompts).
- ### How Prompts Route to Agents & Scripts
- The IDE uses an **LLM orchestration layer** to match your natural language intent to the correct underlying sub-skill (e.g., `seo-hreflang.md`, `seo-schema.md`). You do not need to use explicit flags or commands.
- - **To run a specific test:** Ask for it specifically (e.g., "Check hreflang"). The LLM will only trigger the necessary scripts.
- - **To force ALL agents/tests:** Ask for a "full, comprehensive audit running all checks". The LLM will route this to `seo-audit.md`, which acts as the master orchestrator calling all available scripts and analyzing the combined output.
- Here's how specific phrases map to the skill's capabilities:
- | You type... | Scope | Agent(s) activated | Scripts used |
- |-------------|-------|-------------------|--------------|
- | "Run SEO audit" | 🌐 Full domain | **All 6 core website agents** (technical, content, schema, performance, sitemap, visual) | `audit_runner.py`, `crawl_audit.py`, `parse_html.py`, `pagespeed.py`, `robots_checker.py`, `security_headers.py`, `broken_links.py`, `readability.py` |
- | "Analyze this article" / blog post URL | 📄 Single page | **Content** + **Schema** + **Technical** | `article_seo.py`, `parse_html.py`, `readability.py` |
- | "Check technical SEO" | 🔧 Technical only | **Technical** | `robots_checker.py`, `security_headers.py`, `redirect_checker.py`, `parse_html.py` |
- | "Review content quality" / "E-E-A-T" | 📝 Content only | **Content** | `article_seo.py`, `readability.py`, `entity_checker.py` |
- | "Check schema markup" | 🏷️ Schema only | **Schema** | `parse_html.py`, `validate_schema.py` |
- | "Audit sitemap" | 🗺️ Sitemap only | **Sitemap** | `sitemap_checker.py`, `sitemap_generator.py` |
- | "Check page speed" / "Core Web Vitals" | ⚡ Performance only | **Performance** | `pagespeed.py` |
- | "Take screenshots" / "mobile check" | 📱 Visual only | **Visual** | `capture_screenshot.py`, `analyze_visual.py` |
- | "Check GEO readiness" / "AI search" | 🤖 GEO/AI only | **Technical** + **Content** | `llms_txt_checker.py`, `robots_checker.py`, `parse_html.py` |
- | "Analyze links" / "backlink profile" | 🔗 Links only | **Technical** | `link_profile.py`, `internal_links.py`, `broken_links.py` |
- | "Check hreflang" | 🌍 i18n only | **Technical** | `hreflang_checker.py` |
- | "Create SEO plan" / "SEO strategy" | 📋 Strategy | None (LLM reasoning) | `competitor_gap.py` (optional) |
- | "AEO analysis" / "Featured Snippets" | 🎯 AEO only | **Content** | `article_seo.py`, `parse_html.py` |
- | "Entity SEO" / "Knowledge Graph" | 🏛️ Entity only | **Content** + **Schema** | `entity_checker.py`, `parse_html.py` |
- | "Check IndexNow" | 📡 IndexNow only | **Technical** | `indexnow_checker.py` |
- | "Find content gaps" / "competitor analysis" | 📊 Gap analysis | None (LLM reasoning) | `competitor_gap.py` |
- | "Check for duplicates" / "thin content" | 📋 Dupe check | **Content** | `duplicate_content.py` |
- | "GSC data" / "Search Console" | 📈 GSC only | None | `gsc_checker.py` |
- | "GitHub SEO" / "optimize this repo" | 🐙 Repository | **GitHub Analyst** + **Benchmark** + **Data** + **Verifier** | `github_repo_audit.py`, `github_readme_lint.py`, `github_community_health.py`, `github_search_benchmark.py`, `github_competitor_research.py`, `github_traffic_archiver.py`, `github_seo_report.py`, `finding_verifier.py` (outputs `GITHUB-SEO-REPORT.md` + `GITHUB-ACTION-PLAN.md`) |
- ### Domain vs URL vs Blog Post — What's Different?
- | Input type | What happens | Example |
- |-----------|-------------|---------|
- | **Domain** (`hackingdream.net`) | Crawls multiple pages, checks robots.txt, sitemap, site-wide patterns | Full audit, link profile, sitemap check |
- | **URL** (`hackingdream.net/page`) | Single page deep-dive: HTML, meta, schema, content, CWV | Page audit, schema check, technical check |
- | **Blog post URL** | Article-specific: readability, keyword density, heading structure, JSON-LD `Article`/`BlogPosting` schema, publish date | Article analysis, AEO check |
- ---
- ### 🌐 Full Domain Audit
- ```text
- Run a full SEO audit for https://hackingdream.net and prioritize fixes by impact.
- ```
- ### 📄 Single Page / Blog Post Analysis
- ```text
- Analyze this article: https://www.hackingdream.net/2026/02/cobalt-strike-beacon-commands-red-team-field-guide.html
- ```
- ```text
- Do a single-page SEO analysis of https://hackingdream.net and show critical issues first.
- ```
- ### 🔧 Technical SEO
- ```text
- Analyze technical SEO for https://hackingdream.net (robots, crawlability, canonicals, redirects, headers).
- ```
- ### 📝 Content Quality & E-E-A-T
- ```text
- Review content quality and E-E-A-T signals on https://hackingdream.net and suggest concrete rewrites.
- ```
- ### 🏷️ Schema Markup
- ```text
- Check schema markup on https://hackingdream.net, validate errors, and generate corrected JSON-LD.
- ```
- ### ⚡ Performance & Core Web Vitals
- ```text
- Run Core Web Vitals analysis on https://hackingdream.net and break down LCP subparts.
- ```
- ### 🤖 GEO / AI Search Readiness
- ```text
- Evaluate GEO readiness for https://hackingdream.net (AI crawler access, llms.txt, citation structure).
- ```
- ### 🎯 Answer Engine Optimization (AEO)
- ```text
- Analyze AEO signals for https://hackingdream.net — Featured Snippet targeting, PAA optimization, Knowledge Panel readiness.
- ```
- ### 🔗 Link Profile Analysis
- ```text
- Analyze internal link structure and backlink profile for https://hackingdream.net.
- ```
- ### 🏛️ Entity SEO / Knowledge Graph
- ```text
- Check entity SEO for https://hackingdream.net — Wikidata presence, sameAs links, Knowledge Graph signals.
- ```
- ### 📊 Competitor Topic Gap
- ```text
- Find content gaps between https://hackingdream.net and competitors https://hackerone.com https://portswigger.net.
- ```
- ### 🌍 Hreflang / International SEO
- ```text
- Validate hreflang implementation on https://hackingdream.net — BCP-47 tags, bidirectional links, x-default.
- ```
- ### 📡 IndexNow
- ```text
- Check IndexNow implementation for https://hackingdream.net with key abc123def456.
- ```
- ### 📋 Topical Cluster Planning
- ```text
- Create a topical authority cluster plan for https://hackingdream.net covering cybersecurity topics.
- ```
- ### 📈 Google Search Console (requires credentials)
- ```text
- Pull GSC performance data for https://hackingdream.net and identify striking-distance keywords.
- ```
- ### 🗺️ Sitemap Audit
- ```text
- Audit sitemap quality for https://hackingdream.net and flag missing, redirected, or noindex URLs.
- ```
- ### 🖼️ Image SEO
- ```text
- Run image SEO checks for https://hackingdream.net (alt text, lazy loading, dimensions, format suggestions).
- ```
- ### 📋 Strategic SEO Plan
- ```text
- Create a 6-month SEO strategy for https://hackingdream.net with milestones and KPIs.
- ```
- ### 📱 Visual / Mobile Analysis
- ```text
- Take desktop and mobile screenshots of https://hackingdream.net and analyze above-the-fold content.
- ```
- ---
- ### Run Everything at Once
- To run **all** analysis types on a single URL:
- ```text
- Run a complete SEO audit on https://hackingdream.net — include technical, content, schema, performance,
- links, GEO, AEO, entity SEO, and sitemap analysis. Provide a prioritized action plan.
- ```
- Example generated outputs:
- - `FULL-AUDIT-REPORT.md` — comprehensive findings
- - `ACTION-PLAN.md` — prioritized fixes
- 
- ---
- ## 📊 Report Generation
- You can generate reports in two ways:
- 1. **LLM-first report in your IDE (Antigravity / Claude / Codex)** (recommended for strategy + prioritization):
- ```text
- Run a full SEO audit for https://hackingdream.net and produce a prioritized action plan with evidence for each finding.
- ```
- 2. **Interactive HTML dashboard** (recommended for shareable technical snapshots):
- ```bash
- python3 scripts/generate_report.py "https://hackingdream.net" --output seo-report-hackingdream.html
- ```
- The HTML report includes:
- - overall score and category breakdown
- - environment detection (platform/runtime inference)
- - environment-specific fix plan
- - section-level issues and recommendations
- - readability "what to replace" suggestions
- Example generated dashboard:
- 
- ---
- ## ⚙️ Optional Script Workflow
- Use scripts when you need additional verification or structured JSON outputs.
- ### Credentials (`.env` file)
- Some scripts use third-party APIs. Instead of pasting keys on the command line every time, copy `.env.example` to `.env` and fill in the keys you have:
- ```bash
- cp .env.example .env
- $EDITOR .env # add PAGESPEED_API_KEY, GITHUB_TOKEN, GSC_CREDENTIALS_PATH, etc.
- ```
- `.env` is gitignored. The loader searches the current directory, the skill root, and `~/.agentic-seo/.env` (in that order). Real shell-exported env vars and `--flag` overrides always win.
- | Variable | Used by | How to get one |
- |---|---|---|
- | `PAGESPEED_API_KEY` | `pagespeed.py`, `generate_report.py` | [Google Cloud Console](https://console.cloud.google.com/) → enable "PageSpeed Insights API" |
- | `GOOGLE_KG_API_KEY` | `entity_checker.py` | Same console → enable "Knowledge Graph Search API" |
- | `GITHUB_TOKEN` *(or `GH_TOKEN`)* | All `github_*.py` scripts | A PAT with `public_repo` is enough; `gh auth login` works as a fallback |
- | `GSC_CREDENTIALS_PATH` | `gsc_checker.py`, `link_profile.py` | Path to a Google service-account JSON with Search Console access |
- ```bash
- # GitHub auth setup for repository SEO scripts (choose one)
- export GITHUB_TOKEN="ghp_xxx" # or: export GH_TOKEN="ghp_xxx"
- # or authenticate gh CLI:
- gh auth login -h github.com
- gh auth status -h github.com
- # Example target
- URL="https://example.com"
- # Fetch + parse HTML
- python3 scripts/fetch_page.py "$URL" --output /tmp/page.html
- python3 scripts/parse_html.py /tmp/page.html --url "$URL" --json
- # Core checks
- python3 scripts/robots_checker.py "$URL" --json
- python3 scripts/llms_txt_checker.py "$URL" --json
- python3 scripts/pagespeed.py "$URL" --strategy mobile --json
- python3 scripts/security_headers.py "$URL" --json
- python3 scripts/redirect_checker.py "$URL" --json
- python3 scripts/social_meta.py "$URL" --json
- python3 scripts/sitemap_checker.py "$URL" --json
- python3 scripts/crawl_audit.py "$URL" --max-pages 50 --json
- python3 scripts/indexability_matrix.py --site "$URL" --json
- python3 scripts/canonical_checker.py "$URL" --json
- python3 scripts/x_robots_header_checker.py "$URL" --json
- # Content + structure checks
- python3 scripts/readability.py /tmp/page.html --json
- python3 scripts/internal_links.py "$URL" --depth 1 --max-pages 20 --json
- python3 scripts/broken_links.py "$URL" --workers 5 --json
- python3 scripts/article_seo.py "$URL" --json
- python3 scripts/image_inventory.py /tmp/page.html --json
- python3 scripts/a11y_seo_checker.py /tmp/page.html --json
- python3 scripts/url_quality.py "$URL" --json
- # New analysis scripts
- python3 scripts/hreflang_checker.py "$URL" --json
- python3 scripts/entity_checker.py "$URL" --json
- python3 scripts/duplicate_content.py "$URL" --json
- python3 scripts/link_profile.py "$URL" --json
- python3 scripts/competitor_gap.py "$URL" --competitor https://competitor.com --json
- python3 scripts/faceted_nav_audit.py "$URL" --json
- python3 scripts/ai_crawler_policy_matrix.py "$URL" --json
- python3 scripts/llms_txt_generator.py "$URL" "$URL" --title "Example Site" --description "Example site summary." --json
- # python3 scripts/gsc_checker.py "$URL" --credentials creds.json --json # requires GSC credentials
- # python3 scripts/indexnow_checker.py "$URL" --key YOUR_KEY --json # requires IndexNow key
- # GitHub repository SEO scripts (provider fallback: auto|api|gh)
- python3 scripts/github_repo_audit.py --repo owner/repo --provider auto --json
- python3 scripts/github_readme_lint.py README.md --json
- python3 scripts/github_community_health.py --repo owner/repo --provider auto --json
- # Provide query/competitor inputs from LLM/web-search discovery when possible:
- python3 scripts/github_search_benchmark.py --repo owner/repo --query "<llm_or_web_query>" --provider auto --json
- python3 scripts/github_competitor_research.py --repo owner/repo --query "<llm_or_web_query>" --provider auto --top-n 6 --json
- python3 scripts/github_competitor_research.py --repo owner/repo --competitor owner/repo --competitor owner/repo --provider auto --json
- python3 scripts/github_traffic_archiver.py --repo owner/repo --provider auto --archive-dir .github-seo-data --json
- # github_seo_report.py auto-derives repo-specific benchmark queries if none are provided
- python3 scripts/github_seo_report.py --repo owner/repo --provider auto --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
- # Optional: tune auto-derived query count (default: 6)
- # python3 scripts/github_seo_report.py --repo owner/repo --provider auto --auto-query-max 8 --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
- # Generic verifier stage (can be used by any workflow before final reporting)
- python3 scripts/finding_verifier.py --findings-json raw-findings.json --json
- ```
- Generate a single HTML dashboard if needed:
- ```bash
- python3 scripts/generate_report.py "$URL"
- ```
- ---
- ## 🛡️ Critical Rules Enforced
- | Rule | Detail |
- |------|--------|
- | **INP not FID** | FID removed Sept 2024. INP is the sole interactivity metric. |
- | **FAQ schema restricted** | FAQPage only for government/healthcare authority sites (Aug 2023) |
- | **HowTo deprecated** | Rich results removed Sept 2023 |
- | **JSON-LD only** | Never recommend Microdata or RDFa |
- | **E-E-A-T everywhere** | Applies to ALL competitive queries since Dec 2025 |
- | **Mobile-first complete** | 100% mobile-first indexing since July 2024 |
- | **Location page limits** | ⚠️ Warning at 30+ pages, 🛑 Hard stop at 50+ |
- ---
- ## 📋 Requirements
- | Requirement | Version |
- |-------------|---------|
- | Python | 3.8+ |
- | `requests` | Any |
- | `beautifulsoup4` | Any |
- | Playwright | Optional (for visual analysis) |
- ---
- ## 🙏 Credits
- This project was originally inspired by **[claude-seo](https://github.com/AgriciDaniel/claude-seo)** by **[AgriciDaniel](https://github.com/AgriciDaniel)**.
- Agentic SEO Skill has since evolved into a broader, independently maintained skill package with expanded agent workflows, release packaging, GitHub SEO automation, reporting, validation, and many additional scripts. The project keeps the same practical goal: make SEO analysis usable inside agent IDEs and AI coding assistants through a clear skill layout (`SKILL.md` + `scripts/` + `resources/`).
- ---
- ## 📄 License
- Licensed under the MIT License. See [LICENSE](LICENSE).
- Earlier inspiration and some concepts trace back to [claude-seo](https://github.com/AgriciDaniel/claude-seo), which is also MIT-licensed.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.