FreeAgent skill for AI coding toolsVersion 1.1.0MIT

SEO Skill

A portable SEO auditor and fix workflow for AI coding agents.

SEO Skill is a free, open-source Agent Skill that turns an AI coding assistant into a careful SEO engineer. It audits real websites, explains every finding with evidence, implements fixes in your codebase, and verifies the result. It is built for multilingual and statically generated sites, and works with Claude Code, OpenAI Codex, OpenCode, DeepSeek Harness, Cursor, Gemini CLI, and any other tool that follows the Agent Skills standard.

What it does

SEO Skill is not a checklist generator. It turns an SEO request into an evidence-based audit, a prioritised fix list, implemented changes in your codebase, and a verification pass.

  • Evidence, not guesses

    Every finding carries a URL, status code, header, tag, or quoted snippet. Nothing is reported as "probably slow" or "likely duplicate" without a check.

  • Technical SEO foundations

    Crawlability, indexability, canonicalisation, redirects, status codes, sitemaps, robots.txt, and consistent URL hygiene — fixed in dependency order.

  • Multilingual sites done properly

    Localized URLs, reciprocal hreflang plus x-default, self-canonicals, localized metadata, JSON-LD, Open Graph, and sitemap alternates.

  • Content quality without fabrication

    Checks page purpose, intent, duplicate content, and honest proof. It will not invent testimonials, statistics, clients, prices, or certifications.

  • Structured data and social previews

    Organization, WebSite, WebPage, Service, BreadcrumbList, FAQPage, Article, and Product JSON-LD that match the visible page, plus real Open Graph images.

  • Performance and Core Web Vitals

    Works from measurements, separates lab data from field data, fixes render-blocking resources, images, fonts, compression, and cache policy — with server-owned items documented honestly.

  • AI search and crawler policy

    Separate decisions for AI search crawlers and model-training crawlers, explicit robots.txt groups, and a maintained llms.txt that points to accurate public pages.

  • Measurement and reporting

    A repeatable report with scope, findings by severity, owner per finding, a prioritised plan, verification results, and external follow-ups such as Search Console.

  • Built for static builds

    Generate crawl files from the same data as the pages, fail the build on missing translations, and verify every URL before deploy.

How it works

The skill follows a repeatable workflow. It fixes foundations before content, and it never claims a server-side change that only a host can make.

  1. Scope and baseline

    Confirms the canonical host, the languages and markets that matter, the business goal, and what can actually be measured. Missing access is recorded as not verifiable, not guessed.

  2. Inventory and crawl

    Finds every public URL and captures status, indexability, title, description, canonical, lang, H1, structured data, Open Graph, hreflang, internal links, and word count.

  3. Fix in dependency order

    Status codes and redirects first, then indexability, canonicals, sitemap and robots.txt. Internationalisation, content, structured data, and performance follow.

  4. Separate code from hosting

    Every finding gets an owner: code, content, server, or external. Compression, cache TTLs, DNS, and CDN redirects are documented as server tasks instead of being claimed as repo fixes.

  5. Verify the result

    A fix is not done until the rebuilt site passes a repeatable check: crawl all URLs, validate crawl files, re-check headers, and compare rendered text with structured data.

Install

The fastest route is the bundled CLI. It installs the skill into the shared Agent Skills folder, so most AI coding tools can use it without cloning the repository.

Fastest install (no clone)
npx -y github:AJN-Tech/seo-skill

Installs to the universal ~/.agents/skills/seo target and adds Claude Code support when detected.

Universal target plus Claude Code
npx -y github:AJN-Tech/seo-skill --all

Forces both ~/.agents/skills/seo and ~/.claude/skills/seo.

Verify the install
npx -y github:AJN-Tech/seo-skill check
Clone and use the shell installer
git clone https://github.com/AJN-Tech/seo-skill.git
cd seo-skill
./install.sh

Use ./install.sh --all to force both targets, or ./install.sh --project ../my-site for a project-scoped install.

Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File install.ps1
Remove it later
npx -y github:AJN-Tech/seo-skill uninstall
After installing. Restart your AI tool or start a new session. Skill catalogues are usually loaded at session start, so the new skill may not appear until then.

Supported tools

The universal install target is ~/.agents/skills/seo/. It covers Codex, OpenCode, DeepSeek Harness, Cursor, and Gemini CLI. Claude Code reads its own directory, so the CLI adds it when requested or detected.

