agentleFS
keuperakeupera/seo-skills/skills/technical-seo-audit/SKILL.md

technical-seo-audit

Skill0 starsChanged 2 months agoMITView on GitHub

Audit a website or codebase for the technical faults that stop pages being crawled, rendered, indexed and ranked, then produce a triaged fix list. Use whenever the user asks for an SEO audit or site health check, says pages aren't indexed or aren't showing up in Google, asks about crawlability, robots.txt, sitemaps, status codes, canonicals, redirects, rendering or JavaScript SEO, has just launched or migrated a site, or reports a sudden traffic drop. Also use before any content work on a site that has never been audited, because content on an unindexable page is wasted.

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before touching anything, get the ground truth.

    line 29
  2. Very specific:

    Fetch the page as a bot: Check the final status, the full redirect chain and the x-robots-tag header:

    line 31
  3. Distinctive:

    Read the raw HTML, not the DOM: If the content only appears once JavaScript has run, that's a finding in itself:

    line 37
  4. Distinctive:

    Pull Search Console: if it's available. The Pages report tells you exactly which URLs Google excluded and why.

    line 44
  5. Distinctive:

    If Search Console isn't connected, connecting it is the first recommendation, not an afterthought.

    line 46
  6. Very specific:

    noindex on pages that should rank: Check the meta tag and the X-Robots-Tag header.

    line 82
  7. Distinctive:

    Canonicals pointing somewhere unexpected: Every indexable page should self-canonicalise unless there's a deliberate reason not to.

    line 83
  8. Distinctive:

    Don't report a score: No tool has access to Google's ranking signals, so any number out of 100 is invented.

    line 114

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Technical SEO Audit

Content problems are expensive to fix and slow to pay off. Technical problems are usually cheap to fix and pay off immediately. Audit in that order.

The purpose of this audit isn't a 90-page PDF. It's a short list of things that are broken, ordered by how much traffic each one costs, with the fix written out.

The order of operations

Work top to bottom. A failure at any level makes everything below it irrelevant, so never optimise a title tag on a page that returns a 404 to Googlebot.

1. Can it be reached?      DNS, TLS, server response, uptime
2. Can it be crawled?      robots.txt, status codes, redirect chains, crawl traps
3. Can it be rendered?     JS execution, hydration, content in the initial HTML
4. Can it be indexed?      noindex, canonicals, duplicates, thin pages
5. Can it be understood?   headings, structured data, internal links, entities
6. Is it pleasant to use?  Core Web Vitals, mobile layout, interstitials

Report findings in this order too. It reads as a diagnosis rather than a list of complaints.

Step 1: Establish what's actually happening

Before touching anything, get the ground truth. Guessing at this stage produces confident nonsense.

  • Fetch the page as a bot. Check the final status, the full redirect chain and the x-robots-tag header:
curl -sIL -A "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" https://example.com/page
  • Read the raw HTML, not the DOM. If the content only appears once JavaScript has run, that's a finding in itself:
curl -s https://example.com/page | grep -iE "<title>|canonical|robots|<h1"
  • Read robots.txt and the sitemap by hand. Both are small files and both are frequently wrong.
  • Pull Search Console if it's available. The Pages report tells you exactly which URLs Google excluded and why. That report is the audit. Everything else is you predicting what it will say.

If Search Console isn't connected, connecting it is the first recommendation, not an afterthought.

Step 2: Crawlability

CheckHow to spot itWhy it matters
robots.txt blocking real pagesDisallow rules matching indexable pathsBlocked pages can't be crawled at all
Blocking CSS or JSDisallow on /assets/, /_next/Google renders the page, and blocking assets breaks rendering
Redirect chainsMore than one hop to the destinationWastes crawl budget, dilutes signals, slows users
Redirect loopsThe curl above never terminatesPage is unreachable
Soft 404sA 200 status on an empty or "not found" pageGoogle indexes junk or distrusts the whole section
5xx under loadIntermittent errors in server logsCrawl rate gets throttled and stays throttled
Infinite URL spacesCalendars, filters, session IDs, ?page=99999Crawler burns its budget on worthless URLs

The most common serious finding by a wide margin is a Disallow: / left behind after a staging deploy. Check for it first, every time.

