Claude Code Skills for SEO Audits: A Reusable Workflow

A Claude Code skill is a folder with a SKILL.md file that packages instructions Claude loads when your request matches its description, so an SEO audit routine can be written once and reused on every site. This post shows the structure, a worked audit skill, the safety settings I would use and the checks that still need a human. As of 14 October 2026, it is based on Anthropic's documentation and what I would build, not on a claim that a skill replaces an auditor.

Key Takeaways

• A skill is a directory with a SKILL.md (YAML frontmatter plus Markdown), stored in ~/.claude/skills/ for personal use or .claude/skills/ in a repo to share.
• Claude reads only the name and description at startup and loads the body when a request matches, so a precise description decides whether the skill triggers.
• Keep the SKILL.md under about 500 lines and push checklists and reference material into supporting files.
• For audits, separate deterministic checks (scripts) from judgement (Claude), and make the final report cite the evidence for every finding.
• Restrict allowed-tools, and read any third-party skill like software you are installing.
• Use the skill to speed up evidence collection, then review findings yourself before anything goes to a client.

What a skill is (and is not)

Anthropic's documentation describes Agent Skills as modular capabilities: each is a directory that packages instructions, metadata and optional resources such as scripts, templates and reference files. A skill is more durable than a prompt, because prompts are conversation-level instructions for one-off tasks while skills load on demand (Anthropic: Agent Skills overview).

The loading model is called progressive disclosure. Per that page, level 1 is metadata (name and description, roughly 100 tokens per skill) loaded at startup; level 2 is the SKILL.md body, loaded when the skill triggers; level 3 is bundled files, which load only when read, and scripts, where only the output enters context. This matters for audits: you can keep a long checklist in a reference file and pay for it only when needed.

A skill is not a plugin marketplace, an MCP server or a rules file. Per the Claude Code docs, skills live alongside other mechanisms, and Claude Code's skill page lists where they sit: personal (~/.claude/skills/<name>/SKILL.md), project (.claude/skills/<name>/SKILL.md, committed to share with a team), nested, plugin and enterprise (Claude Code docs: Skills). Olostep's July 2026 explainer gives the same rule of thumb: CLAUDE.md for always-on rules, slash commands for quick templates, MCP servers for live data or external actions, and skills for expertise needed only sometimes (Olostep). Olostep is a web-data vendor, so I only lean on its general guidance.

My earlier notes on Claude Code for marketers are in the Claude Code update post and the plugin side in the plugin directory post.

Why an audit is a good fit for a skill

SEO audits repeat the same steps: crawl, inspect indexability, check templates, sample pages, compare against a standard, write findings. The inputs change; the procedure does not. That is exactly what a skill is for. Done badly, it also tempts you to accept confident-sounding output without evidence, so the design below builds in evidence and review.

The folder layout I would use

seo-audit/
├── SKILL.md              # when to use, workflow, output format
├── checklist.md          # the full list of checks, grouped
├── report-template.md    # findings format (issue, evidence, impact, fix)
└── scripts/
    ├── fetch_headers.sh  # status codes, canonical, robots headers
    └── parse_sitemap.py  # list URLs and lastmod

Claude Code's docs recommend keeping SKILL.md as an overview and moving detail into separate files, referenced from SKILL.md so Claude knows when to read them. They also mention ${CLAUDE_SKILL_DIR} for pointing to bundled scripts regardless of working directory.

A worked SKILL.md

This is a template, not a tested product. Adapt the commands to your environment and test it on a site you own.

