Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AgricIDaniel/claude-seo/llms.txt

Use this file to discover all available pages before exploring further.

Every Claude SEO audit walks a 10-principle thinking framework grouped into four phases before emitting a single finding. The framework is not a checklist — it is an ordered cognitive process that ensures recommendations trace back to first principles, account for cross-skill dependencies, survive a falsifiability test, and close with a feedback loop the user can monitor. The full per-principle SEO mapping lives in skills/seo/references/thinking-framework.md.

​
The Four Phases and Ten Principles

PhasePrinciplesWhat it does
PERCEIVEOBSERVE (external) · OBSERVE (internal) · LISTENCollect raw signals; audit your own assumptions; read what the SERP, the brand voice, and the community actually say
ANALYZETHINK · CONNECT (lateral) · CONNECT (system)Reduce to first principles; find non-obvious cross-skill links; sequence findings into a dependency graph
VALIDATEFEEL · ACCEPTPressure-test against UX, brand voice, and operator capacity; surface falsifiability for every claim
ACTCREATE · GROWShip the artifact; set the feedback loop for the next audit cycle
Full audits (/seo audit, /seo page) walk every phase before emitting the action plan. Narrower commands (/seo schema, /seo images, etc.) pass at least THINK + ACCEPT before emitting — sound first principle, surfaced falsifiability — even when the other phases are abbreviated.

​
Phase-by-Phase Breakdown

​
PERCEIVE Phase

The PERCEIVE phase is about gathering evidence before forming any opinion. It has three principles. OBSERVE (external) collects raw signals from outside the site: SERP features actually shown for target queries, competitor schema implementations, AI Overview citation patterns, Common Crawl domain-level metrics, and primary-source Google guidance published since the last audit. OBSERVE (internal) audits Claude SEO’s own assumptions. Before running analysis, the orchestrator checks whether its benchmark data is current (e.g., INP not FID, FAQPage no longer a rich-result type, the correct QRG version date), and whether the site has been audited before (drift baseline detection). This principle prevents confident-but-stale advice. LISTEN reads the signals the site itself and its community are already sending: brand voice in existing content, user-generated content patterns on Reddit and review platforms, GSC query data when credentials exist, GA4 organic landing-page data. The audit is more accurate when it works with the grain of the site rather than applying a generic template to it.

​
ANALYZE Phase

The ANALYZE phase converts raw signals into structured insights. It has three principles. THINK is the reduction-to-first-principles step. For each candidate finding, the orchestrator asks: what is the most basic SEO truth this observation rests on? A slow LCP traces back to server response time, render-blocking resources, or resource load time — not just “the site is slow.” Findings grounded at first principles produce fixes that actually resolve the root cause. CONNECT (lateral) finds non-obvious links between findings in different sub-skills. A canonical chain broken on programmatic pages (technical) is also an E-E-A-T signal degradation (content) and a schema self-referencing error (schema) — those three findings share a single root fix. Lateral connections collapse the action plan from dozens of findings to a handful of high-leverage changes. CONNECT (system) sequences all findings into a dependency graph. Some fixes are gates: a crawlability fix must ship before on-page optimizations have any ranking effect. Others are accelerators: fixing LCP before schema refinements means the schema changes land on a faster page. The dependency graph becomes the sequencing of the action plan.

​
VALIDATE Phase

The VALIDATE phase pressure-tests findings before they reach the user. It has two principles. FEEL checks each recommendation against UX, brand voice, and operator capacity. A technically correct fix that degrades the user experience or that requires engineering resources the team does not have should be flagged as such, not presented as a simple to-do. ACCEPT is the falsifiability gate. Every finding that survives to the action plan must answer four questions:
  1. What is the first-principle observation this finding rests on?
  2. What dependency relationships does it have with other recommendations?
  3. How would we know this failed? — the explicit failure-mode check.
  4. What leading indicator can the user monitor without re-running the audit?
Findings that cannot answer all four questions are dropped or demoted. This is the sharpest difference between Claude SEO and conventional audit tools.

​
ACT Phase

The ACT phase closes the loop. It has two principles. CREATE is the artifact step: ship the report, generate the schema block, write the sitemap, output the content brief. Claude SEO’s outputs are files you own — Markdown reports, JSON-LD blocks, XML sitemaps — not dashboard entries locked to a vendor. GROW sets the feedback mechanism. Every action-plan item specifies a leading indicator (GSC click-through rate trend, CrUX LCP field data, referring domain velocity, AI Overview citation count) so the user knows what to watch. The seo-drift skill operationalises this: it captures SQLite snapshots and compares them on the next run to surface regressions and confirm wins.

