Claude-SEO-Skills

A collection of Claude skills for SEO tasks. Each folder under skills/ is a self-contained, fully functional Claude skill.

Each skill performs a real technical-SEO audit — crawling a site (or scanning local HTML), checking it against documented rules, and producing a prioritized, paste-ready report. They're built to be read and learned from as much as run: the rationale behind every check lives in each skill's references/audit-checks.md.

• See what they produce: examples/ — illustrative sample reports.
• Understand how they work: docs/CONVENTIONS.md — the design behind every skill.

Requirements

• Python 3.8+ to run the audit scripts. No pip install required — every script uses only the Python standard library. (The one optional dependency, brotli, is used if present and skipped if not.)
• Node 16+ only if you use the npx installer below. Claude itself runs the skills; you don't need Node to use them once installed.

Skill architecture

Every skill folder follows the standard Claude skill structure:

skill-name/
├── SKILL.md                     # YAML frontmatter (name, description) + workflow
├── references/
│   ├── audit-checks.md          # every check: definition, why it matters, fix
│   └── report-template.md       # the exact Markdown structure of the output
└── scripts/
    ├── fetch_pages.py                # shared: crawl once → page_cache.json (crawl skills)
    ├── extract_*.py / collect_*.py   # the extractor → inventory.json (reads --from-cache)
    ├── audit_*.py                    # the auditor → audit_report.json
    ├── md_to_docx.py                 # shared: render the report as a .docx
    └── findings_to_csv.py            # shared: flatten audit_report.json → findings.csv

All skills share one pipeline — fetch → extract → audit → report — and a four-level severity model (High / Medium / Low / Info). The page-based audits crawl the site once into a shared page_cache.json (via fetch_pages.py) and each extractor reads from it with --from-cache, so a full audit fetches once instead of crawling per area; each extractor also keeps a standalone mode (live URL, --local, --url-list). See docs/CONVENTIONS.md for the full design and a guide to adding your own skill.

Export reports to Word (.docx) or CSV

Every skill can hand back its report as a Word document, not just Markdown. Ask for "a Word doc", "a .docx", or "a shareable report" and the skill writes the report and converts it with its bundled scripts/md_to_docx.py:

python3 scripts/md_to_docx.py report.md --output report.docx

Like everything else here, the converter is standard-library only — a .docx is just a ZIP of OOXML, so no pip install is needed. It renders headings, tables, lists, links, bold/italic, and code blocks. The export happens after the report is written, so the .docx keeps the prioritized fixes and rewritten values Claude produced — it's the report reformatted, not a raw dump of the findings JSON.

When you want the data rather than the write-up — to filter, sort, or triage in Sheets or Excel — every skill also bundles scripts/findings_to_csv.py, which flattens the audit's audit_report.json into a CSV with one row per finding:

python3 scripts/findings_to_csv.py audit_report.json --output findings.csv

Also standard-library only. It prepends check and severity columns and joins list fields (like the pages sharing a duplicate value) with ; . This one is a direct dump of the structured findings, so it complements the .docx: the Word doc for stakeholders, the CSV for working the issue list.

Run everything at once

| Skill | Description | |---|---| | full-seo-audit | Orchestrator. Runs every individual audit below and consolidates the findings into one prioritized, cross-area report — ranked by impact, not by which audit found the issue. Use for a complete / comprehensive technical-SEO review. |

Available skills

