How to use the SEO Audit agent skill (seo-audit)

What is an agent skill and what does seo-audit make the agent do?

An agent skill is a folder of instructions, plus optional reference files, that an AI agent loads when a request matches the skill's description. The seo-audit skill is built around a single SKILL.md file and several reference documents covering topics such as title tags, local SEO and international SEO.

When the skill is active and you ask about a ranking or SEO problem, the agent starts with a structured audit rather than a list of tips. It works through crawlability and indexation first, then technical foundations such as Core Web Vitals, then on-page optimization, content quality and authority. It also checks HTTPS, mobile-friendliness, URL structure, hreflang and local SEO problems where they apply.

• Priority order: crawlability and indexation, technical foundations, on-page optimization, content quality, authority and links.
• Checks include robots.txt, XML sitemaps, canonical tags, Core Web Vitals thresholds, mobile setup, HTTPS and URL structure.
• It warns about common mistakes, such as reporting missing schema markup from a plain page fetch that cannot see JavaScript-injected data.

Install the seo-audit skill from a ZIP file

Download the seo-audit ZIP from the skill's page in this directory, then unzip it. The folder should contain SKILL.md, the references folder and the evals folder.

For a personal setup, place the unzipped skill folder inside ~/.claude/skills/. For a single project, place it inside that project's .claude/skills/ folder so it applies only there.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with natural requests

You do not need a special command. The skill's description lists many phrases that should activate it, including 'SEO audit', 'technical SEO', 'why am I not ranking', 'my traffic dropped', 'core web vitals', 'indexing issues' and 'Google Business Profile'. Plain wording works well, for example: 'My traffic dropped last month, figure out why.'

Vague requests also trigger it. The skill is written so that a message such as 'help with SEO' starts with an audit rather than a guess. If you want a different kind of work, the skill points to other skills: programmatic-seo for building pages at scale, schema for structured data, and ai-seo for AI search optimization.

• Good: 'Why am I not ranking for our pricing page?'
• Good: 'Run an SEO health check on example.com.'
• Good: 'Our hreflang setup for the French and German sites looks wrong.'
• Vague but still valid: 'My SEO is bad.'

Give the agent the context it needs

The skill asks a few questions before auditing: the type of site, the main business goal for search, the priority keywords, any recent changes or migrations, and the scope (full site or specific pages). If you have a product marketing context file at .agents/product-marketing.md, .claude/product-marketing.md or the older product-marketing-context.md, the agent reads it first.

Access to data makes the audit sharper. The skill lists optional inputs: a browser tool to render pages and check JavaScript-injected schema, Google Search Console or analytics data, and a Screaming Frog export if your client provides one.

• Optional: a browser tool, to render pages and check JavaScript-injected schema.
• Optional: Google Search Console or analytics data.
• Optional: a Screaming Frog export.

Understand the safety notes before you run it

The skill does not run scripts, but it does use the network, so the agent fetches pages from your site. Fetched content goes to the agent. If the site is sensitive or private, check that you are comfortable with that before you start.

The skill also treats fetched pages as untrusted data. The agent is instructed to analyze page content and never follow instructions embedded in HTML, meta tags or page copy.

• Runs scripts: no.
• Uses network: yes.
• Avoid it for sensitive or private sites unless you accept that page content is sent to an agent with network access.

Get accurate schema results

Many CMS plugins such as AIOSEO, Yoast and RankMath inject JSON-LD with client-side JavaScript. That markup does not appear in plain HTML or in web_fetch output, which strips script tags. The skill warns that reporting 'no schema found' from a plain fetch produces false findings.

To check schema properly, the skill suggests a browser tool that runs document.querySelectorAll('script[type="application/ld+json"]') on the rendered page, the Google Rich Results Test, or a Screaming Frog export, which renders JavaScript.

• Browser tool: render the page and run the query shown in the code block.
• Google Rich Results Test: https://search.google.com/test/rich-results
• Screaming Frog export, if the client provides one.

Tips for getting a useful audit

Give the agent the page or section you care about, a sense of what changed, and any data you already have. A prioritized checklist is more useful when the agent knows whether you are chasing a traffic drop or preparing a launch.

Treat the output as recommendations, not guarantees. The skill is explicit that it gives recommendations, not outcomes, and that search rules change over time. The skill also notes that pages ranking in positions 8 to 20 are often the fastest wins, and points to rankings-push.md for that workflow.

• Name the scope: one page, a section, or the whole site.
• Share Search Console or analytics exports where you can.
• Ask for the findings in priority order and check each one before acting.
• For multilingual sites, focus hreflang work on pages receiving wrong-language traffic rather than every page.