Step 3: Rendering

Google renders JavaScript, but rendering is queued, budgeted and sometimes skipped. Anything that matters belongs in the initial HTML response.

Diff what the server sends against what the browser ends up with:

curl -s https://example.com/page | wc -c          # bytes of real HTML
curl -s https://example.com/page | grep -c "<p"   # is there any prose in there?

Findings worth raising:

  • Main content only present after hydration. Fix with SSR, SSG or streaming, not with prerender hacks.
  • Links rendered as div with an onclick handler. Google follows real anchors with an href attribute and nothing else. Router links that compile down to real anchors are fine. Ones that don't are invisible.
  • Content behind an interaction. Content in the HTML but visually hidden is generally fine. Content fetched on click is not.
  • Canonical or meta tags injected by client-side JavaScript. Frequently ignored. Emit them server-side.

Step 4: Indexability

  • noindex on pages that should rank. Check the meta tag and the X-Robots-Tag header. The header is the one people forget, and it wins silently.
  • Canonicals pointing somewhere unexpected. Every indexable page should self-canonicalise unless there's a deliberate reason not to. Cross-domain canonicals to a staging or CDN host are a classic launch bug.
  • Duplicate clusters. The same content on /page, /page/, /Page, ?utm_source=..., plain http, www and non-www. Pick one, redirect the rest, canonical the survivors.
  • Thin and near-empty pages such as tag archives, empty search results and paginated pages holding two items. Give them substance, noindex them, or remove them.
  • Orphan pages listed in the sitemap that nothing links to internally. If the site won't link to a page, that's a statement about how important it is.

The full decision tree lives in canonical-duplicate-content.

Step 5: Machine comprehension

  • One h1 per page, describing the page rather than the brand.
  • A heading hierarchy that doesn't skip levels for styling reasons.
  • Descriptive internal anchor text. "Pricing" beats "here".
  • Structured data that matches what's visibly on the page. See schema-markup.
  • A sitemap listing exactly the canonical, indexable, 200-status URLs and nothing else. A sitemap full of redirects and 404s is a quality signal pointing the wrong way.

Step 6: Triage before you report

Sort every finding into one of four buckets. Anything below the top two isn't worth the user's afternoon.

BucketMeaningExample
BlockingPages can't be indexed at allDisallow: /, sitewide noindex, 5xx
CostingIndexed but measurably underperformingRedirect chains on top pages, missing canonicals, slow LCP
HygieneCorrect to fix, small effectSitemap tidying, heading order, alt text gaps
IgnoreA tool flags it and it doesn't matterKeyword density, "SEO score", meta keywords

For every finding in the top two buckets give four things: the affected URLs or the pattern, the evidence, the fix written as code or configuration, and the expected effect. A finding without a fix is a complaint.

Don't do these

  • Don't run a crawler and paste the output. Tools generate hundreds of issues that are mostly noise. Your value is deciding which twelve matter.
  • Don't report a score. No tool has access to Google's ranking signals, so any number out of 100 is invented. Say what's broken instead.
  • Don't sell llms.txt as a ranking fix. Google Search ignores it. Harmless to keep, dishonest to bill for.
  • Don't use robots.txt to deindex. Blocking a URL stops Google recrawling it, so an already-indexed page stays in the index with no snippet. Allow the crawl and serve noindex.
  • Don't ship a fix without a rollback. Redirects and canonicals are the two changes most likely to take a site down quietly.

Where the data comes from

Crawl stats, indexation counts, log-level bot activity and Core Web Vitals field data shouldn't be estimated. Search Console covers most of it for free and is the source of truth for how Google actually sees the site.

For continuous monitoring rather than a point-in-time audit, Keupera runs SEO and UX audits, Lighthouse blockers and an AI-crawler bot tracker in one workspace, and exposes them over MCP so an agent can pull real numbers:

claude mcp add --transport http keupera https://mcp.keupera.com/mcp -s user

Either way, never fill a gap in the data with a plausible-sounding figure. Mark it unknown and say what would answer it.

Related skills

canonical-duplicate-content, redirect-migration-plan, core-web-vitals, nextjs-seo, ai-crawler-policy, search-console-analysis, schema-markup

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.