Source: addyosmani/web-quality-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the SEO skill?
The SEO skill Claude Code, Codex, Cursor and other agents can load from addyosmani/web-quality-skills is a technical SEO audit that starts from measured evidence: a Lighthouse SEO run on the rendered page, then the checks Lighthouse can't do on its own. It fixes crawl, index, metadata and structured data problems in your source and re-runs the same checks to confirm.
The skill is one of six in the repo, which the README describes as "An (unofficial) measurement-first collection of Agent Skills for optimizing web projects with Google Lighthouse, Chrome DevTools for agents, Core Web Vitals, WCAG, and search guidance." The others cover accessibility, performance, Core Web Vitals, best practices and a full web quality audit.
The skill's description reads: "Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "optimize for search", "fix meta tags", "add structured data", "sitemap optimization", or "search engine optimization"."
As of 24 October 2026, its skills.sh page listed 51.8K installs (snapshot, 24 October 2026), second in the repo after the accessibility skill.
What does it do?
The skill is model-invoked: the agent loads it when your request matches the description, such as "fix the meta tags on the pricing page". It is framework-agnostic, so the same advice applies to Next.js, Astro, Nuxt or plain HTML.
Its SKILL.md opens with a four-step audit workflow for a page you can load:
- Run live Lighthouse SEO and Agentic Browsing checks, using the
lighthouse_audittool when Chrome DevTools MCP is connected. - Inspect what Lighthouse can't establish: response headers, redirects,
robots.txt, sitemap coverage, canonical consistency across templates, structured data eligibility, and Search Console data if you give the agent access. - Keep technical crawl and index findings separate from content quality and authority.
- Fix the source, re-run the same checks, and report that indexing or ranking outcomes still need search-engine validation.
The rest of the file is reference material the agent applies while fixing:
| Area | What the skill covers |
|---|---|
| Crawlability | robots.txt rules, meta robots values, self-referencing canonicals, XML sitemaps (50,000 URLs or 50MB per file) |
| URLs | Hyphens, lowercase, short paths, HTTPS |
| On-page | Unique titles and meta descriptions, heading hierarchy, image filenames and alt text, descriptive anchor text |
| Structured data | JSON-LD that describes visible content, validated on the rendered page |
| Mobile | Responsive viewport, tap targets, readable font sizes |
| International | hreflang tags and the lang attribute |
Length guidance is deliberately soft. The skill treats 50 to 60 characters for titles and 150 to 160 for meta descriptions as rough linting proxies, not pass or fail limits, and points to Google's title link guidance for why Google may rewrite a title anyway. It also says not to fail a page just because valid HTML has more than one <h1>.
It ends with a prioritized checklist (critical, high, medium, ongoing) and a tools table: Google Search Console, PageSpeed Insights, the Rich Results Test, Lighthouse and Screaming Frog.
What's in the folder:
SKILL.md: the workflow, technical and on-page rules, and the checklist.references/STRUCTURED-DATA.md: Organization, Article, Product, FAQ and Breadcrumb JSON-LD examples plus validation links. The agent reads it only when you ask for schema markup or an audit finds a structured data issue.
How does it handle AI search?
The SKILL.md keeps three things apart that SEO advice often blurs:
- Lighthouse Agentic Browsing measures whether an assistant can understand and use the rendered page: the accessibility tree, an optional
llms.txt, and WebMCP registrations when present. - Search indexing and ranking, which "cannot be inferred from the Agentic Browsing score."
- AI ingestion or citation, which it calls product-specific. A browsable page or a valid
llms.txt"does not prove that an AI product will ingest, rank, or cite it."
For crawler controls, it tells the agent to audit each documented user agent separately, with a table covering OAI-SearchBot, PerplexityBot, Claude-SearchBot and Claude-User, and Google-Extended, and notes that training crawlers such as GPTBot and ClaudeBot are separate from search and user-fetch crawlers. It links each vendor's documentation and asks the agent to recheck current names there rather than trust the table.
On llms.txt, the skill calls it "an experimental proposal, not a cross-vendor discovery standard" and says to add one only when you ask or a documented consumer supports it.
How do you install it?
Just this skill. The command on its skills.sh page uses the skills CLI, which needs Node.js 22.20 or later:
npx skills add https://github.com/addyosmani/web-quality-skills --skill seo
Add -g to install it for every project. For Claude Code the folder lands in .claude/skills/seo/, or ~/.claude/skills/seo/ with -g, the standard Claude Code skill locations. The SKILL.md links to the repo's core-web-vitals and web-quality-audit skills, so add --skill core-web-vitals --skill web-quality-audit if you want those links to resolve.
All six skills as a Claude Code plugin. From the README, run inside Claude Code:
/plugin marketplace add addyosmani/web-quality-skills
/plugin install web-quality-skills@addy-web-quality-skills
Plugin skills are namespaced, so it appears as /web-quality-skills:seo and updates with /plugin update.
Codex and Gemini CLI. The README documents codex plugin marketplace add addyosmani/web-quality-skills (Codex CLI v0.122 or later, then @seo in chat) and gemini extensions install https://github.com/addyosmani/web-quality-skills. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
claude.ai. The README suggests adding the skill to project knowledge or pasting the SKILL.md into a conversation. You can also zip the seo folder and upload it under Customize, then Skills, as the Claude Help Center describes.
Optional: Chrome DevTools MCP. For live Lighthouse runs, connect Chrome DevTools MCP. Its docs give this Claude Code command:
claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest
How do you use it?
Point it at a page it can load, or at the templates that render your pages. The skill gets more out of a running URL than out of source alone.
Example prompts (suggestions, not quotes from the repo):
Run an SEO audit on http://localhost:3000/pricing and fix what you can in the source.Check robots.txt, the sitemap and canonical tags across our blog templates for conflicts.Add Product structured data to the product page template and validate the rendered JSON-LD.Our docs pages share one meta description. Generate unique ones from each page's content.Review which AI crawlers our robots.txt blocks and explain what each block affects.
Requirements: none beyond the skill for source review. For rendered checks you need Chrome DevTools MCP or the Lighthouse CLI, and for indexing data you need to give the agent Search Console exports or access.
Tips and limits
- Scores are not rankings. The skill says a Lighthouse SEO score "covers a useful subset of technical checks; it is not a prediction of rankings." Expect fixes and evidence, not traffic promises.
- Content quality is out of scope for scoring. It reviews usefulness and authority but is told not to "assign synthetic ranking percentages."
- Some examples are dated. The sample sitemap includes
changefreqandprioritytags and the canonical section mentionsrel="prev"andrel="next"; treat code samples as patterns and check current guidance at Google Search Central. - Security audit. On 24 October 2026 its skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Warn. The skill ships no scripts; it runs tools only through whatever your agent has, such as Lighthouse.
The MIT License lets you copy, change and share the skill as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and references/STRUCTURED-DATA.md. Paste the repo link instead and Kipt lists all six skills, so you can take core-web-vitals and web-quality-audit too. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/web-quality-skills.
Similar skills
- Accessibility skill: the WCAG 2.2 skill from the same repo, which overlaps with SEO on alt text and headings.
- Core Web Vitals skill: the sibling skill the SEO checklist defers to for page experience metrics.
- Web best practices skill: HTTPS, security headers and console errors, from the same repo.
- Web performance skill: Cloudflare's trace-based performance audit for coding agents.