Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bhanunamikaze-agentic-seo-skill/badge.svg)](/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

i

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.

  1. ---
  2. name: seo
  3. description: >
  4. Deterministic LLM-first SEO audits for websites, blog posts, and GitHub
  5. repositories. Use this when the user asks to "perform SEO analysis", "run SEO
  6. audit", "analyze SEO", "check technical SEO", "review schema", "Core Web
  7. Vitals", "E-E-A-T", "hreflang", "GEO", "AEO", or GitHub repository SEO
  8. optimization. For full/page/repo audits, run bundled scripts for evidence and
  9. return prioritized, confidence-labeled fixes.
  10. ---
  11. # SEO Skill (Agentic / Claude / Codex)
  12. LLM-first SEO analysis skill with 16 specialized sub-skills, 10 specialist agents, and 89 scripts for website, blog, and GitHub repository optimization.
  13. ## Deterministic Trigger Mapping
  14. For prompt reliability in Codex/agent IDEs, map common user wording to a fixed workflow:
  15. - If user says `perform seo analysis on <url>` (or similar generic SEO request with a URL), treat it as a **single-URL full audit**.
  16. - If no explicit sub-skill is specified, run the full/page audit path with **LLM-first reasoning** and script-backed evidence.
  17. - For full/page audits, always produce:
  18. - `FULL-AUDIT-REPORT.md` (detailed findings)
  19. - `ACTION-PLAN.md` (prioritized fixes)
  20. - If `generate_report.py` is run, also return the saved HTML path (for example `SEO-REPORT.html`).
  21. ## Available Commands
  22. | Command | Sub-Skill | Description |
  23. |---------|-----------|-------------|
  24. | `seo audit <url>` | [seo-audit](resources/skills/seo-audit.md) | Full website audit with scoring |
  25. | `seo page <url>` | [seo-page](resources/skills/seo-page.md) | Deep single-page analysis |
  26. | `seo technical <url>` | [seo-technical](resources/skills/seo-technical.md) | Technical SEO checks |
  27. | `seo content <url>` | [seo-content](resources/skills/seo-content.md) | Content quality & E-E-A-T |
  28. | `seo schema <url>` | [seo-schema](resources/skills/seo-schema.md) | Schema detection/validation/generation |
  29. | `seo sitemap <url>` | [seo-sitemap](resources/skills/seo-sitemap.md) | Sitemap analysis & generation |
  30. | `seo images <url>` | [seo-images](resources/skills/seo-images.md) | Image optimization audit |
  31. | `seo geo <url>` | [seo-geo](resources/skills/seo-geo.md) | AI search optimization (GEO) |
  32. | `seo programmatic <url>` | [seo-programmatic](resources/skills/seo-programmatic.md) | Programmatic SEO safeguards |
  33. | `seo competitors <url>` | [seo-competitor-pages](resources/skills/seo-competitor-pages.md) | Comparison/alternatives pages |
  34. | `seo hreflang <url>` | [seo-hreflang](resources/skills/seo-hreflang.md) | International SEO validation |
  35. | `seo plan <url>` | [seo-plan](resources/skills/seo-plan.md) | Strategic SEO planning |
  36. | `seo github <repo_or_url>` | [seo-github](resources/skills/seo-github.md) | GitHub repository discoverability, README, topics, community health, and traffic archival |
  37. | `seo article <url>` | [seo-article](resources/skills/seo-article.md) | Article data extraction & LLM optimization |
  38. | `seo links <url>` | [seo-links](resources/skills/seo-links.md) | External backlink profile & link health |
  39. | `seo aeo <url>` | [seo-aeo](resources/skills/seo-aeo.md) | Answer Engine Optimization (Featured Snippets, PAA, Knowledge Panel) |
  40. ---
  41. ## Orchestration Logic
  42. When the user requests SEO analysis, follow this routing:
  43. ### Step 1 — Identify the Task
  44. Parse the user's request to determine which sub-skill(s) to activate:
  45. - **Full audit**: Read `resources/skills/seo-audit.md` — crawl multiple pages, delegate to agents, score and report
  46. - **Single page**: Read `resources/skills/seo-page.md` — deep dive on one URL
  47. - **Specific area**: Read the matching `resources/skills/seo-*.md` file
  48. - **Strategic plan**: Read `resources/skills/seo-plan.md` and the matching `resources/templates/*.md` for the detected industry
  49. - **GitHub repository SEO**: Read `resources/skills/seo-github.md` and use GitHub scripts with `--provider auto` for API/`gh` fallback.
  50. - **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`.
  51. ### Step 2 — Collect Evidence
  52. **Primary method (LLM-first)** — use the built-in `read_url_content` tool first:
  53. ```
  54. read_url_content(url) → returns parsed HTML content directly
  55. ```
  56. Use this as the baseline evidence for reasoning.
  57. **Deterministic verification (recommended when script execution is available)**:
  58. ```bash
  59. # Fetch/parse raw HTML for structured checks
  60. python3 <SKILL_DIR>/scripts/fetch_page.py <url> --output /tmp/page.html
  61. python3 <SKILL_DIR>/scripts/parse_html.py /tmp/page.html --url <url> --json
  62. # Optional: generate shareable HTML dashboard artifact
  63. python3 <SKILL_DIR>/scripts/generate_report.py <url> --output SEO-REPORT.html
  64. ```
  65. > **Do not use third-party mirrors (e.g., `r.jina.ai`) as primary evidence when direct site fetch or bundled scripts are available.**
  66. > `<SKILL_DIR>` = absolute path to this skill directory (the folder containing this SKILL.md).
  67. ### Step 3 — Perform LLM-First Analysis
  68. Use the LLM as the primary SEO analyst:
  69. 1. Synthesize evidence from page content, metadata, and optional script outputs.
  70. 2. Produce findings with explicit proof:
  71. - `Finding`
  72. - `Evidence` (specific element, metric, or snippet)
  73. - `Impact` (why it matters for ranking/indexing/UX)
  74. - `Fix` (clear implementation step)
  75. 3. Prioritize by impact and implementation effort.
  76. 4. Separate confirmed issues, likely issues, and unknowns (missing data).
  77. Always read and apply `resources/references/llm-audit-rubric.md` to keep scoring, severity, confidence, and output structure consistent across audit types.
  78. ### Step 4 — Run Baseline Verification Scripts (When execution is available)
  79. For full/page audits, run baseline checks to avoid hypothesis-only reporting. Do not replace LLM reasoning with script-only scoring.
  80. ```bash
  81. # Check robots.txt and AI crawler management
  82. python3 <SKILL_DIR>/scripts/robots_checker.py <url>
  83. # Check llms.txt for AI search readiness
  84. python3 <SKILL_DIR>/scripts/llms_txt_checker.py <url>
  85. # Get Core Web Vitals from PageSpeed Insights (free API, no key needed)
  86. python3 <SKILL_DIR>/scripts/pagespeed.py <url> --strategy mobile
  87. # Check security headers (HSTS, CSP, X-Frame-Options, etc.)
  88. python3 <SKILL_DIR>/scripts/security_headers.py <url>
  89. # Detect broken links on a page (404s, timeouts, connection errors)
  90. python3 <SKILL_DIR>/scripts/broken_links.py <url> --workers 5
  91. # Trace redirect chains, detect loops and mixed HTTP/HTTPS
  92. python3 <SKILL_DIR>/scripts/redirect_checker.py <url>
  93. # Analyze readability from fetched HTML (Flesch-Kincaid, grade level, sentence stats)
  94. python3 <SKILL_DIR>/scripts/readability.py /tmp/page.html --json
  95. # Validate Open Graph and Twitter Card meta tags
  96. python3 <SKILL_DIR>/scripts/social_meta.py <url>
  97. # Analyze internal link structure, find orphan pages
  98. python3 <SKILL_DIR>/scripts/internal_links.py <url> --depth 1 --max-pages 20
  99. # Extract article content and perform keyword research for LLM-driven optimization
  100. python3 <SKILL_DIR>/scripts/article_seo.py <url> --keyword "<optional_target_keyword>" --json
  101. # Credentials for paid/auth APIs (PageSpeed, GitHub, GSC, Knowledge Graph)
  102. # are loaded from CLI flags, then env vars, then a `.env` file in the repo
  103. # root / cwd / `~/.agentic-seo/.env`. Copy `.env.example` to `.env` and fill
  104. # in only the keys you have. Never paste secrets in prompts.
  105. # GitHub repository SEO (provider fallback: auto|api|gh)
  106. # Auth setup (choose one):
  107. # export GITHUB_TOKEN="ghp_xxx" # or export GH_TOKEN="ghp_xxx"
  108. # gh auth login -h github.com && gh auth status -h github.com
  109. python3 <SKILL_DIR>/scripts/github_repo_audit.py --repo <owner/repo> --provider auto --json
  110. python3 <SKILL_DIR>/scripts/github_readme_lint.py README.md --json
  111. python3 <SKILL_DIR>/scripts/github_community_health.py --repo <owner/repo> --provider auto --json
  112. # Benchmark/competitor inputs should be provided by LLM/web-search discovery when possible.
  113. # If omitted, github_seo_report.py auto-derives repo-specific benchmark queries.
  114. python3 <SKILL_DIR>/scripts/github_search_benchmark.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --json
  115. python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --query "<llm_or_web_query>" --provider auto --top-n 6 --json
  116. python3 <SKILL_DIR>/scripts/github_competitor_research.py --repo <owner/repo> --competitor <owner/repo> --competitor <owner/repo> --provider auto --json
  117. python3 <SKILL_DIR>/scripts/github_traffic_archiver.py --repo <owner/repo> --provider auto --archive-dir .github-seo-data --json
  118. 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
  119. # Optional: increase/reduce auto-derived query volume (default: 6)
  120. # 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
  121. ```
  122. If a check fails due network, DNS, permissions, or API rate limits:
  123. - Report it explicitly as an **environment limitation**, not a confirmed site issue.
  124. - Keep confidence as `Hypothesis` for impacted categories.
  125. - Continue with available evidence instead of stopping the audit.
  126. - Do not enter repeated fallback loops. Retry a failed source at most once, then finalize the audit.
  127. - Do not pivot into repeated web-search scraping loops for the same URL.
  128. **Visual analysis** (requires Playwright — use `conda activate pentest` if available):
  129. ```bash
  130. # Capture screenshots (desktop, laptop, tablet, mobile)
  131. python3 <SKILL_DIR>/scripts/capture_screenshot.py <url> --all
  132. # Analyze visual layout, above-the-fold, mobile responsiveness
  133. python3 <SKILL_DIR>/scripts/analyze_visual.py <url> --json
  134. ```
  135. **HTML Report Generator** — generates a self-contained interactive HTML dashboard:
  136. ```bash
  137. # Generate full SEO report (runs scripts automatically, saves HTML to PWD)
  138. python3 <SKILL_DIR>/scripts/generate_report.py <url>
  139. python3 <SKILL_DIR>/scripts/generate_report.py <url> --output custom-report.html
  140. ```
  141. ### Step 5 — Delegate to Specialist Agents
  142. For comprehensive audits, read the relevant agent file from `resources/agents/` to adopt the specialist role:
  143. | Agent | File | Focus Area |
  144. |-------|------|------------|
  145. | Technical SEO | [seo-technical.md](resources/agents/seo-technical.md) | Crawlability, indexability, security, URLs, mobile, CWV, JS rendering |
  146. | Content Quality | [seo-content.md](resources/agents/seo-content.md) | E-E-A-T assessment, content metrics, AI content detection |
  147. | Performance | [seo-performance.md](resources/agents/seo-performance.md) | Core Web Vitals (LCP, INP, CLS), optimization recommendations |
  148. | Schema Markup | [seo-schema.md](resources/agents/seo-schema.md) | Detection, validation, generation of JSON-LD structured data |
  149. | Sitemap | [seo-sitemap.md](resources/agents/seo-sitemap.md) | XML sitemap validation, generation, quality gates |
  150. | Visual Analysis | [seo-visual.md](resources/agents/seo-visual.md) | Screenshots, above-the-fold, responsiveness, layout |
  151. | Verifier (global) | [seo-verifier.md](resources/agents/seo-verifier.md) | Deduplicate findings, suppress contradictions, and validate evidence relevance before final report |
  152. ### Step 6 — Apply Quality Gates
  153. Reference the quality standards in `resources/references/`:
  154. - **Content minimums**: Read [quality-gates.md](resources/references/quality-gates.md) for word counts, unique content %, title/meta requirements
  155. - **Schema validation**: Read [schema-types.md](resources/references/schema-types.md) for active/deprecated/restricted types
  156. - **Core Web Vitals**: Read [cwv-thresholds.md](resources/references/cwv-thresholds.md) for current metric thresholds
  157. - **E-E-A-T framework**: Read [eeat-framework.md](resources/references/eeat-framework.md) for scoring criteria
  158. - **Google reference**: Read [google-seo-reference.md](resources/references/google-seo-reference.md) for quick reference
  159. - **LLM report rubric**: Read [llm-audit-rubric.md](resources/references/llm-audit-rubric.md) for mandatory evidence format, confidence labels, and output contract
  160. ### Step 6.5 — Verify Findings (All Workflows)
  161. Before writing final reports, run verification:
  162. ```bash
  163. python3 <SKILL_DIR>/scripts/finding_verifier.py --findings-json <raw_findings.json> --json
  164. ```
  165. Use verified output for final report tables, not raw findings.
  166. ### Step 7 — Score and Report
  167. Use numeric scores as guidance, not as a replacement for evidence quality and judgment.
  168. #### Default Scoring Weights (Full Audit)
  169. > **Canonical source of truth** — These weights are defined here and in `resources/skills/seo-audit.md`.
  170. > Do not modify weights in individual sub-skill files; update only these two locations to keep scores consistent.
  171. | Category | Weight |
  172. |----------|--------|
  173. | Technical SEO | 25% |
  174. | Content Quality | 20% |
  175. | On-Page SEO | 15% |
  176. | Schema / Structured Data | 15% |
  177. | Performance (CWV) | 10% |
  178. | Image Optimization | 10% |
  179. | AI Search Readiness (GEO) | 5% |
  180. > 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.
  181. ### Step 8 — Mandatory Deliverables
  182. For `seo audit`, `seo page`, and generic `perform seo analysis on <url>` flows:
  183. 1. Create `FULL-AUDIT-REPORT.md` in the current working directory at the start of the audit, then update it as evidence is collected.
  184. 2. Create `ACTION-PLAN.md` in the current working directory at the start of the audit, then update it with prioritized fixes.
  185. 3. If HTML dashboard was generated, include its exact saved path (for example `SEO-REPORT.html` or an absolute path).
  186. 4. In the final response, explicitly list generated artifacts and paths.
  187. 5. If technical checks are blocked by environment limits, still write both markdown files and include an "Environment Limitations" section.
  188. #### Score Interpretation
  189. | Score | Rating |
  190. |-------|--------|
  191. | 90-100 | Excellent |
  192. | 70-89 | Good |
  193. | 50-69 | Needs Improvement |
  194. | 30-49 | Poor |
  195. | 0-29 | Critical |
  196. ---
  197. ## Industry Detection
  198. When running `seo plan`, detect the business type and load the matching template:
  199. | Industry | Template File |
  200. |----------|---------------|
  201. | SaaS / Software | [saas.md](resources/templates/saas.md) |
  202. | Local Service Business | [local-service.md](resources/templates/local-service.md) |
  203. | E-commerce / Retail | [ecommerce.md](resources/templates/ecommerce.md) |
  204. | Publisher / Media | [publisher.md](resources/templates/publisher.md) |
  205. | Agency / Consultancy | [agency.md](resources/templates/agency.md) |
  206. | Other / Generic | [generic.md](resources/templates/generic.md) |
  207. **Detection signals:**
  208. - SaaS: pricing page, feature pages, /docs, /api, trial/demo CTAs
  209. - Local: address, phone, Google Business Profile, service area pages
  210. - E-commerce: product pages, cart, checkout, /collections, /categories
  211. - Publisher: article dates, author pages, /news, high content volume
  212. - Agency: case studies, /work, /portfolio, team pages, service offerings
  213. ---
  214. ## Schema Templates
  215. Pre-built JSON-LD templates are available in [templates.json](resources/schema/templates.json) for:
  216. - **Common**: BlogPosting, Article, Organization, LocalBusiness, BreadcrumbList, WebSite (with SearchAction)
  217. - **Video**: VideoObject, BroadcastEvent, Clip, SeekToAction
  218. - **E-commerce**: ProductGroup (variants), OfferShippingDetails, Certification
  219. - **Other**: SoftwareSourceCode, ProfilePage (E-E-A-T author pages)
  220. ---
  221. ## Validation Scripts
  222. Two validation scripts are available for CI/CD integration:
  223. ### Pre-commit SEO Check
  224. ```bash
  225. bash <SKILL_DIR>/scripts/pre_commit_seo_check.sh
  226. ```
  227. 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.
  228. ### Schema Validator
  229. ```bash
  230. python3 <SKILL_DIR>/scripts/validate_schema.py <file_path>
  231. ```
  232. Validates JSON-LD blocks in HTML files: JSON syntax, @context/@type presence, placeholder text, deprecated/restricted types.
  233. ### Skill Inventory Validator
  234. ```bash
  235. python3 <SKILL_DIR>/scripts/validate_skill_inventory.py
  236. ```
  237. Validates documented sub-skill, agent, and script counts against files on disk. CI uses this to prevent README/SKILL inventory drift.
  238. ### Reference Freshness Validator
  239. ```bash
  240. python3 <SKILL_DIR>/scripts/reference_freshness.py <SKILL_DIR>/resources/references --max-age-days 90
  241. ```
  242. Checks that every reference file has a `<!-- Updated: YYYY-MM-DD -->` marker and flags references older than the configured freshness window.
  243. ---
  244. ## Output Format
  245. All sub-skill reports should use consistent severity levels:
  246. - 🔴 **Critical** — Directly impacts rankings or indexing (fix immediately)
  247. - ⚠️ **Warning** — Optimization opportunity (fix within 1 month)
  248. - ✅ **Pass** — Meets or exceeds standards
  249. - ℹ️ **Info** — Not applicable or informational only
  250. Structure reports as:
  251. 1. Summary table with element, value, and severity
  252. 2. Detailed findings grouped by category
  253. 3. Actionable recommendations ordered by impact
  254. ---
  255. ## Critical Rules
  256. 1. **INP not FID** — FID was removed September 9, 2024. The sole interactivity metric is INP (Interaction to Next Paint). Never reference FID.
  257. 2. **FAQ schema is restricted** — FAQPage schema is limited to government and healthcare authority sites only (August 2023). Do NOT recommend for commercial sites.
  258. 3. **HowTo schema is deprecated** — Rich results fully removed September 2023. Never recommend.
  259. 4. **JSON-LD only** — Always use `<script type="application/ld+json">`. Never recommend Microdata or RDFa.
  260. 5. **E-E-A-T everywhere** — As of December 2025, E-E-A-T applies to ALL competitive queries, not just YMYL.
  261. 6. **Mobile-first is complete** — 100% mobile-first indexing since July 5, 2024.
  262. 7. **Location page limits** — Warning at 30+ pages, hard stop at 50+ pages. Enforce unique content requirements.
  263. 8. **AI crawler management** — Check robots.txt for GPTBot, ClaudeBot, PerplexityBot, Applebot-Extended, Google-Extended, Bytespider, CCBot.
  264. 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.
  265. 10. **Always produce file artifacts for audit flows** — `FULL-AUDIT-REPORT.md` and `ACTION-PLAN.md` are required outputs for full/page audit requests.
  266. 11. **Bound evidence retries** — Avoid long search/retry loops. If core checks fail due DNS/network, finalize promptly with confidence labels and file outputs.
  267. 12. **Avoid redundant web fallbacks** — If direct fetch/scripts fail and one fallback also fails, stop retrying and finish the report with explicit limitations.
  268. 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).
  269. ---
  270. ## Dependencies
  271. ### Optional Script Dependencies
  272. - Python 3.8+
  273. - `requests` (for network analysis scripts)
  274. - `beautifulsoup4` (for HTML parsing scripts)
  275. - Playwright (for `capture_screenshot.py` and `analyze_visual.py`)
  276. ```bash
  277. pip install playwright && playwright install chromium
  278. ```
  279. Or if using conda: `conda activate pentest` (if Playwright is pre-installed)
  280. ### Install Script Dependencies
  281. ```bash
  282. pip install requests beautifulsoup4
  283. ```
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.

  1. # SEO Skill (Antigravity / Claude / Codex / Cursor)
  2. 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.
  3. 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)**.
  4. ## IDE Compatibility
  5. The installer ships native formats for each tool — not just a generic copy:
  6. | Tool | Install location | Native format |
  7. |---|---|---|
  8. | Claude Code | `~/.claude/skills/seo` | Skill directory |
  9. | Codex CLI | `~/.codex/skills/seo` | Skill directory |
  10. | Antigravity IDE | `<project>/.agent/skills/seo` | Skill directory |
  11. | Claude Cowork | `<project>/.claude/skills/seo` | Project-scoped skill (commit to git) |
  12. | Cursor | `<project>/.cursor/rules/seo.mdc` + `.cursor/skills/seo/` | MDC rule |
  13. | Windsurf | `<project>/.windsurf/rules/seo.md` + `.windsurf/skills/seo/` | Windsurf rule |
  14. | Continue.dev | `<project>/.continue/prompts/seo.prompt` + `.continue/skills/seo/` | Slash command |
  15. | GitHub Copilot | `<project>/.github/copilot-instructions.md` + `.github/skills/seo/` | Repo instructions |
  16. | Cline | `<project>/.clinerules` + `.cline/skills/seo/` | Project rules |
  17. ## 📦 Current Inventory
  18. - Specialized sub-skills: `16`
  19. - Specialist agents: `10`
  20. - Scripts in `scripts/`: `89` (`88` Python + `1` shell validation helper)
  21. Inventory drift is checked by CI with:
  22. ```bash
  23. python3 scripts/validate_skill_inventory.py
  24. python3 scripts/reference_freshness.py resources/references --max-age-days 90
  25. ```
  26. ### Key Script Inventory
  27. 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).
  28. | Script | Best for |
  29. |---|---|
  30. | `audit_runner.py` | One-command full audit that writes JSON, HTML, `FULL-AUDIT-REPORT.md`, and `ACTION-PLAN.md`. |
  31. | `generate_report.py` | Self-contained browser dashboard for sharing SEO findings. |
  32. | `fetch_page.py` | Reliable page fetch with SEO crawler headers and local HTML output. |
  33. | `parse_html.py` | Extract titles, metadata, headings, links, images, schema, and canonical signals. |
  34. | `pagespeed.py` | Core Web Vitals and PageSpeed Insights evidence. |
  35. | `crawl_audit.py` | Multi-page crawl evidence for status, metadata, depth, and duplicate signals. |
  36. | `indexability_matrix.py` | Per-URL indexability verdicts from robots, meta robots, canonicals, status, and sitemaps. |
  37. | `robots_checker.py` | Search and AI crawler policy checks from `robots.txt`. |
  38. | `sitemap_checker.py` | XML sitemap discovery, parsing, limits, status checks, and `lastmod` quality. |
  39. | `image_inventory.py` | Image alt text, dimensions, loading behavior, responsive image, and LCP-candidate evidence. |
  40. | `validate_schema.py` | JSON-LD syntax, required fields, placeholders, and deprecated schema checks. |
  41. | `github_seo_report.py` | GitHub repository SEO report and action plan generation. |
  42. | `finding_verifier.py` | Deduplicate, prioritize, and validate findings before final reporting. |
  43. ## 🐙 GitHub SEO Metadata
  44. Recommended GitHub repository description (About field):
  45. ```text
  46. 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.
  47. ```
  48. Suggested GitHub topics:
  49. ```text
  50. seo, llm, github-seo, ai-search, geo, aeo, technical-seo, schema, core-web-vitals, codex, claude-code, antigravity, cursor, windsurf, copilot
  51. ```
  52. ## ✨ Features
  53. | Sub-Skill | Description |
  54. |-----------|-------------|
  55. | [seo audit](resources/skills/seo-audit.md) | Full website audit with evidence-backed scoring |
  56. | [seo article](resources/skills/seo-article.md) | Article data extraction & LLM-driven content optimization |
  57. | [seo page](resources/skills/seo-page.md) | Deep single-page analysis |
  58. | [seo technical](resources/skills/seo-technical.md) | Crawlability, indexability, security, Core Web Vitals, AI crawlers |
  59. | [seo content](resources/skills/seo-content.md) | Content quality & E-E-A-T assessment (Sept 2025 QRG) |
  60. | [seo schema](resources/skills/seo-schema.md) | Schema.org detection, validation & JSON-LD generation |
  61. | [seo sitemap](resources/skills/seo-sitemap.md) | XML sitemap analysis & generation |
  62. | [seo images](resources/skills/seo-images.md) | Image optimization audit (alt text, formats, lazy loading, CLS) |
  63. | [seo geo](resources/skills/seo-geo.md) | Generative Engine Optimization — AI Overviews, ChatGPT, Perplexity |
  64. | [seo aeo](resources/skills/seo-aeo.md) | Answer Engine Optimization — Featured Snippets, PAA, Knowledge Panel |
  65. | [seo links](resources/skills/seo-links.md) | Link profile analysis — internal links, backlinks, anchor text, orphan pages |
  66. | [seo programmatic](resources/skills/seo-programmatic.md) | Programmatic SEO safeguards & quality gates |
  67. | [seo competitors](resources/skills/seo-competitor-pages.md) | Comparison & alternatives page generation |
  68. | [seo hreflang](resources/skills/seo-hreflang.md) | International SEO / hreflang validation |
  69. | [seo plan](resources/skills/seo-plan.md) | Strategic SEO planning with topical clusters & industry templates |
  70. | [seo github](resources/skills/seo-github.md) | GitHub repository SEO: metadata/topics, README quality, community profile, query benchmarking, traffic archiving |
  71. ## 🧠 LLM-First Workflow
  72. This skill is designed for reasoning-first SEO analysis:
  73. 1. Collect page evidence (`read_url_content` first, scripts optional).
  74. 2. Analyze with LLM using explicit proof for each finding.
  75. 3. Apply confidence labels (`Confirmed`, `Likely`, `Hypothesis`).
  76. 4. Prioritize by impact and effort.
  77. 5. Produce a structured action plan.
  78. ### Required Rubric
  79. All audits should apply:
  80. - `resources/references/llm-audit-rubric.md`
  81. The rubric standardizes:
  82. - evidence format (`Finding`, `Evidence`, `Impact`, `Fix`)
  83. - severity (`Critical`, `Warning`, `Pass`, `Info`)
  84. - confidence labeling
  85. - output contract for audit reports
  86. ## 🤖 Specialist Agents
  87. - **Technical SEO** — crawlability, indexability, security, mobile, JS rendering
  88. - **Content Quality** — E-E-A-T scoring, AI content detection
  89. - **Performance** — Core Web Vitals (LCP, INP, CLS) analysis
  90. - **Schema Markup** — JSON-LD detection, validation, generation
  91. - **Sitemap** — XML sitemap validation, quality gates
  92. - **Visual Analysis** — screenshots, above-the-fold, responsiveness (Playwright)
  93. - **GitHub Analyst** — metadata, topics, README, trust, title strategy
  94. - **GitHub Benchmark** — query ranking and competitor intelligence
  95. - **GitHub Data** — API/auth fallback and traffic archival continuity
  96. - **Verifier (Global)** — dedupe/contradiction suppression before final reporting
  97. ## 📚 Reference Data
  98. - Core Web Vitals thresholds (INP replaced FID)
  99. - E-E-A-T framework (Sept 2025 QRG + Dec 2025 core update)
  100. - Schema.org types — active, restricted, deprecated
  101. - Content quality gates & word count minimums
  102. - Google SEO quick reference
  103. - LLM audit rubric for consistent outputs
  104. 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.
  105. ## 🏭 Industry Templates
  106. Pre-built strategy templates for: **SaaS**, **E-commerce**, **Local Business**, **Publisher/Media**, **Agency**, and **Generic** businesses.
  107. ---
  108. ## 🔧 Installation
  109. All `--online` commands below download the latest release package from GitHub automatically. With no `--target`, `--online` installs to every supported IDE.
  110. ### Quick install (no cloning required)
  111. **Linux / macOS:**
  112. ```bash
  113. # Default: installs to every target at once
  114. curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online
  115. # Claude Code only
  116. curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target claude
  117. # User-wide (Claude + Codex)
  118. curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target global
  119. # Every target, scoped to a project
  120. curl -fsSL https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh | bash -s -- --online --target all --project-dir /path/to/your/project
  121. ```
  122. **Windows (PowerShell 7+):**
  123. ```powershell
  124. # Download installer, then run with --online
  125. irm https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.ps1 -OutFile install.ps1
  126. # Default: installs to every target at once
  127. powershell -ExecutionPolicy Bypass -File .\install.ps1 --online
  128. # Claude Code only
  129. powershell -ExecutionPolicy Bypass -File .\install.ps1 --online --target claude
  130. # Every target, scoped to a project
  131. powershell -ExecutionPolicy Bypass -File .\install.ps1 --online --target all --project-dir C:\path\to\your\project
  132. ```
  133. ### From source
  134. ```bash
  135. git clone https://github.com/Bhanunamikaze/Agentic-SEO-Skill.git
  136. cd Agentic-SEO-Skill
  137. # Claude Code (most common)
  138. bash install.sh --target claude
  139. # Codex
  140. bash install.sh --target codex
  141. # Claude Cowork / project-scoped (installs to .claude/skills/, commit to git to share with team)
  142. bash install.sh --target cowork --project-dir /path/to/your/project
  143. # GitHub Copilot Chat (writes .github/copilot-instructions.md)
  144. bash install.sh --target copilot --project-dir /path/to/your/project
  145. # Cursor AI (writes .cursor/rules/seo.mdc)
  146. bash install.sh --target cursor --project-dir /path/to/your/project
  147. # Windsurf (writes .windsurf/rules/seo.md)
  148. bash install.sh --target windsurf --project-dir /path/to/your/project
  149. # Cline (writes .clinerules)
  150. bash install.sh --target cline --project-dir /path/to/your/project
  151. # Continue.dev (writes .continue/prompts/seo.prompt)
  152. bash install.sh --target continue --project-dir /path/to/your/project
  153. # Antigravity (writes .agent/skills/seo)
  154. bash install.sh --target antigravity --project-dir /path/to/your/project
  155. # User-wide (Claude + Codex)
  156. bash install.sh --target global
  157. # All project-local IDEs at once
  158. bash install.sh --target project --project-dir /path/to/your/project
  159. # Every target at once
  160. bash install.sh --target all --project-dir /path/to/your/project
  161. # With Python deps + Playwright (for visual analysis scripts)
  162. bash install.sh --target claude --install-deps --install-playwright
  163. ```
  164. **Windows (PowerShell) — from source:**
  165. ```powershell
  166. powershell -ExecutionPolicy Bypass -File .\install.ps1 --target claude
  167. powershell -ExecutionPolicy Bypass -File .\install.ps1 --target cursor --project-dir C:\path\to\project
  168. powershell -ExecutionPolicy Bypass -File .\install.ps1 --target all --project-dir C:\path\to\project
  169. ```
  170. **Safer remote install (download, inspect, run):**
  171. ```bash
  172. curl -fsSLO https://raw.githubusercontent.com/Bhanunamikaze/Agentic-SEO-Skill/main/install.sh
  173. less install.sh # review before running
  174. bash install.sh --online
  175. ```
  176. ### All flags
  177. | Flag | Default | Purpose |
  178. |---|---|---|
  179. | `--target <name>` | `claude` | Pick a target (see IDE Compatibility table). With `--online` and no flag, defaults to `all`. |
  180. | `--project-dir <path>` | cwd | Where to install project-local targets. |
  181. | `--skill-name <name>` | `seo` | Override the installed folder name for skills-dir targets. |
  182. | `--online` | off | Fetch the latest release/branch archive from GitHub instead of using the local tree. |
  183. | `--ref <branch-or-tag>` | `main` | Branch or tag to use in `--online` mode. |
  184. | `--repo-url <url>` | upstream | Override the source repo for remote clone. |
  185. | `--source <auto\|local\|remote>` | `auto` | Force the source resolution mode. |
  186. | `--repo-path <path>` | — | Use a specific local checkout as the install source. |
  187. | `--install-deps` | off | Also `pip install --user requests beautifulsoup4`. |
  188. | `--install-playwright` | off | Also install Playwright + Chromium (for visual analysis). |
  189. | `--force` | off | Overwrite an existing installed skill. (`--online` implies `--force`.) |
  190. | `-h`, `--help` | — | Show the full usage block. |
  191. ### Python dependencies (manual)
  192. If you skipped `--install-deps`:
  193. ```bash
  194. pip install requests beautifulsoup4
  195. # Optional — for visual analysis (screenshots & layout checks):
  196. pip install playwright && playwright install chromium
  197. ```
  198. ### Verify Triggering
  199. The skill will auto-trigger when you mention SEO-related keywords in your IDE. Try:
  200. - *"Run an SEO audit on example.com"*
  201. - *"Check the schema markup on my homepage"*
  202. - *"Analyze Core Web Vitals for my site"*
  203. - *"Create an SEO plan for my SaaS product"*
  204. - *"Run GitHub SEO analysis for owner/repo"*
  205. ---
  206. ## 💬 Example Prompts (hackingdream.net)
  207. 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).
  208. ### How Prompts Route to Agents & Scripts
  209. 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.
  210. - **To run a specific test:** Ask for it specifically (e.g., "Check hreflang"). The LLM will only trigger the necessary scripts.
  211. - **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.
  212. Here's how specific phrases map to the skill's capabilities:
  213. | You type... | Scope | Agent(s) activated | Scripts used |
  214. |-------------|-------|-------------------|--------------|
  215. | "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` |
  216. | "Analyze this article" / blog post URL | 📄 Single page | **Content** + **Schema** + **Technical** | `article_seo.py`, `parse_html.py`, `readability.py` |
  217. | "Check technical SEO" | 🔧 Technical only | **Technical** | `robots_checker.py`, `security_headers.py`, `redirect_checker.py`, `parse_html.py` |
  218. | "Review content quality" / "E-E-A-T" | 📝 Content only | **Content** | `article_seo.py`, `readability.py`, `entity_checker.py` |
  219. | "Check schema markup" | 🏷️ Schema only | **Schema** | `parse_html.py`, `validate_schema.py` |
  220. | "Audit sitemap" | 🗺️ Sitemap only | **Sitemap** | `sitemap_checker.py`, `sitemap_generator.py` |
  221. | "Check page speed" / "Core Web Vitals" | ⚡ Performance only | **Performance** | `pagespeed.py` |
  222. | "Take screenshots" / "mobile check" | 📱 Visual only | **Visual** | `capture_screenshot.py`, `analyze_visual.py` |
  223. | "Check GEO readiness" / "AI search" | 🤖 GEO/AI only | **Technical** + **Content** | `llms_txt_checker.py`, `robots_checker.py`, `parse_html.py` |
  224. | "Analyze links" / "backlink profile" | 🔗 Links only | **Technical** | `link_profile.py`, `internal_links.py`, `broken_links.py` |
  225. | "Check hreflang" | 🌍 i18n only | **Technical** | `hreflang_checker.py` |
  226. | "Create SEO plan" / "SEO strategy" | 📋 Strategy | None (LLM reasoning) | `competitor_gap.py` (optional) |
  227. | "AEO analysis" / "Featured Snippets" | 🎯 AEO only | **Content** | `article_seo.py`, `parse_html.py` |
  228. | "Entity SEO" / "Knowledge Graph" | 🏛️ Entity only | **Content** + **Schema** | `entity_checker.py`, `parse_html.py` |
  229. | "Check IndexNow" | 📡 IndexNow only | **Technical** | `indexnow_checker.py` |
  230. | "Find content gaps" / "competitor analysis" | 📊 Gap analysis | None (LLM reasoning) | `competitor_gap.py` |
  231. | "Check for duplicates" / "thin content" | 📋 Dupe check | **Content** | `duplicate_content.py` |
  232. | "GSC data" / "Search Console" | 📈 GSC only | None | `gsc_checker.py` |
  233. | "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`) |
  234. ### Domain vs URL vs Blog Post — What's Different?
  235. | Input type | What happens | Example |
  236. |-----------|-------------|---------|
  237. | **Domain** (`hackingdream.net`) | Crawls multiple pages, checks robots.txt, sitemap, site-wide patterns | Full audit, link profile, sitemap check |
  238. | **URL** (`hackingdream.net/page`) | Single page deep-dive: HTML, meta, schema, content, CWV | Page audit, schema check, technical check |
  239. | **Blog post URL** | Article-specific: readability, keyword density, heading structure, JSON-LD `Article`/`BlogPosting` schema, publish date | Article analysis, AEO check |
  240. ---
  241. ### 🌐 Full Domain Audit
  242. ```text
  243. Run a full SEO audit for https://hackingdream.net and prioritize fixes by impact.
  244. ```
  245. ### 📄 Single Page / Blog Post Analysis
  246. ```text
  247. Analyze this article: https://www.hackingdream.net/2026/02/cobalt-strike-beacon-commands-red-team-field-guide.html
  248. ```
  249. ```text
  250. Do a single-page SEO analysis of https://hackingdream.net and show critical issues first.
  251. ```
  252. ### 🔧 Technical SEO
  253. ```text
  254. Analyze technical SEO for https://hackingdream.net (robots, crawlability, canonicals, redirects, headers).
  255. ```
  256. ### 📝 Content Quality & E-E-A-T
  257. ```text
  258. Review content quality and E-E-A-T signals on https://hackingdream.net and suggest concrete rewrites.
  259. ```
  260. ### 🏷️ Schema Markup
  261. ```text
  262. Check schema markup on https://hackingdream.net, validate errors, and generate corrected JSON-LD.
  263. ```
  264. ### ⚡ Performance & Core Web Vitals
  265. ```text
  266. Run Core Web Vitals analysis on https://hackingdream.net and break down LCP subparts.
  267. ```
  268. ### 🤖 GEO / AI Search Readiness
  269. ```text
  270. Evaluate GEO readiness for https://hackingdream.net (AI crawler access, llms.txt, citation structure).
  271. ```
  272. ### 🎯 Answer Engine Optimization (AEO)
  273. ```text
  274. Analyze AEO signals for https://hackingdream.net — Featured Snippet targeting, PAA optimization, Knowledge Panel readiness.
  275. ```
  276. ### 🔗 Link Profile Analysis
  277. ```text
  278. Analyze internal link structure and backlink profile for https://hackingdream.net.
  279. ```
  280. ### 🏛️ Entity SEO / Knowledge Graph
  281. ```text
  282. Check entity SEO for https://hackingdream.net — Wikidata presence, sameAs links, Knowledge Graph signals.
  283. ```
  284. ### 📊 Competitor Topic Gap
  285. ```text
  286. Find content gaps between https://hackingdream.net and competitors https://hackerone.com https://portswigger.net.
  287. ```
  288. ### 🌍 Hreflang / International SEO
  289. ```text
  290. Validate hreflang implementation on https://hackingdream.net — BCP-47 tags, bidirectional links, x-default.
  291. ```
  292. ### 📡 IndexNow
  293. ```text
  294. Check IndexNow implementation for https://hackingdream.net with key abc123def456.
  295. ```
  296. ### 📋 Topical Cluster Planning
  297. ```text
  298. Create a topical authority cluster plan for https://hackingdream.net covering cybersecurity topics.
  299. ```
  300. ### 📈 Google Search Console (requires credentials)
  301. ```text
  302. Pull GSC performance data for https://hackingdream.net and identify striking-distance keywords.
  303. ```
  304. ### 🗺️ Sitemap Audit
  305. ```text
  306. Audit sitemap quality for https://hackingdream.net and flag missing, redirected, or noindex URLs.
  307. ```
  308. ### 🖼️ Image SEO
  309. ```text
  310. Run image SEO checks for https://hackingdream.net (alt text, lazy loading, dimensions, format suggestions).
  311. ```
  312. ### 📋 Strategic SEO Plan
  313. ```text
  314. Create a 6-month SEO strategy for https://hackingdream.net with milestones and KPIs.
  315. ```
  316. ### 📱 Visual / Mobile Analysis
  317. ```text
  318. Take desktop and mobile screenshots of https://hackingdream.net and analyze above-the-fold content.
  319. ```
  320. ---
  321. ### Run Everything at Once
  322. To run **all** analysis types on a single URL:
  323. ```text
  324. Run a complete SEO audit on https://hackingdream.net — include technical, content, schema, performance,
  325. links, GEO, AEO, entity SEO, and sitemap analysis. Provide a prioritized action plan.
  326. ```
  327. Example generated outputs:
  328. - `FULL-AUDIT-REPORT.md` — comprehensive findings
  329. - `ACTION-PLAN.md` — prioritized fixes
  330. ![Example prompt and generated outputs](docs/images/example-prompt-output.png)
  331. ---
  332. ## 📊 Report Generation
  333. You can generate reports in two ways:
  334. 1. **LLM-first report in your IDE (Antigravity / Claude / Codex)** (recommended for strategy + prioritization):
  335. ```text
  336. Run a full SEO audit for https://hackingdream.net and produce a prioritized action plan with evidence for each finding.
  337. ```
  338. 2. **Interactive HTML dashboard** (recommended for shareable technical snapshots):
  339. ```bash
  340. python3 scripts/generate_report.py "https://hackingdream.net" --output seo-report-hackingdream.html
  341. ```
  342. The HTML report includes:
  343. - overall score and category breakdown
  344. - environment detection (platform/runtime inference)
  345. - environment-specific fix plan
  346. - section-level issues and recommendations
  347. - readability "what to replace" suggestions
  348. Example generated dashboard:
  349. ![SEO report dashboard example](docs/images/report-dashboard.png)
  350. ---
  351. ## ⚙️ Optional Script Workflow
  352. Use scripts when you need additional verification or structured JSON outputs.
  353. ### Credentials (`.env` file)
  354. 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:
  355. ```bash
  356. cp .env.example .env
  357. $EDITOR .env # add PAGESPEED_API_KEY, GITHUB_TOKEN, GSC_CREDENTIALS_PATH, etc.
  358. ```
  359. `.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.
  360. | Variable | Used by | How to get one |
  361. |---|---|---|
  362. | `PAGESPEED_API_KEY` | `pagespeed.py`, `generate_report.py` | [Google Cloud Console](https://console.cloud.google.com/) → enable "PageSpeed Insights API" |
  363. | `GOOGLE_KG_API_KEY` | `entity_checker.py` | Same console → enable "Knowledge Graph Search API" |
  364. | `GITHUB_TOKEN` *(or `GH_TOKEN`)* | All `github_*.py` scripts | A PAT with `public_repo` is enough; `gh auth login` works as a fallback |
  365. | `GSC_CREDENTIALS_PATH` | `gsc_checker.py`, `link_profile.py` | Path to a Google service-account JSON with Search Console access |
  366. ```bash
  367. # GitHub auth setup for repository SEO scripts (choose one)
  368. export GITHUB_TOKEN="ghp_xxx" # or: export GH_TOKEN="ghp_xxx"
  369. # or authenticate gh CLI:
  370. gh auth login -h github.com
  371. gh auth status -h github.com
  372. # Example target
  373. URL="https://example.com"
  374. # Fetch + parse HTML
  375. python3 scripts/fetch_page.py "$URL" --output /tmp/page.html
  376. python3 scripts/parse_html.py /tmp/page.html --url "$URL" --json
  377. # Core checks
  378. python3 scripts/robots_checker.py "$URL" --json
  379. python3 scripts/llms_txt_checker.py "$URL" --json
  380. python3 scripts/pagespeed.py "$URL" --strategy mobile --json
  381. python3 scripts/security_headers.py "$URL" --json
  382. python3 scripts/redirect_checker.py "$URL" --json
  383. python3 scripts/social_meta.py "$URL" --json
  384. python3 scripts/sitemap_checker.py "$URL" --json
  385. python3 scripts/crawl_audit.py "$URL" --max-pages 50 --json
  386. python3 scripts/indexability_matrix.py --site "$URL" --json
  387. python3 scripts/canonical_checker.py "$URL" --json
  388. python3 scripts/x_robots_header_checker.py "$URL" --json
  389. # Content + structure checks
  390. python3 scripts/readability.py /tmp/page.html --json
  391. python3 scripts/internal_links.py "$URL" --depth 1 --max-pages 20 --json
  392. python3 scripts/broken_links.py "$URL" --workers 5 --json
  393. python3 scripts/article_seo.py "$URL" --json
  394. python3 scripts/image_inventory.py /tmp/page.html --json
  395. python3 scripts/a11y_seo_checker.py /tmp/page.html --json
  396. python3 scripts/url_quality.py "$URL" --json
  397. # New analysis scripts
  398. python3 scripts/hreflang_checker.py "$URL" --json
  399. python3 scripts/entity_checker.py "$URL" --json
  400. python3 scripts/duplicate_content.py "$URL" --json
  401. python3 scripts/link_profile.py "$URL" --json
  402. python3 scripts/competitor_gap.py "$URL" --competitor https://competitor.com --json
  403. python3 scripts/faceted_nav_audit.py "$URL" --json
  404. python3 scripts/ai_crawler_policy_matrix.py "$URL" --json
  405. python3 scripts/llms_txt_generator.py "$URL" "$URL" --title "Example Site" --description "Example site summary." --json
  406. # python3 scripts/gsc_checker.py "$URL" --credentials creds.json --json # requires GSC credentials
  407. # python3 scripts/indexnow_checker.py "$URL" --key YOUR_KEY --json # requires IndexNow key
  408. # GitHub repository SEO scripts (provider fallback: auto|api|gh)
  409. python3 scripts/github_repo_audit.py --repo owner/repo --provider auto --json
  410. python3 scripts/github_readme_lint.py README.md --json
  411. python3 scripts/github_community_health.py --repo owner/repo --provider auto --json
  412. # Provide query/competitor inputs from LLM/web-search discovery when possible:
  413. python3 scripts/github_search_benchmark.py --repo owner/repo --query "<llm_or_web_query>" --provider auto --json
  414. python3 scripts/github_competitor_research.py --repo owner/repo --query "<llm_or_web_query>" --provider auto --top-n 6 --json
  415. python3 scripts/github_competitor_research.py --repo owner/repo --competitor owner/repo --competitor owner/repo --provider auto --json
  416. python3 scripts/github_traffic_archiver.py --repo owner/repo --provider auto --archive-dir .github-seo-data --json
  417. # github_seo_report.py auto-derives repo-specific benchmark queries if none are provided
  418. python3 scripts/github_seo_report.py --repo owner/repo --provider auto --markdown GITHUB-SEO-REPORT.md --action-plan GITHUB-ACTION-PLAN.md --json
  419. # Optional: tune auto-derived query count (default: 6)
  420. # 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
  421. # Generic verifier stage (can be used by any workflow before final reporting)
  422. python3 scripts/finding_verifier.py --findings-json raw-findings.json --json
  423. ```
  424. Generate a single HTML dashboard if needed:
  425. ```bash
  426. python3 scripts/generate_report.py "$URL"
  427. ```
  428. ---
  429. ## 🛡️ Critical Rules Enforced
  430. | Rule | Detail |
  431. |------|--------|
  432. | **INP not FID** | FID removed Sept 2024. INP is the sole interactivity metric. |
  433. | **FAQ schema restricted** | FAQPage only for government/healthcare authority sites (Aug 2023) |
  434. | **HowTo deprecated** | Rich results removed Sept 2023 |
  435. | **JSON-LD only** | Never recommend Microdata or RDFa |
  436. | **E-E-A-T everywhere** | Applies to ALL competitive queries since Dec 2025 |
  437. | **Mobile-first complete** | 100% mobile-first indexing since July 2024 |
  438. | **Location page limits** | ⚠️ Warning at 30+ pages, 🛑 Hard stop at 50+ |
  439. ---
  440. ## 📋 Requirements
  441. | Requirement | Version |
  442. |-------------|---------|
  443. | Python | 3.8+ |
  444. | `requests` | Any |
  445. | `beautifulsoup4` | Any |
  446. | Playwright | Optional (for visual analysis) |
  447. ---
  448. ## 🙏 Credits
  449. This project was originally inspired by **[claude-seo](https://github.com/AgriciDaniel/claude-seo)** by **[AgriciDaniel](https://github.com/AgriciDaniel)**.
  450. 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/`).
  451. ---
  452. ## 📄 License
  453. Licensed under the MIT License. See [LICENSE](LICENSE).
  454. 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 in

Free to use. If it’s helped, pass it on.