​
Falsifiable Recommendations

Falsifiability is the property that distinguishes a recommendation from a hypothesis. Claude SEO treats every audit finding as a hypothesis that must be falsifiable before it earns a place in the action plan. A falsifiable recommendation carries four fields:

First-Principle Observation

The most basic SEO truth the finding rests on. Not “your LCP is slow” but “the LCP element (hero image, 340 KB uncompressed) is loaded with a render-blocking <link rel='stylesheet'> above it in <head>.”

Dependency Relationships

Which other recommendations does this finding depend on, and which does it unblock? Surfaced by CONNECT (system) during the ANALYZE phase.

Failure-Mode Check

An explicit answer to “how would we know this failed?” A schema fix that passes Rich Results Test but doesn’t appear in SERPs within 30 days of indexation is a failure signal, not a success.

Leading Indicator

A metric the user can monitor without re-running the audit — CrUX LCP p75 trend, GSC impressions for target queries, CrUX INP field data, or referring domain count via the free Common Crawl integration.

​
Primary Source Alignment

Claude SEO grounds recommendations in primary sources only. The four canonical sources are: Google’s AI Optimization Guide (May 2026), the September 2025 Quality Rater Guidelines, Google Search Essentials, and web.dev. Recommendations that cannot be traced to one of these four sources (or to a directly supporting data signal like CrUX or GSC) are either dropped or clearly labelled as inference.
Current primary-source positions that differ from common SEO advice:
  • GEO/AEO = SEO. Google’s AI Optimization Guide states that AI Overviews and AI Mode are grounded in the same ranking systems as classic Search. “AEO” and “GEO” are rebranded labels, not distinct disciplines.
  • llms.txt is not a citation lever. Evidence-based reframe in skills/seo-geo/references/llmstxt-evidence.md: there is no primary-source confirmation that llms.txt influences AI Overview citation decisions.
  • FAQPage is no longer a rich-result type. Google retired FAQ rich results for all sites on May 7, 2026. FAQPage is still useful as an AI/entity signal and is flagged at Info (not Critical) when found; new FAQPage markup is not recommended for SERP benefit.
  • INP replaced FID. Interaction to Next Paint replaced First Input Delay on March 12, 2024. FID was removed from all Chrome tools on September 9, 2024. Claude SEO never references FID.
  • HowTo and several schema types are retired. HowTo rich results were removed in September 2023. ClaimReview, VehicleListing, EstimatedSalary, LearningVideo, SpecialAnnouncement, and CourseInfo carousel were retired in June 2025. Detecting these in <script type="application/ld+json"> blocks produces a Critical finding.

​
FLOW Framework Integration

The seo-flow skill integrates the FLOW framework (CC BY 4.0), a library of 41 evidence-led SEO prompts organized into five stages: Find, Leverage, Optimize, Win, and Local. FLOW is a companion knowledge base, not a parallel methodology — it feeds into the ACT phase by providing structured prompts for specific content and optimization workflows. When content-strategy signals are detected during a full audit, the orchestrator conditionally spawns the seo-flow agent, which selects the most relevant FLOW prompts for the site’s detected industry type and current audit findings. You can also invoke it directly: 
/seo flow find https://example.com
/seo flow optimize https://example.com/blog/post
/seo flow local https://example.com
The FLOW library is synced from its upstream repository via scripts/sync_flow.py, which respects the CC BY 4.0 attribution headers and supports --dry-run for preview.

​
Why Falsifiability Matters

Most SEO audit tools produce a list of findings ordered by severity. That list is useful but it answers only one question: “what is wrong?” Claude SEO’s methodology asks a harder question at every finding: “how would we know if fixing this actually worked?” Without a falsifiability check, an SEO recommendation is unfalsifiable in exactly the same way a horoscope is unfalsifiable — it can always be rationalised after the fact. With a falsifiability check, the user has a concrete criterion for success or failure that does not depend on re-interpreting ambiguous organic traffic trends six months later. The combination of first-principle grounding, dependency sequencing, failure-mode checks, and leading indicators produces an action plan that behaves more like a scientific protocol than an audit report: each recommendation is a testable hypothesis, and the leading indicator tells you whether the test is passing or failing in real time.

Build docs developers (and LLMs) love

Get started for freeTalk to us