| Skill | Description | |---|---| | canonical-tag-audit | Audit a website's rel="canonical" tags: missing canonicals, multiple/conflicting canonicals, canonicals pointing at non-200/redirecting/noindexed URLs, relative or cross-host canonicals, https-to-http downgrades, and Link-header/HTML conflicts. | | content-quality-audit | Audit a website's content quality: thin content, exact-duplicate body text, near-duplicate (templated) pages via MinHash similarity, low text-to-HTML ratio, and missing H1s. | | core-web-vitals-audit | Audit a website's Core Web Vitals and page-experience signals (LCP, CLS, INP, TTFB): optionally pulls real field data from Google PageSpeed Insights (CrUX), and always collects browserless lab proxies — render-blocking CSS/JS, page weight, image dimension and lazy-loading hygiene, TTFB, text compression, DOM size, request counts, and third-party origins. | | external-link-audit | Audit a website's external (outbound) links: broken links, redirected targets, insecure HTTP links, affiliate rel="sponsored" compliance, unsafe target="_blank" usage, and sitewide outbound link patterns. | | heading-structure-audit | Audit a website's heading hierarchy (H1–H6): missing or multiple H1s, skipped heading levels, empty headings, headings that don't start at H1, overly long headings, and duplicate headings. | | image-seo-audit | Audit a website's images for SEO and Core Web Vitals: missing or empty alt text, missing width/height (layout shift), no lazy loading, oversized files, legacy formats, generic filenames, and broken image URLs. | | internal-link-audit | Audit a website's internal linking structure: broken links, orphan pages, redirect chains, click depth, anchor text quality, and link equity distribution. | | keyword-cannibalization-audit | Audit a website for keyword cannibalization: pages with duplicate title targets, clusters of pages whose title/H1/keyword signatures overlap, and pages sharing the same primary keyword phrase — with a recommended page hierarchy. | | llms-txt-audit | Audit a website's /llms.txt for AI/LLM discoverability (per llmstxt.org): a missing or HTML-served file, missing required H1 title or summary blockquote, broken/redirecting/blocked links, links missing descriptions, malformed list items, wrong-host or relative URLs, duplicate links, wrong content type, and whether a companion /llms-full.txt exists. | | meta-data-audit | Audit a website's title tags and meta descriptions: missing, duplicate, too-long, too-short, or multiple tags, generic or boilerplate titles, and keyword stuffing. | | mixed-content-audit | Audit an HTTPS website for mixed content: active mixed content (http scripts/styles/iframes browsers block), insecure form actions, passive mixed content (http images/media), legacy protocol-relative URLs, and pages still served over http. | | open-graph-audit | Audit a website's Open Graph and Twitter Card metadata: missing og:title/description/image/url, broken or non-image or relative og:image, og:url mismatching the canonical, missing twitter:card, over-length social titles/descriptions, and reused default images. | | pagination-audit | Audit a website's pagination: paginated pages canonicalizing to page 1 (hiding deep content), noindexed component pages, paginated pages missing a self-canonical, broken or inconsistent rel=next/prev, and redundant ?page=1 first pages. | | redirect-audit | Audit a website's redirects: resolves the full redirect chain for every URL to find chains and loops, redirects that end in 404s/errors, temporary (302) redirects used for permanent moves, HTTPS-to-HTTP downgrades, client-side meta-refresh and JavaScript redirects, dropped query strings, and canonicals pointing at redirecting URLs. | | robots-txt-audit | Audit a website's robots.txt: a redirected or HTML-served file, a 5xx read as "block everything", a sitewide Disallow: /, syntax errors, render-blocking CSS/JS, missing or unreachable Sitemap: directives, a missing default User-agent: * group, unsupported directives (noindex, crawl-delay) Google ignores, files over the 500 KiB limit, and BOM/duplicate/empty-rule issues. | | schema-markup-audit | Audit a website's structured data: extract JSON-LD, Microdata, and RDFa, validate against schema.org and Google rich result requirements, and find missing, invalid, or incomplete markup. | | site-architecture-audit | Audit a website's architecture: hostname and protocol canonicalization, robots.txt, XML sitemap parity, crawl and index directive conflicts, URL structure quality, click-depth distribution, and directory taxonomy. | | sitemap-audit | Audit a website's XML sitemaps: discovers sitemaps from robots.txt, follows sitemap index files, and validates every listed URL for non-200 status, redirects, noindex/robots-blocked URLs, canonicalized-away URLs, wrong host/protocol, duplicates, oversized sitemaps (over 50,000 URLs or 50MB), parse errors, and lastmod/priority/changefreq hygiene. | | soft-404-audit | Audit a website for soft 404s: error pages served with a 200 status, a server that returns 200 for every unknown URL, thin pages matching the site's error template, and empty/near-empty pages. |

Install

Install all skills into your global Claude skills directory (~/.claude/skills/):

npx claude-seo-skills install

Other options:

# Install only specific skills
npx claude-seo-skills install sitemap-audit robots-txt-audit

# Install into the current project's ./.claude/skills instead of the global dir
npx claude-seo-skills install --project

# Install into a custom directory, overwriting anything already there
npx claude-seo-skills install --dir ~/my-skills --force

# List available skills
npx claude-seo-skills list

Or install the CLI globally:

npm install -g claude-seo-skills
claude-seo-skills install

Manual usage

You can also copy a skill folder into your Claude skills directory (e.g., ~/.claude/skills/ for Claude Code) or upload it where skills are supported. Claude will invoke the skill automatically when a request matches its description.