SEO Fundamentals

Shared knowledge and rules for the seo-machine plugin. Numbers (weights, thresholds, targets) live in ${CLAUDE_SKILL_DIR}/references/scoring-spec.md; evidence for mechanisms in ${CLAUDE_SKILL_DIR}/references/patent-signals.md. Read those two before scoring or recommending anything numeric.

Ground-truth rules (apply in every skill)

1. Never invent facts, data, people, quotes, or sources. Statistics, case studies, named individuals, proprietary numbers, and citations come only from the user, from fetched pages, or from search results you actually retrieved. If content needs such material and the user has not supplied it, write [NEEDS REAL DATA: what is needed] in place and list the gaps in the deliverable. Do not fill the gap with a plausible-sounding placeholder.
2. Never report "no schema found" from static HTML alone. WebFetch strips <script> tags and many CMSs inject JSON-LD client-side. Use python3 ${CLAUDE_PLUGIN_ROOT}/scripts/fetch_page.py <url> (raw HTML, parses JSON-LD), a browser tool, or Google's Rich Results Test; otherwise phrase as "not detected in static HTML — verify with Rich Results Test".
3. Measure, don't estimate. Word counts, readability, keyword density, heading frequency, and passage density come from python3 ${CLAUDE_PLUGIN_ROOT}/scripts/text_metrics.py. Estimate only when the script cannot run, and say so.
4. Every finding carries evidence (URL, line, tool output, GSC report). Use the severity levels in scoring-spec.md.
5. Cite mechanisms by tier. CONFIRMED → "must fix"; MECHANISM → "should fix"; INFERENCE → "worth doing". Never present a patent number as proof of production use.
6. Match the user's language for deliverables (PL/EN/DE/ES/FR/IT). Keep SEO terms in English where that is the industry norm.

Search intent

Classify every target keyword before creating or optimizing: Informational (learn), Navigational (reach a site), Commercial investigation (compare), Transactional (act). Content-intent mismatch is the most common reason good content fails to rank; check the content type of the current top 5 before choosing yours.

On-page elements

• Title tag — 50–60 characters, primary entity front-loaded, written as click copy (it is a NavBoost input; see references/navboost.md). Unique per page.
• Meta description — 150–160 characters, value + CTA, intent match. Unique per page.
• Headings — exactly one H1 containing the primary entity; 4–7 H2s; H3s under complex H2s; never skip levels. Phrase H2/H3 as the sub-question they answer and answer it in the first 40–60 words after the heading.
• URL — lowercase, hyphenated, 3–5 words, keyword included, ≤3 path levels.
• Placements — primary entity in title, H1, first 50 words as a sentence subject, 2–3 H2s, conclusion, slug, image alt where natural. Density is a spam floor (>3% critical), not a target.

Technical checklist

• Crawl & index: robots.txt not blocking key paths; XML sitemap with only canonical 200 URLs; self-referencing canonicals; noindex only where intended; hreflang for multi-locale sites (references/international-seo.md).
• Pagination: Google ignores rel="next"/"prev"; make every paginated page self-canonical and crawlable via real links, or offer a view-all page.
• Core Web Vitals: LCP <2.5 s, INP <200 ms, CLS <0.1, TTFB <800 ms. Field data from CrUX / PageSpeed Insights; lab data from Lighthouse. (The standalone Mobile-Friendly Test and the GSC Mobile Usability report were retired in late 2023 — use Lighthouse's mobile audit.)
• Infrastructure: HTTPS only, no mixed content, ≤1 redirect hop, no loops, one canonical host/slash/case form, zero internal 404s.
• Deep dives: references/technical-seo-deep-dive.md.

Structured data

Use JSON-LD. Templates: references/schema-markup-templates.md. Markup must describe content visible on the page; contradictions between schema and body are a policy violation and a trust problem (G4). Since 2023 FAQ rich results are limited to a few authoritative government/health sites and HowTo rich results no longer show — keep FAQ/HowTo markup only when the content is genuinely on the page and do not promise SERP enhancements from it. Declare sameAs for Organization, Person (authors), Brand, and LocalBusiness to authoritative profiles (Wikidata, LinkedIn, ORCID, Crunchbase, official registries). Validate with Rich Results Test and the Schema.org validator.

E-E-A-T as measurable signals

E-E-A-T is a Quality Rater framework, not an algorithm. Optimize the signals it emerges from:

• Experience — first-hand specifics from the author: real dates, versions, screenshots, own numbers, first-person stake, honest uncertainty. All of it must be real (ground-truth rule 1).
• Expertise — verified author entity: byline → dedicated author page → schema.org/Person with sameAs; multiple deep pieces on the same topic (G7).
• Authoritativeness — topical focus of the domain (siteFocusScore, Topic Authority), brand and brand+topic search demand, Knowledge Panel, links and mentions from topically relevant sources.
• Trustworthiness — schema ↔ body alignment (G4), corroborated facts from primary sources (G5), visible editorial standards (dates, corrections, sources), consistent NAP for local/brand entities.

YMYL topics (health, finance, legal, safety) require all four elevated; elsewhere Experience and Trust are the highest-leverage.

Internal linking

3–5+ contextual internal links per article with descriptive 2–5-word anchors; every cluster page links to its pillar and 2–3 siblings; the pillar links to every cluster page; no orphans; important pages ≤3 clicks from home.

Featured snippets and citable passages

Paragraph: 40–60-word direct answer right after a question H2. List: 5–9 items under a descriptive heading. Table: 2–4 columns. Definition: "[Term] is [definition]" as the first sentence. The same structure makes passages extractable for AI Overviews (G6).

References

• references/scoring-spec.md — all weights, thresholds, verdicts (read first)
• references/patent-signals.md — verified evidence per signal
• references/navboost.md — engagement signals and site-side proxies
• references/keyword-research-framework.md — research methodology, keyword mapping, cannibalization
• references/technical-seo-deep-dive.md — crawl budget, CWV fixes, indexation, soft 404s, mobile parity, findings format
• references/international-seo.md — hreflang, canonical × i18n, locale content quality
• references/schema-markup-templates.md — JSON-LD templates
• references/readability-formulas.md — formulas implemented by scripts/text_metrics.py