Suede Programmatic Seo

Suede AI Programmatic SEO Skills

Compatibility

Requires a source dataset with reuse rights, query-pattern evidence, and page/template access. Current search policies require browsing. Local planning/building needs no new integration; publication requires authority.

For a concrete input, expected output, recovery path, and validation check, read the worked contract. Use it to check the handoff before treating the task as complete.

Programmatic pages work when each one answers a real query with data the searcher cannot get faster elsewhere. They fail, and can drag the whole site down, when they are one template with a swapped city name. This skill treats page count as something a sample earns, never a target.

Gate policy: advisory, not blocking

Every gate and verdict here is a recommendation to the user, not a control on the agent. A failed gate changes what you report, never what you do. Single exception: an extremely risky finding (data loss, credential exposure, legal or rights violations, payment mistakes, irreversible public damage) pauses for the user's choice.

The policy line you must stay behind

Google's spam policies name three patterns programmatic sites trip most:

• Scaled content abuse: many pages generated mainly to manipulate rankings or AI answers and not to help people, whatever tool produced them.
• Doorway abuse: sites or pages created to rank for similar queries that funnel users to the same destination ("[service] in [city]" pages with nothing local on them).
• Site reputation abuse: third-party pages published on a host site to borrow its ranking signals with little first-party oversight.

Google also says AI answers need no special pages; producing variants for AI is the same abuse. Every gate below exists to keep a page set on the right side of this line. Source: https://developers.google.com/search/docs/essentials/spam-policies

Initial assessment

Read .agents/product-marketing.md (or .claude/product-marketing.md, or the legacy product-marketing-context.md) if present. Then establish:

1. Business: product, audience, the conversion each page should earn.
2. Pattern and demand: the repeating query pattern, its variables, how many combinations have evidence of demand (Search Console, Keyword Planner, or a dated export; otherwise unknown).
3. Competition: who ranks now, what their pages contain, and whether you can offer something they do not.
4. Data: what populates each page, where it comes from, how often it refreshes, and whether you have the rights to publish it.
5. Delivery: CMS or framework, and whether it can template, split sitemaps, and set noindex and canonicals per page.

Data defensibility

The data decides whether the set is worth building. Rank it:

1. Proprietary (you created it: usage stats, tests, benchmarks)
2. Product-derived (aggregated from your users, with consent)
3. User-generated (reviews, submissions, community)
4. Licensed (exclusive or contracted)
5. Public (anyone can publish it; weakest, needs real added analysis)

A set built only on tier-5 data needs an original layer (scoring, comparison, calculation, local verification) or it is a doorway set.

Playbooks

Read references/playbooks.md when choosing, layering, or implementing one. It holds per-playbook value requirements, URL patterns, and the asset-to-playbook table.

Implementation

1. Pattern and demand

Name the pattern, the variables, and the candidate list. Keep only combinations with demand evidence or a clear reader need. Combinations with no evidence wait for phase 2 or never ship.

2. Data model

One row per page. Columns for every page-unique field, its source, its last-verified date, and a publish flag computed from the gates below. Rows that fail stay in the table with publish = false.

3. Template

• H1 and title that carry the page's variables naturally.
• A direct answer in the opening that uses the row's own data ("Median [metric] in [city] was [value] in [month year], per [source]"), never generic copy.
• Data sections that render only when the row has the data (conditional blocks, not empty placeholders).
• An original layer: a calculation, ranking, comparison, or note that exists only because you combined the data.
• Related-page links and a CTA matched to intent.
• Schema only where a supported feature fits; BreadcrumbList and Organization via a shared @id are usually safe.

4. Internal linking

• Hub pages per category and per parent (city, industry, integration category) that link to every published child.
• Children link to the hub, to siblings that share a real relationship (nearby cities, adjacent integrations), and to the main product page.
• No orphans: every published page reachable within three or four clicks from the home page through crawlable <a href> links.
• Breadcrumbs, visible and marked up.

5. Indexation

