seo
"Website SEO done as shipped, verified fixes: technical audits, indexing problems, Core Web Vitals, titles/meta, content refreshes, JSON-LD schema, local SEO (Google Business Profile, clinics, colleges, multi-location), internal linking, hreflang, migrations and redirects, robots.txt and AI-crawler policy, AI search visibility (ChatGPT, Perplexity, Google AI Overviews / GEO), compliant link earning, traffic-drop diagnosis and Search Console reporting. Bundles zero-dependency, tested scripts (crawler, page checker, robots tester, schema validator, CWV, redirect verifier) that run on free data. Use whenever the user mentions SEO, rankings, Google or Bing traffic, pages not indexed, Search Console, sitemaps, robots.txt, canonicals, schema, page speed for search, getting cited by AI assistants, or launching, migrating or redesigning a public site, even without saying 'SEO'. Not for paid ads, app-store optimization, YouTube growth, or in-app search engines."
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/boobal-official--claude-seo-skill)HTML
<a href="/listings/boobal-official--claude-seo-skill"><img src="/api/listings/boobal-official--claude-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.
Claude Code loads skills from `~/.claude/skills/` (all projects) or `.claude/skills/` (one project).
# macOS / Linux / Git Bash git clone https://github.com/boobal-official/claude-seo-skill ~/.claude/skills/seo
# Windows PowerShell git clone https://github.com/boobal-official/claude-seo-skill "$env:USERPROFILE\.claude\skills\seo"
Restart Claude Code (or start a new session). The skill triggers automatically on SEO requests (rankings, indexing, Search Console, robots.txt, schema, Core Web Vitals, migrations, AI-search visibility...). Requires Node.js 18+ for the scripts. Update with `git pull` in that folder.
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 · 156 lines
- ---
- name: seo
- description: "Website SEO done as shipped, verified fixes: technical audits, indexing problems, Core Web Vitals, titles/meta, content refreshes, JSON-LD schema, local SEO (Google Business Profile, clinics, colleges, multi-location), internal linking, hreflang, migrations and redirects, robots.txt and AI-crawler policy, AI search visibility (ChatGPT, Perplexity, Google AI Overviews / GEO), compliant link earning, traffic-drop diagnosis and Search Console reporting. Bundles zero-dependency, tested scripts (crawler, page checker, robots tester, schema validator, CWV, redirect verifier) that run on free data. Use whenever the user mentions SEO, rankings, Google or Bing traffic, pages not indexed, Search Console, sitemaps, robots.txt, canonicals, schema, page speed for search, getting cited by AI assistants, or launching, migrating or redesigning a public site, even without saying 'SEO'. Not for paid ads, app-store optimization, YouTube growth, or in-app search engines."
- ---
- # SEO
- Make a website earn more search traffic that converts, from Google, Bing, and AI assistants:
- find what blocks it, fix it in the code or content, and prove each fix worked with before/after
- evidence. A report with no shipped change is not the deliverable; neither is a change with no proof.
- ## Principles (and why)
- - **Fix the blocker before the polish.** A perfect title on a page Bing cannot crawl earns
- nothing. Work in severity order on the pages that make money first.
- - **Evidence over memory.** Search engines change often (several 2025-2026 changes are recorded in
- `references/thresholds.md`). Measure the live site, read the repo, and re-check time-sensitive
- facts at the official URLs listed there. If you cannot verify something, say "not verified".
- - **Never invent facts.** No made-up statistics, prices, reviews, credentials, or quotes. Missing
- facts become `[NEEDS FACT: ...]` items for the owner.
- - **Free data first.** Everything works with the live site, the repo, Search Console/Bing exports,
- PageSpeed Insights, and web search. Paid SEO tools are optional if the user already has them; never recommend buying one.
- - **Stay inside search engine spam policies.** No link buying, cloaking, doorway pages, fake
- reviews, or scaled thin pages: they get sites penalised or ignored, and recovery is slow.
- - **Ask before irreversible, policy, or external actions** (list in Step 4).
- ## Step 1: Intake (short; infer what you can)
- 1. **Site URL** (or a local production build) and **goal**: audit, a specific problem, a page to rank, launch/migration, local, AI visibility, traffic drop.
- 2. **Money pages and conversion**: pricing, admissions, booking, product, contact. These get priority.
- 3. **Repo and stack**: `node <skill-dir>/scripts/repo-audit.mjs <repo>`.
- 4. **Data available**: GSC/Bing exports or access, analytics, a PSI API key, any paid SEO tool.
- If something is missing, proceed with what exists and note the gap once; do not block.
- `<skill-dir>` is this skill's base directory (shown when the skill loads). Scripts need only
- Node >= 18 and run from anywhere. Flags may come in any order; `--json` gives machine-readable
- output (always valid JSON, even on errors).
- ## Step 2: Route the task
- | Task | Read | Run |
- |---|---|---|
- | Full audit / "why don't we rank" | `references/technical-audit.md` | `repo-audit`, `robots-check`, `crawl-site`, `seo-check --deep`, `seo-check --bots` (separate run; ask first behind a WAF/CDN bot shield), `cwv` |
- | Traffic dropped | `measurement.md` (drop diagnosis) then `technical-audit.md` | `crawl-site`, `robots-check` |
- | Pages not indexed / GSC errors | `technical-audit.md`, `measurement.md` | `crawl-site`, `seo-check --deep` |
- | Page speed, Core Web Vitals | `core-web-vitals.md` | `cwv` |
- | Titles, meta, headings, intent, refresh a post | `on-page.md` | `seo-check`, `crawl-site` |
- | Content quality, E-E-A-T, AI writing cleanup, AI search / GEO | `content-and-ai-search.md` | `slop-check`, `seo-check --bots` (ask first behind a WAF/CDN bot shield) |
- | Schema / rich results | `structured-data.md` | `seo-check` |
- | Local, Google Business Profile, multi-location, clinics, colleges | `local-seo.md` + `structured-data.md` | `seo-check`, `crawl-site --money "^/locations/"` |
- | Internal links, orphans, site structure | `internal-linking.md` | `crawl-site --money ...` |
- | Multilingual / hreflang | `international.md` | `seo-check --deep` |
- | Domain move, rebrand, URL changes, replatform | `migrations.md` | `verify-redirects`, `crawl-site`, `robots-check` |
- | robots.txt, AI bots, blocking scrapers | `crawler-policy.md` | `robots-check`, `seo-check --bots` (ask first behind a WAF/CDN bot shield) |
- | Backlinks, PR, outreach, directories | `off-page.md` | - |
- | Keyword research, competitors, content plan | `research.md` | - |
- | Search Console, logs, reporting, IndexNow, Discover | `measurement.md` | `indexnow` (dry run first) |
- | Next.js / WordPress / Shopify / static / SPA specifics | `stacks.md` | `repo-audit` |
- Every threshold, limit, and time-sensitive policy fact lives in `references/thresholds.md` (the
- scripts read the same values from `scripts/thresholds.mjs`; the test suite fails if they drift).
- Workflow rules of thumb stay in the guide that uses them and are labelled as heuristics.
- ## Step 3: Prioritise
- Severity scale (defined in `thresholds.md`): FATAL, HIGH, MEDIUM, LOW, INFO. Order work by severity x page value:
- ```
- FATAL on any page that matters -> fix now
- HIGH on money / high-traffic pages -> fix now
- HIGH elsewhere, MEDIUM on money -> this change if under ~1 hour, else top of the roadmap
- MEDIUM elsewhere -> roadmap with owner
- LOW -> one batched line at the bottom; skip while FATAL/HIGH remain
- ```
- Script output is evidence, not a verdict. Confirm intent before "fixing": a `noindex` on a login
- page, a canonical on a true duplicate, or an owner-approved AI-bot block is correct.
- ## Step 4: Change and verify
- **Before** changing anything, run the check that found the issue and save its `--json` output
- under `seo/evidence/YYYY-MM-DD/` (the "before"). Make the change the way the repo already works (its routing, metadata helpers, CMS).
- Then re-run the same check (the "after"). Pass conditions:
- | Change | Proof (after) |
- |---|---|
- | robots.txt | `robots-check.mjs <origin>`: no FATAL; any remaining HIGH is a block the owner approved |
- | noindex / canonical / title / meta / schema | `seo-check.mjs <url> --deep` shows the new values and no issue code for it |
- | soft 404 | `crawl-site.mjs` no `soft-404`; `curl -s -o /dev/null -w "%{http_code}" <origin>/zzz-test` prints 404 |
- | redirects / http->https / host | `verify-redirects.mjs map.csv` "0 failed"; `crawl-site.mjs` no `http-not-redirected` / `host-duplicate` / `url-variant-duplicate` |
- | sitemap | `crawl-site.mjs` no `sitemap-*` codes |
- | hreflang | `seo-check.mjs <url> --deep` no `hreflang-*` codes on every language version |
- | bot access (WAF/UA rules) | `seo-check.mjs <url> --bots` status 200 for search + AI-search bots |
- | internal links | `crawl-site.mjs --money ...`: no `money-underlinked`/`orphan-pages`, or each remaining one explained |
- | rendering / content | `seo-check.mjs`: no `client-rendered`; the page's key facts (price, H1, main text) appear in the raw-HTML output |
- | structured data | `seo-check.mjs`: no `jsonld-parse-error`/`schema-missing-required`; the owner confirms in the Rich Results Test (no public API) |
- | CWV | `cwv.mjs` lab before vs after (field data lags; say so) |
- | copy cleanup | `slop-check.mjs` 0 hits, or each remaining hit justified |
- | NAP / local | `seo/local/nap-audit.md` shows every source matching; `seo-check.mjs` shows the same name/address/phone in JSON-LD and page text |
- | IndexNow | `indexnow.mjs ... --submit --json` returns `"ok": true` (after approval) |
- | AI-features opt-out | owner confirms Settings > Search generative AI shows Exclude on the right property; the Generative AI performance report trends to zero over the following days |
- Also run the repo's lint/typecheck/build. Not deployed yet: verify against the local production
- build and say that production still needs checking after deploy.
- **Ask the user first** before: noindexing, deleting, or redirecting pages that have traffic or
- backlinks; any robots.txt/WAF change that blocks a search engine, an AI search bot, or AI training
- bots (a policy decision); opting out of Google's AI features; dropping a locale; changing URLs at
- scale; submitting anything externally (IndexNow, sitemaps via APIs, directories, disavow files,
- Search Console Change of Address, Bing Site Move); running `seo-check --bots` against a production
- site behind a WAF/CDN bot shield (spoofed crawler user agents from the user's IP can get that IP
- rate-limited or banned). **Never**: send emails or messages, post to
- social or forums, create accounts, buy anything, or write reviews. Draft them for the owner.
- ## Step 5: Report (always this shape)
- ```markdown
- ## SEO: <site> (<date>)
- Verdict: <one plain sentence: the biggest thing holding the site back>
- ### Shipped (verified)
- | Change | File/URL | Before | After (proof command -> result) |
- ### Roadmap
- | # | Severity | Page(s) | Issue | Why it costs traffic/revenue | Fix | How the owner can verify (no skill needed) | Status |
- Every finding gets an owner-runnable check: a `curl` line, a Search Console/Bing report, or a
- browser view-source step, in addition to any script command.
- ### Needs from you
- - <max 3: access, facts marked NEEDS FACT, approvals>
- ### Not verified
- - <anything you could not measure, and what would verify it>
- ```
- Save it as `seo/reports/YYYY-MM-DD-<type>.md` in the repo when there is one. For ongoing work keep
- state in `seo/` (`measurement.md` lists the files) so the next run starts where this one stopped.
- ## Script reference
- | Script | Purpose |
- |---|---|
- | `scripts/repo-audit.mjs [dir]` | stack detection + source-level issues (env noindex, soft-404-prone routes, client-fetched content, missing metadata/sitemap/robots, SEO plugin conflicts) |
- | `scripts/robots-check.mjs <origin> [paths]` / `--file robots.txt [paths]` | RFC 9309 / Google-parser matching for search, AI-search, user-triggered and training bots (list in `scripts/robots.mjs`); render-asset blocks; sitemap lines; `--offline` skips sitemap fetches |
- | `scripts/crawl-site.mjs <origin> [--max N] [--max-sitemap N] [--concurrency N] [--sitemap URL] [--money REGEX] [--out f]` | link crawl + sitemaps: soft 404, broken links, chains, sitemap hygiene, duplicates, near-duplicates, depth, orphans, contextual in-links, URL variants, OG/favicon, production-host leaks, page issues rolled up |
- | `scripts/seo-check.mjs <url> [--deep] [--ua preset]` | one page as raw HTML: status, chain, robots directives, canonical, title/meta/H1, hreflang, JSON-LD validation, rendering, Googlebot HTML size limit (`thresholds.md`); `--deep` also fetches canonical/hreflang/og:image targets |
- | `scripts/seo-check.mjs <url> --bots` | separate mode: what a browser, Googlebot, Bingbot and AI bots each receive |
- | `scripts/cwv.mjs <url> [--strategy mobile\|desktop] [--local] [--from-json f]` | CWV field + lab via PageSpeed Insights; `--local` = Lighthouse on this machine (ask first) |
- | `scripts/verify-redirects.mjs map.csv [--http-max-hops N]` | 1-hop 301/308 to the mapped URL, final 200, http variants |
- | `scripts/slop-check.mjs <files>` | AI-writing tells in copy (skips code and frontmatter) |
- | `scripts/indexnow.mjs --host h --key k <urls> [--file f] [--submit]` | IndexNow ping (Bing and others); dry run unless `--submit` |
- | `scripts/tests/run-tests.mjs [--network]` | self-test against local fixture sites; run after editing any script |
- Exit codes (all scripts): 2 = FATAL found, 1 = HIGH found, 0 = otherwise, 3 = could not complete
- (network, quota, internal error: report "not measured", never guess), 64 = usage error.
- `cwv`: 2 = a field metric poor, 1 = needs improvement, 0 = good or no field data, 3 = not measured.
- Network safety: when the audited site is public, the scripts refuse requests to private, loopback
- and link-local addresses (e.g. cloud metadata endpoints) that a hostile site could point them at via
- sitemaps, og:image or redirects; `--allow-private` overrides. Output from pages is sanitised before printing.
- Residual risk: the check resolves hostnames before Node's fetch resolves them again, so a DNS-rebinding
- attacker could still switch addresses in between; run audits of untrusted sites from a machine without
- sensitive internal services if that matters.
- `verify-redirects`: 1 = a row failed. `slop-check`: 1 = hits remain. `indexnow`: 1 = key file or submission failed.
- With `--json` every script prints valid JSON, including on usage and internal errors; those carry
- severity INFO (a typo or an unreachable network is not a site defect) and the exit code (64 / 3) says what happened.
README.md · README · 135 lines
- # SEO skill for Claude Code
- An agent skill that does website SEO the way a senior technical SEO would: find what blocks
- traffic, fix it in the code or content, and **prove each fix worked** with before/after evidence.
- It runs on free data (your live site, your repo, Search Console/Bing exports, PageSpeed Insights)
- and ships with zero-dependency, tested Node.js scripts.
- ```
- "Audit https://example.com and tell me why we get no traffic from Bing and ChatGPT"
- "Fix the SEO problems in this Next.js repo before launch"
- "Our admissions pages aren't indexed. Find out why."
- "We're moving blog.example.com to example.com/blog. Plan the redirects and verify them."
- ```
- ## Why this skill
- | | |
- |---|---|
- | **Ships changes, not PDFs** | Every workflow ends in edited files plus a proof command (and a check the site owner can run without the skill: `curl`, Search Console, view-source). |
- | **Current to 2026** | Facts that changed recently are recorded with official links to re-check: FAQ rich results retired (May 2026), Googlebot's 2 MB HTML limit, the Search Console AI Overviews / AI Mode control, ChatGPT-User and robots.txt, Next.js streaming metadata, AIPREF status. |
- | **One source of truth** | Every threshold and policy fact lives in `references/thresholds.md`; the scripts read the same values from `scripts/thresholds.mjs`, and the test suite fails if they drift. |
- | **Free data first** | No paid SEO tool required, none recommended, no affiliate links. If you already have Ahrefs/Semrush/DataForSEO, it can use them. |
- | **Safe by default** | Asks before noindexing, redirecting, blocking any crawler, or submitting anything externally. Never sends emails, buys links, or writes reviews. No cloaking, no prompt-injection tricks. Stays inside Google's spam policies. |
- | **Tested tooling** | 285 automated tests against local fixture sites with planted defects, a clean site that must stay clean, and edge cases from four rounds of adversarial code review. CI runs them on Windows, macOS and Linux with Node 18, 20 and 22. |
- | **Safe to point at untrusted sites** | SSRF protection (no requests to private/loopback/cloud-metadata addresses, incl. IPv4-mapped IPv6 forms, when auditing a public site; DNS rebinding documented as a residual risk), gzip-bomb and size caps, linear-time parsing, and terminal-escape sanitising of page content. |
- ## Install
- Claude Code loads skills from `~/.claude/skills/` (all projects) or `.claude/skills/` (one project).
- ```bash
- # macOS / Linux / Git Bash
- git clone https://github.com/boobal-official/claude-seo-skill ~/.claude/skills/seo
- ```
- ```powershell
- # Windows PowerShell
- git clone https://github.com/boobal-official/claude-seo-skill "$env:USERPROFILE\.claude\skills\seo"
- ```
- Restart Claude Code (or start a new session). The skill triggers automatically on SEO requests
- (rankings, indexing, Search Console, robots.txt, schema, Core Web Vitals, migrations, AI-search
- visibility...). Requires Node.js 18+ for the scripts. Update with `git pull` in that folder.
- ## What's inside
- ```
- SKILL.md router: intake -> route -> prioritise -> change + verify -> report
- references/
- thresholds.md every number, limit and time-sensitive policy fact (+ official links)
- technical-audit.md crawl, index, render, canonicals, soft 404s, programmatic pages
- core-web-vitals.md LCP / INP / CLS diagnosis and stack fixes
- on-page.md intent, titles, meta, headings, content refresh
- content-and-ai-search.md helpful content, E-E-A-T/YMYL, answer-first structure, AI visibility
- structured-data.md JSON-LD templates (Organization, LocalBusiness, Product/merchant, Article...)
- local-seo.md Google Business Profile, NAP, location pages, clinics, colleges
- internal-linking.md architecture, click depth, orphans, contextual links
- international.md hreflang and locale strategy
- migrations.md domain moves, redirect maps, cutover, monitoring
- off-page.md link earning inside spam policies, outreach drafts
- crawler-policy.md search vs AI-search vs training bots, robots.txt templates, bot verification
- measurement.md Search Console, Bing, traffic-drop diagnosis, logs, reporting
- stacks.md Next.js (App/Pages Router, 15/16), WordPress, Shopify, static, SPA
- research.md free keyword and competitor research
- scripts/ Node.js >= 18, no npm install
- crawl-site.mjs link crawl + sitemaps: soft 404, broken links, chains, sitemap hygiene,
- duplicates, near-duplicates, depth, orphans, contextual in-links
- seo-check.mjs one page as raw HTML (what non-JS crawlers see); --deep, --bots
- robots-check.mjs RFC 9309 / Google-parser matching for search, AI-search and training bots
- repo-audit.mjs source-level issues before deploy (Next.js, WordPress, SPA)
- cwv.mjs Core Web Vitals via PageSpeed Insights (field + lab)
- verify-redirects.mjs 1-hop 301/308 verification for migrations
- slop-check.mjs AI-writing tells in copy
- indexnow.mjs IndexNow ping (dry run unless --submit)
- tests/run-tests.mjs self-test suite
- ```
- Use the scripts directly too:
- ```bash
- node scripts/robots-check.mjs https://example.com /pricing
- node scripts/crawl-site.mjs https://example.com --max 300 --money "^/(pricing|admissions)" --out seo/crawl.json
- node scripts/seo-check.mjs https://example.com/pricing --deep
- node scripts/repo-audit.mjs ./my-next-app
- ```
- Exit codes: `2` FATAL found, `1` HIGH found, `0` otherwise, `3` could not complete (network/quota),
- `64` usage error. Add `--json` for machine-readable output.
- ## How it was evaluated
- The skill was built and improved over five review rounds against a fixed rubric
- ([docs/RUBRIC.md](docs/RUBRIC.md)), scored by independent reviewer agents that had not seen the
- author's reasoning. One reviewer checked every factual claim against official documentation; a
- second hunted for script bugs by running crafted inputs. Each round's findings were fixed and
- re-verified. Details: [docs/EVALUATION.md](docs/EVALUATION.md).
- | Dimension | v1 | final |
- |---|---|---|
- | Accuracy (current to Nov 2026) | 5 | 10 |
- | Ships verified changes | 8 | 10 |
- | Works with zero paid tools | 9 | 10 |
- | Coverage | 7 | 10 |
- | Safety & neutrality | 8 | 10 |
- | Tooling quality | 5 | 10 |
- | Skill design | 6 | 10* |
- | Internal consistency | 7 | 10 |
- \*The last review scored skill design 9 for one duplicated constant; it was fixed and is now
- guarded by a test, but that final change was verified by the test suite rather than another review round.
- **With vs without the skill** (same model, same tasks, blind grading against objective checks):
- on a 110-page site audit and a "review my developer's SEO advice" task, runs with the skill
- scored **24/24 (100%)** against **19/24 (79%)** without it. The baseline's misses were factual
- (e.g. saying Applebot was blocked when it falls back to Googlebot's rules, quoting an outdated
- "safe" Next.js version).
- Honest limits: search engines change constantly, so `thresholds.md` records when each fact was
- checked and tells the agent to re-verify; Core Web Vitals needs a free PageSpeed API key once the
- shared quota runs out; spoofed-UA bot tests run from your IP and can differ from real crawlers.
- ## Run the tests
- ```bash
- node scripts/tests/run-tests.mjs # offline, local fixture sites on random ports
- node scripts/tests/run-tests.mjs --network # also a live fetch + PageSpeed check
- ```
- ## Contributing
- Issues and pull requests are welcome, especially corrections with an official source link.
- If you change a number, change it in both `references/thresholds.md` and `scripts/thresholds.mjs`
- (the tests will tell you if you forget), and run the test suite.
- ## License
- MIT, see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.