Skip to content
Back to search

seo-audit-skill

SkillWorks with Claude CodeGitHub

SEO agent skill for OpenClaw,Claude Code, and AI agents. Generate beginner SEO audits and advanced technical SEO reports for any page.

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/jeffli1993--seo-audit-skill/badge.svg)](/listings/jeffli1993--seo-audit-skill)

HTML

<a href="/listings/jeffli1993--seo-audit-skill"><img src="/api/listings/jeffli1993--seo-audit-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.

**Option 1: CLI (Recommended)**

npx skills add JeffLi1993/seo-audit-skill

# Or install a specific tier
npx skills add JeffLi1993/seo-audit-skill --skill seo-audit
npx skills add JeffLi1993/seo-audit-skill --skill seo-audit-full

**Option 2: Claude Code Plugin**

/plugin marketplace add JeffLi1993/seo-audit-skill
/plugin install seo-audit-skill

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.

README.md · README · 209 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # seo-audit-skill
  2. **English** · [中文](README.zh.md) · [SEO Audit Agent Skill](https://nanoskill.ai/skills/seo-audit)
  3. Reusable Agent Skills for single-page SEO auditing. Give it a URL — get a structured HTML report with actionable findings.
  4. Built on a **Script + LLM two-layer architecture**: Python scripts handle deterministic checks (HTTP status, XML parsing, string matching), while the LLM handles semantic judgment (keyword intent, content quality, page type inference). Works with Claude Code, Cursor, and any agent runtime that supports SKILL.md.
  5. ## Best practices
  6. 1. Run `npx skills add JeffLi1993/seo-audit-skill`, then audit your page (for example: `audit this page: https://example.com`). Open the report at `reports/<hostname>-audit.html` and review it yourself: keep what matters for your goals, skip what does not.
  7. 2. Share the report (or the key sections) with Cursor or Claude Code and have the assistant work through the findings and fixes item by item.
  8. ---
  9. ## Report Output
  10. Each basic audit produces a standalone HTML report saved to `reports/<hostname>-audit.html`.
  11. Full audits save to `reports/<hostname>-full-audit.html`.
  12. | Section | What you get |
  13. |---|---|
  14. | **Audit Summary** | One-line verdict + critical / warnings / passing at a glance |
  15. | **Site Checks** | Sitemap URL Inventory · Crawlability · URL Canonicalization · i18n · Schema · E-E-A-T |
  16. | **Page Speed** | Full only — Lighthouse scores, lab metrics, final URL, screenshot availability |
  17. | **Page Checks** | TDK · H1 · Headings · Word Count · Internal Links · Social Tags |
  18. | **Priority Actions** | Top 3 highest-impact fixes, ranked |
  19. | **Insight Walkthrough** | Evidence → Impact → Fix for each major finding |
  20. ```
  21. audit this page: https://openclaw.ai
  22. → ✅ Report saved → reports/openclaw-ai-audit.html
  23. ```
  24. | Website | Audit Summary | Site Checks | Page Checks & insights |
  25. |---|---|---|---|
  26. | colaos.ai | <img src="assets/0-0.png" alt="Audit Summary" width="240" /> | <img src="assets/0-1.png" alt="Site Checks" width="240" /> | <img src="assets/0-2.png" alt="Page Checks and insights" width="240" /> |
  27. ---
  28. ## Skills
  29. | Skill | Tier | When to use |
  30. |---|---|---|
  31. | `seo-audit` | Basic | Default — give it a URL, get a 20+ check structured report |
  32. | `seo-audit-full` | Full | Deep audit with PageSpeed, sitemap inventory, social tags, content quality, GSC data, competitor gap |
  33. > `seo-audit-full` requires a Google PageSpeed Insights API key for PageSpeed checks. Set `PAGESPEED_API_KEY` / `GOOGLE_PAGESPEED_API_KEY`, or pass `--api-key`; without a key, the full audit stops and asks you to configure one.
  34. ---
  35. ## Audit Coverage
  36. ### Site-level
  37. | Check | What it verifies | Basic | Full |
  38. |---|---|:---:|:---:|
  39. | Sitemap URL Inventory | Standalone table of top sitemap directories: URL count, page type, representative example URL | — | ✅ |
  40. | Staging Subdomain Indexation | Detects public `test.`, `staging.`, `dev.`, `preview.`, `beta.`, `uat.` hosts that mirror production and may be indexable | — | ✅ |
  41. | robots.txt | RFC 9309 group parsing, Allow/Disallow logic, Googlebot status, Sitemap directives | ✅ | ✅ |
  42. | sitemap.xml | Valid XML, URL count, follows Sitemap directive path from robots.txt, samples child sitemap URLs when needed | ✅ | ✅ |
  43. | 404 Handling | True 404 vs soft 404 (200) vs redirect-to-homepage (301) | ✅ | ✅ |
  44. | URL Canonicalization | HTTP→HTTPS redirect, www consistency, trailing slash, canonical tag match | ✅ | ✅ |
  45. | i18n / hreflang | Reciprocal symmetry, BCP 47 codes, x-default, default-language URL duplication, canonical/hreflang alignment | ✅ | ✅ |
  46. | Schema (JSON-LD) | Parseability, @type detection, required/recommended fields, nested fields, type conflicts, localized schema language/URL alignment | ✅ | ✅ |
  47. | E-E-A-T Trust Pages | About / Contact / Privacy / Terms — exists (HTTP 200) + reachable from footer/nav | ✅ | ✅ |
  48. | GSC Crawl Status | Index coverage, crawl errors, blocked resources | — | ✅ |
  49. | PageSpeed / Lighthouse | Performance · Accessibility · Best Practices · SEO scores, lab metrics, final URL, screenshot availability | — | ✅ |
  50. `Sitemap URL Inventory` is intentionally rendered as its own table before Crawlability:
  51. | Directory | URL Count | Page Type | Example Page |
  52. |---|---:|---|---|
  53. | `/blog/` | 300 | Blog / Content Pages | `https://xx.ai/blog/best-ai-video-tools` |
  54. | `/tools/` | 80 | Tool Pages | `https://xx.ai/tools/image-generator` |
  55. | `/alternatives/` | 40 | Alternative / Competitor Pages | `https://xx.ai/alternatives/synthesia` |
  56. Use it as a site-level map, then choose representative URLs from important directories for deeper full audits.
  57. ### Page-level
  58. | Check | What it verifies | Basic | Full |
  59. |---|---|:---:|:---:|
  60. | URL Slug | Lowercase, hyphenated, keyword present, stop word & stuffing detection | ✅ | ✅ |
  61. | Title Tag | 50–60 chars, keyword position, homepage vs inner page rules | ✅ | ✅ |
  62. | Meta Description | 120–160 chars, keyword match, concrete value prop (not generic fluff) | ✅ | ✅ |
  63. | H1 Tag | Single H1, keyword match (full / partial / none), semantic intent review | ✅ | ✅ |
  64. | Canonical Tag | Self-referencing, matches final URL after redirects | ✅ | ✅ |
  65. | Image Alt Text | Alt attribute check on all `<img>`, JS-render detection | ✅ | ✅ |
  66. | Word Count | Body text ≥ 500 words, thin content flag | ✅ | ✅ |
  67. | Keyword Placement | Primary keyword within first 100 body words | ✅ | ✅ |
  68. | Heading Structure | H2 count (target 5–7), H3/H2 ratio, keyword distribution in H2s | ✅ | ✅ |
  69. | Internal Links | Same-origin links (excl. nav/footer), equity distribution | ✅ | ✅ |
  70. | OG / Social Tags | og:image, twitter:card, social preview completeness | — | ✅ |
  71. | Content Quality | E-E-A-T depth, readability, specificity vs competitors | — | ✅ |
  72. | Robots Meta | noindex, nofollow, max-snippet directives | — | ✅ |
  73. ---
  74. ## Structure
  75. ```
  76. seo-audit-skill/
  77. ├── seo-audit/
  78. │ ├── SKILL.md # Skill definition + agent workflow
  79. │ ├── references/REFERENCE.md # Field definitions, edge cases
  80. │ ├── assets/report-template.html # HTML output template
  81. │ └── scripts/
  82. │ ├── check-site.py # robots.txt + sitemap → JSON
  83. │ ├── check-page.py # TDK + H1 + canonical + slug → JSON
  84. │ ├── check-schema.py # JSON-LD extraction + validation → JSON
  85. │ └── fetch-page.py # Raw HTML fetcher, SSRF protection
  86. └── seo-audit-full/
  87. ├── SKILL.md
  88. ├── references/REFERENCE.md
  89. ├── assets/report-template.html
  90. └── scripts/
  91. ├── check-site.py # staging + sitemap inventory + robots/sitemap → JSON
  92. ├── check-pagespeed.py # PageSpeed Insights / Lighthouse → JSON
  93. ├── check-social.py # OG + Twitter Card validation → JSON
  94. └── check-schema.py # JSON-LD quality + localized schema validation → JSON
  95. ```
  96. ---
  97. ## Architecture: Script + LLM
  98. ```
  99. URL
  100. │
  101. ▼
  102. ┌──────────────────────────────────────────────────┐
  103. │ Layer 1 · Python Scripts │
  104. │ Deterministic checks → structured JSON │
  105. │ │
  106. │ check-site.py sitemap inventory, staging │
  107. │ check-page.py H1 / title / meta / canonical│
  108. │ check-schema.py JSON-LD fields + localization│
  109. │ fetch-page.py raw HTML + SSRF protection │
  110. └───────────────────────┬──────────────────────────┘
  111. │ JSON + llm_review_required flag
  112. ▼
  113. ┌──────────────────────────────────────────────────┐
  114. │ Layer 2 · LLM Agent │
  115. │ Semantic judgment on flagged fields only │
  116. │ │
  117. │ · Keyword intent alignment (H1 / title) │
  118. │ · Meta description quality & specificity │
  119. │ · Page type → expected Schema @type mapping │
  120. │ · E-E-A-T trust page reachability (footer/nav) │
  121. │ · Content analysis (word count, heading, links) │
  122. └───────────────────────┬──────────────────────────┘
  123. │
  124. ▼
  125. report-template.html
  126. → reports/<hostname>-audit.html
  127. ```
  128. **Why two layers?** Scripts handle the 80% of checks that are deterministic — does `robots.txt` exist? Is the title 55 characters? The LLM handles the 20% that require understanding — does this H1 semantically cover the intent of "AI workflow automation"? The `llm_review_required` flag ensures the LLM only intervenes when the script explicitly cannot make the call. No hallucination on factual checks, no blind spots on semantic ones.
  129. ---
  130. ## Installation
  131. **Option 1: CLI (Recommended)**
  132. ```bash
  133. npx skills add JeffLi1993/seo-audit-skill
  134. # Or install a specific tier
  135. npx skills add JeffLi1993/seo-audit-skill --skill seo-audit
  136. npx skills add JeffLi1993/seo-audit-skill --skill seo-audit-full
  137. ```
  138. **Option 2: Claude Code Plugin**
  139. ```bash
  140. /plugin marketplace add JeffLi1993/seo-audit-skill
  141. /plugin install seo-audit-skill
  142. ```
  143. ## Usage
  144. ```
  145. audit this page: https://example.com
  146. ```
  147. ---
  148. ## Scripts
  149. All scripts output structured JSON to stdout. Exit code `0` = pass/warn, `1` = any fail.
  150. | Script | What it does |
  151. |---|---|
  152. | `check-site.py` | robots.txt + sitemap + sitemap inventory — RFC 9309 parsing, staging subdomain checks, top directory grouping |
  153. | `check-page.py` | H1 / title / meta / canonical / URL slug — keyword match with stop-word-aware filter |
  154. | `check-schema.py` | JSON-LD extraction, @graph flattening, @type + required field validation, localized schema alignment |
  155. | `fetch-page.py` | Raw HTML fetch — SSRF protection, redirect chain tracking, Googlebot UA option |
  156. | `check-pagespeed.py` | Full only — PageSpeed Insights / Lighthouse scores and lab metrics; requires API key |
  157. | `check-social.py` | Full only — OG tags + Twitter Card validation |
  158. **Dependency:** `pip install requests`
  159. ---
  160. ## License
  161. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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