• One sitemap per page type so indexation can be read per set.
• Rows below the gates are not generated, or are generated with noindex and left out of the sitemap until they pass.
• Self-referencing canonicals; no canonicalizing many thin pages to one hub as a substitute for not publishing them.
• Use subfolders under the main domain unless there is a technical or organizational reason for a subdomain; Google treats both as crawlable, but a subdomain is managed and measured as a separate property.
• Crawl budget matters only for very large sets (tens of thousands of URLs or more); below that, quality gates are the constraint.

Quality gates

Run on a sample of 10 pages or 5% of the planned set, whichever is larger, drawn across the data range (best-populated, median, thinnest rows), never only showcase pages. At least 90% of the sample must pass every gate before generating, publishing, or submitting anything beyond the sample. A failing sample means fix the template or shrink the set.

Index-worthiness (content)

• At least 5 page-unique data fields differ from every sibling, and at least one is not on any competing page you checked
• Template-shared text is 40% or less of rendered body words, measured on the thinnest row
• The opening answers the query with this row's data, not generic copy
• An original layer exists (calculation, ranking, comparison, verified local detail)
• A reader who never buys the product still leaves with something useful
• Facts carry a source and a last-verified date

Doorway test

• Swap the variable (city, persona, tool) with a sibling's: if the page still reads as true, it fails
• Pages do not all funnel to one destination with nothing in between
• No near-duplicate pages for synonyms of the same query ("CRM for realtors" and "CRM for real estate agents" is one page)

Technical

• Unique title, meta description, and H1 per page
• Schema validates and matches visible content
• Core Web Vitals measured on a real sample page (field data where available), not assumed
• Mobile render checked

Linking and indexation

• Linked from a hub and from at least one sibling
• In the right per-type sitemap, crawlable, no conflicting noindex

Rollout and KPIs

Ship in phases: sample, then phase 1 (the strongest rows), then expansion only when phase 1 earns it. Read these at 30 and 60 days after each phase:

These thresholds are Suede defaults; adjust them to the user's baseline and record the change. Hand ongoing reporting to suede-analytics.

Common mistakes

• City or persona swapped into identical copy (doorway).
• Pages for combinations nobody searches.
• Stale or unverified data presented as current.
• Canonicalizing hundreds of thin pages instead of not publishing them.
• Generating AI-written filler to hit a word count.
• Publishing the full set before the sample passes.

Output Contract

Close every programmatic SEO pass with this block. Write the literal templates.

textCopy code
PLAYBOOK: [name], chosen because [pattern + data fit]
DATA DEFENSIBILITY: [tier 1-5], source, rights, provenance, refresh cadence
ORIGINAL LAYER: [what exists only because the data was combined]
PAGE-COUNT BOUND: sample [N] -> phase 1 [N] -> ceiling [N], expansion condition [KPI threshold]
URL: [literal pattern]   TITLE: [literal]   META: [literal]   H1: [literal]
OPENING ANSWER TEMPLATE: [literal, with data variables]
UNIQUENESS: [page-unique fields per page] | template-shared body text: [N%]
DOORWAY TEST: [pass/fail on sample, examples]
LINK PLAN: hub [URL] -> spokes [pattern] | cross-links [rule] | sitemap [file]
SAMPLE VERDICT: [N of N pass], failing gates: [list or "none"]
KPI PLAN: [metrics, sources, 30/60-day thresholds]
SHIP GATE: ship | ship-with-caveats | hold, reason

Boundaries

• Do not generate, publish, submit, or index a full page set before a bounded sample passes. When the sample fails or was never run, name the blocking gate and failing count, give 2 to 4 options (fix the template, narrow the set, add data, publish the passing subset), and recommend one. Proceeding is the user's call.
• Do not invent source data, claim rankings or traffic, scrape sources whose terms forbid it, or treat keyword volume as user value.
• Do not alter production routes, templates, canonicals, sitemaps, or internal links without an approved scope and current-site verification.

Routing

• Audit shipped pages and technical health: suede-seo-audit.
• Make the set quotable and measure AI citations: suede-ai-seo.
• Editorial (non-templated) planning: suede-content-strategy.
• Comparison-page evidence and framing: suede-competitors.
• Interactive tools as page anchors: suede-free-tools.
• Rollout reporting: suede-analytics.