suede-programmatic-seo — Claude Code skill: setup and guide

---
name: suede-programmatic-seo
description: "Suede AI programmatic SEO for data-backed page systems at scale: location, persona, integration, comparison, template, glossary, and directory pages. Chooses the playbook, defines the data model and template, and enforces index-worthiness gates against thin, doorway, and scaled-content-abuse patterns, plus internal linking, sitemaps, phased rollout, and the KPIs that decide whether to expand. Use when planning, building, or rescuing many templated pages. NOT FOR: auditing an existing site (use suede-seo-audit); AI answer-engine visibility and measurement (use suede-ai-seo); planning editorial content (use suede-content-strategy); publishing bulk pages without approval."
metadata:
  version: 3.0.0
---

# Suede Programmatic SEO

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

| Playbook | Pattern | Example |
|---|---|---|
| Templates | "[type] template" | "invoice template" |
| Curation | "best [category] for [segment]" | "best CRM for agencies" |
| Conversions | "[X] to [Y]" | "kg to lbs" |
| Comparisons | "[X] vs [Y]" | "webflow vs wordpress" |
| Examples | "[type] examples" | "landing page examples" |
| Locations | "[service] in [place]" | "coworking in austin" |
| Personas | "[product] for [audience]" | "crm for real estate" |
| Integrations | "[A] [B] integration" | "slack asana integration" |
| Glossary | "what is [term]" | "what is churn rate" |
| Translations | localized versions | "/es/", "/de/" |
| Directory | "[category] tools" | "ai writing tools" |
| Profiles | "[entity]" or "[entity] [attribute]" | "stripe pricing history" |

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:

| KPI | Source | Expand when | Stop and fix when |
|---|---|---|---|
| Indexation rate (indexed / submitted per sitemap) | Search Console Pages | 70% or more | Below 60% |
| Pages with impressions / pages indexed | Search Console Performance | Rising | Flat after 60 days |
| CTR on the set vs site average | Search Console | At or above | Well below |
| Engaged sessions per page | GA4 | Comparable to hand-built pages | Near zero |
| Conversions from the set | GA4 | Positive and growing | None after 60 days |
| "Crawled, currently not indexed" count | Search Console | Falling | Rising |
| Manual actions | Search Console | None | Any: halt and remove |

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.

```text
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`.