I Wrote a Claude Code SEO Skill, and Testing It Found Two Bugs on Day One
Claude Code skills are just folders. A SKILL.md with a name and a description, plus whatever scripts you want the model to run. When the description matches what you asked for, Claude loads the instructions and follows them. That's the whole mechanism, and it's why SEO is a good fit: most on-page checks are deterministic, and a model is much better at explaining a result than at counting characters in a <title> tag.
So I wrote one. It checks a single URL for the on-page basics and hands Claude a JSON report to turn into a fix list. Then I ran it against five real pages and one fake one before trusting it. It broke twice, on pages I'd have assumed were safe.
The layout
.claude/skills/seo-page-check/
├── SKILL.md
└── scripts/
└── check_page.py
Project-level skills live in .claude/skills/ inside the repo; personal ones go in ~/.claude/skills/. Claude Code reads the frontmatter of every skill at startup and only pulls in the body when the description matches the task, so a skill you're not using costs almost nothing.
SKILL.md
name: seo-page-check
description: Check one URL for on-page SEO problems (title, meta description, canonical, robots/noindex, H1, JSON-LD, image alt text) and return a prioritized fix list. Use when the user asks to audit, check, or review the SEO of a specific page or URL.
# SEO page check
1. Run the checker on the URL the user gave:
`python3 .claude/skills/seo-page-check/scripts/check_page.py <url>`
2. Read the JSON it prints. Do not re-fetch the page yourself unless the script failed.
3. Report in this order, and skip any section with nothing in it:
- **Blockers**: anything in `blockers` (noindex, non-200 status, canonical pointing to another host).
- **Fix next**: items in `warnings`, one line each, with the current value quoted.
- **Fine**: one line listing what passed.
4. For each title or description warning, suggest one rewrite that keeps the page's main keyword. Do not invent keywords that are not on the page.
5. Never claim a ranking impact. Say what is wrong and what to change.
Two choices in there are deliberate.
The description lists the actual checks. Claude decides whether to load a skill from the description alone, so "SEO helper" would be a bad one. It's vague, and it would match half of what you type in a marketing repo. Naming the checks and the trigger ("a specific page or URL") keeps it from firing when you ask for keyword ideas.
Rule 5 is there because models love writing "this will improve your rankings." Nobody knows that from a page check, so the skill forbids it.
The script
Standard library only, so it runs anywhere Claude Code does without a pip install:
#!/usr/bin/env python3
"""Fetch one URL and report on-page SEO issues as JSON. Standard library only."""
import json, sys, urllib.error, urllib.request
from html.parser import HTMLParser
from urllib.parse import urlparse
class Page(HTMLParser):
def __init__(self):
super().__init__()
self.title, self.in_title, self.in_h1 = "", False, False
self.meta, self.canonical, self.h1s, self.jsonld = {}, None, [], 0
self.imgs, self.imgs_no_alt, self.title_done = 0, 0, False
def handle_starttag(self, tag, attrs):
a = dict(attrs)
if tag == "title" and not self.title_done: self.in_title = True # skip SVG <title>s
elif tag == "meta" and a.get("name"):
self.meta[a["name"].lower()] = a.get("