---
name: seo-audit
description: Audit a website for technical SEO, content and AI-search readiness. Use when the user asks for an SEO audit, site review, indexability check, or "why is this site not ranking".
disable-model-invocation: true
allowed-tools: Read Grep Bash(curl -sI *) Bash(python3 ${CLAUDE_SKILL_DIR}/scripts/*)
---

# SEO audit workflow

Audit $ARGUMENTS. Never change the site. Cite evidence for every finding.

## Steps
1. Confirm scope: domain, 5-10 representative URLs, any known problem.
2. Run `scripts/parse_sitemap.py` and sample URLs by template.
3. For each sampled URL, run `scripts/fetch_headers.sh` and record status, canonical, robots directives.
4. Read `checklist.md` and apply only checks relevant to the scope.
5. Write findings using `report-template.md`.
6. List what you could NOT check and why.

## Rules
- Mark each finding Confirmed (evidence shown) or Hypothesis (needs verification).
- Do not state ranking or traffic impact as fact.
- Do not recommend structured data that the page does not visibly support.

Notes on the choices, all grounded in the docs I opened:

• `description` is front-loaded with phrases a user would actually type. Claude Code's page says Claude decides whether to load a skill from description and when_to_use alone, and the combined text is truncated at 1,536 characters in the listing. Anthropic's API overview sets a 1,024-character limit on description for skills in that environment, so keep it short enough for both.
• `disable-model-invocation: true` means only you can invoke it with /seo-audit, which suits a task with a cost and a client-facing output.
• `allowed-tools` is narrow. It lists reads, grep, header-only curl and your own scripts. Per the docs, allowed-tools lets those tools run without a permission prompt during the turn, so I only pre-approve safe ones.
• Portability: the docs warn that outside Claude Code, such as claude.ai uploads or the Skills API, only a smaller set of frontmatter fields is accepted. If you plan to upload the skill elsewhere, check which fields your target accepts.

What to put in checklist.md

Group checks by what can be verified by a script, what needs Claude's reading and what needs you. A starting structure:

Two of the checks should come straight from Google's documentation. The AI features page says a page can appear as a supporting link in AI Overviews or AI Mode if it is indexed and eligible to show in Search with a snippet, with no additional technical requirements, and that you do not need AI-specific files or special markup (Google: AI features and your website). So your AI-readiness section should check indexability, snippet controls (nosnippet, max-snippet), crawl access at the CDN layer and text availability, not invent "AI schema." Likewise, the structured data policy says to mark up only visible content and not to mislead (Google: General structured data guidelines), so the skill should flag markup that overreaches.

Google's own guidance on creating helpful, reliable content (authorship, how content was made, why) is a good source for the content section of the checklist.

Evidence rules that stop hallucinated audits

I would hard-code these into the skill because they are where AI-assisted audits go wrong:

1. No finding without evidence. Each issue lists the URL, the observed value and how it was obtained.
2. Separate facts from guesses. "Confirmed" versus "Hypothesis" labels.
3. No invented metrics. If the skill has no analytics data, it must say traffic impact is unknown.
4. Sample, then extrapolate carefully. State the sample size and avoid "site-wide" claims from three URLs.
5. List the unchecked. An honest "not checked" list is more useful than false completeness.

Open-source skills: useful, but inspect them

You do not have to start from zero. One write-up describes two MIT-licensed skills for Claude Code from Daniel Agrici, Claude SEO (audits) and Claude Blog (writing and review), with checks spanning technical SEO, Core Web Vitals, hreflang, E-E-A-T and schema signals, and GEO readiness (Pasquale Pillitteri). The article is dated around June 2026, its star counts are as of 22 June 2026 and its growth example is the author's own site, so it is not evidence of general results. It also notes the tool does not promise rankings and advises cloning and inspecting install scripts rather than piping them to a shell. I have not installed or tested those skills, so I cannot vouch for their output.

Security: treat skills like software

Anthropic's page is blunt: skills give Claude new capabilities through instructions and code, so a malicious skill can direct Claude to use tools in ways that do not match its stated purpose. Their guidance is to use trusted sources, audit everything bundled (SKILL.md, scripts, images), be wary of skills that fetch external URLs, and watch for tool misuse and data exposure. For an SEO skill that touches client data, also keep client credentials out of the skill folder and avoid giving it write access to a CMS. The wider agent-security picture is in my post on agent security for marketers.

Testing the skill

Claude Code's docs suggest testing in a fresh session, because leftover context can hide gaps in your instructions, and comparing runs with and without the skill. My test routine:

1. Run it on a small site you control with a known issue (for example a noindex you planted).
2. Check whether the skill found it and cited evidence.
3. Run it on a clean page and check for false positives.
4. Change the description wording and confirm it triggers on the phrases you expect.
5. Re-run after a Claude Code or model update; behaviour can shift.

The docs also say edits to SKILL.md under existing skill directories are picked up without a restart, which makes iteration quick, and that you should audit unused skills because each one in the listing costs context.

What the skill should not do

• Make ranking promises or traffic forecasts.
• Rewrite pages or push changes without your approval.
• Replace analysis of search intent, brand and business context.
• Decide which issues matter most for revenue. That is your call.

FAQ

What is a Claude Code skill?

It is a directory with a SKILL.md file containing YAML frontmatter and Markdown instructions, plus optional scripts and reference files. Claude loads it when your request matches its description, or you invoke it by name.

Where do I save an SEO audit skill?

For personal use, ~/.claude/skills/<name>/SKILL.md. To share with a team, put it in .claude/skills/<name>/SKILL.md in the repo and commit it, according to Claude Code's documentation.

Can a skill do a full SEO audit by itself?

It can collect and organise evidence quickly, but intent, business context and prioritisation need a human. I would never send an unreviewed AI audit to a client.

How do I stop it from making things up?

Require evidence for every finding, label hypotheses, forbid invented metrics and list unchecked items. Put those rules at the top of SKILL.md.

Is it safe to install skills from GitHub?

Treat it like installing software. Read SKILL.md and every script, check allowed-tools, avoid skills that fetch unknown URLs and prefer trusted sources, as Anthropic's documentation advises.

Do I need to code?

Not necessarily. SKILL.md is Markdown. Scripts help for deterministic checks and are optional, but someone should be able to read them.

How is a skill different from CLAUDE.md?

CLAUDE.md holds rules that always apply to a project. A skill loads only when relevant, which keeps context lean for specialised workflows like audits.

Will it work on claude.ai or the API?

Possibly with limits. Claude Code's docs say outside Claude Code only a smaller set of frontmatter fields is accepted, so check before uploading.

How often should I update the skill?

Review it when Google's documentation, your tooling or the model changes, and at least quarterly. Keep a changelog in the skill folder.

Work With Me

If you want an audit workflow your team can reuse, or a human review of what your AI-assisted audits produce, I would be happy to help. I bring 4+ years of marketing experience across SEO, AEO and content strategy. See my work and reach out through the contact form at https://younusfardeen.in.