ToolInstalled pathHow to invoke
Claude Code~/.claude/skills/seo//seo
OpenAI Codex~/.agents/skills/seo//skills or $seo
OpenCode~/.agents/skills/seo/Ask, or use the skill tool
DeepSeek Harness~/.agents/skills/seo/Skill list in a new session
Cursor~/.agents/skills/seo//seo or @seo
Gemini CLI~/.agents/skills/seo//skills list

Project-scoped installs are supported too: ./install.sh --project ../my-site writes the skill inside the project so the whole team gets it. For tools without a skill directory, ./install.sh --agents-md ../my-site appends a pointer to AGENTS.md.

How to use it

Ask naturally in your AI coding tool, or run the auditor directly from a terminal. The skill handles the workflow; the auditor provides deterministic, repeatable evidence.

Ask your AI tool

  • Audit https://example.com for SEO and give me the prioritised fixes.
  • Why is the French version of our site not ranking?
  • Add reciprocal hreflang and x-default for our four languages.
  • Fix the PageSpeed issues on the home page and tell me what is server-owned.
  • Write robots.txt, a sitemap, and llms.txt from our page catalogue.
  • Review our JSON-LD and Open Graph tags against the visible page.
  • Set up a repeatable Search Console measurement plan.

Or run the auditor yourself

Audit a live site
npx -y github:AJN-Tech/seo-skill audit https://example.com --json --out seo-report.json

A bounded, polite, read-only crawl. It never submits forms or changes anything on the site.

Audit a local build
npx -y github:AJN-Tech/seo-skill audit ./dist --base https://example.com

Runs full URL-aware checks against the files you are about to deploy.

Audit one page
npx -y github:AJN-Tech/seo-skill audit https://example.com/pricing
Check crawl files only
npx -y github:AJN-Tech/seo-skill crawl-files https://example.com
Use it as a CI gate
npx -y github:AJN-Tech/seo-skill audit ./dist --base https://example.com --fail-on high

Exits non-zero when a critical or high finding exists, so a bad build cannot ship.

What it checks

The skill ships with a reference library. It loads only what the task needs, which keeps the always-on instructions small while still covering the full audit surface.

  • Audit checklist

    The full pass/fail checklist by area, for when a script cannot run or as the acceptance list after a fix pass.

  • Technical SEO

    How to inspect crawl, index, redirects, canonicals, and status codes without a browser.

  • Crawl files

    robots.txt policies, sitemap generation, and llms.txt templates.

  • Internationalisation

    URL schemes, reciprocal hreflang rules, x-default, and the pitfalls of client-side language switching.

  • Content quality

    Page purpose, section structure, duplicate detection, reviewed translations, and honest proof.

  • Structured data

    JSON-LD graph patterns, localization, and validation against visible content.

  • Performance

    Core Web Vitals, PageSpeed Insights, the render path, responsive images, and server headers.

  • AI search

    AI search versus model training, llms.txt, and the limits of AI visibility measurement.

  • Measurement

    Search Console setup, sitemap submission, KPIs, and reporting cadence.

  • Report template

    The deliverable format: findings, severity, owner, fix, and validation method.

  • Static-site playbook

    Build-time SEO architecture and a regression harness for static and server-rendered sites.

  • Case study

    A real four-language audit: 38 pages became 152 crawlable pages, with the verification bug that was caught.

Guardrails

The skill is explicit about what it will not do. These rules protect users and keep the audit honest.

  • No cloaking, doorway pages, paid links, link farms, or snippet manipulation.
  • No fabricated reviews, ratings, statistics, certifications, or "trusted by" logos.
  • No keyword stuffing in titles, headings, alt text, or schema.
  • No device-language redirects that hide the canonical localized page from crawlers.
  • No disallow rules on pages that must stay indexable, and no accidental noindex.
  • Lighthouse lab estimates are never presented as field Core Web Vitals.
  • If a requested tactic would harm users or break search policies, the skill refuses it and offers the compliant alternative.

Who it is for

A good fit if you…

  • Business owners and developers who want an SEO audit they can act on.
  • Teams shipping multilingual or statically generated sites.
  • Agencies that need a repeatable, evidence-based SEO check in CI.
  • Anyone using an AI coding assistant who wants SEO guardrails built in.

Not a fit if you want…

  • Guaranteed rankings or traffic promises.
  • Paid ads management or link buying.
  • Cloaking, doorway pages, or mass near-duplicate content.
  • Fabricated reviews, statistics, or client proof.

Requirements and license

  • Node.js 18 or newer for the auditor and tests.
  • The skill itself is plain Markdown and works offline.
  • No API keys, no build step, and no runtime dependencies for the audit.
  • The audit is read-only and only performs GET requests.
License
MIT
Version
1.1.0
Last updated
November 2026
Price
Free
All free resources