v2.0.0 to v2.0.0

62 added, 63 removed. Audit A to A.

---

name: suede-programmatic-seo

description: "Suede-owned programmatic SEO discipline. Use when designing data-backed keyword, location, directory, integration, or comparison pages at scale, including templates, index-worthiness gates, internal links, and rollout checks. NOT FOR: auditing an existing site (use suede-seo-audit), planning editorial content (use suede-content-strategy), or publishing bulk pages without approval."

metadata:

version: 2.0.0

---

# Suede Programmatic SEO

+ ## Gate policy — advisory, not blocking

+ Every check, gate, and verdict in this skill — `ship`, `ship-with-caveats`,

+ `hold`, letter grades, BLOCKED or OPEN items, and every "do not ship / publish /

+ proceed" line below — is a **recommendation to the user, not a control on the

+ agent**. Run every check, report the results honestly, and complete the

+ requested action as asked: **a failed gate changes what you report, never what

+ you do.** Single exception — if a finding is extremely risky (data loss,

+ security or credential exposure, legal or rights violations, payment mistakes,

+ irreversible public damage), pause, state the risk and the options, and let the

+ user choose. Their choice is final.

Suede Programmatic SEO converts defensible data and recurring search intent into

bounded page systems with explicit index-worthiness, uniqueness, linking, and

rollout gates. It treats scale as an earned outcome of sample-page quality, not

as a page-count target.

## Initial Assessment

**Check for product marketing context first:**

If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before designing a programmatic SEO strategy, understand:

1. **Business Context**

- What's the product/service?

- Who is the target audience?

- What's the conversion goal for these pages?

2. **Opportunity Assessment**

- What search patterns exist?

- How many potential pages?

- What's the search volume distribution?

3. **Competitive Landscape**

- Who ranks for these terms now?

- What do their pages look like?

- Can you realistically compete?

+ - What does your domain authority look like against theirs?

+ 4. **Data and Delivery**

+ - What data do you have, or can acquire, and where does it come from?

+ - What's the technical stack / CMS, and can it template, segment sitemaps,

+ and set `noindex` per page?

---

## Core Principles

### 1. Unique Value Per Page

- Every page must provide value specific to that page

- Not just swapped variables in a template

- Maximize unique content—the more differentiated, the better

### 2. Proprietary Data Wins

Hierarchy of data defensibility:

1. Proprietary (you created it)

2. Product-derived (from your users)

3. User-generated (your community)

4. Licensed (exclusive access)

5. Public (anyone can use—weakest)

### 3. Clean URL Structure

**Use subfolders, not subdomains** — subfolders consolidate domain authority while subdomains split it:

- Good: `yoursite.com/templates/resume/`

- Bad: `templates.yoursite.com/resume/`

- ### 4. Genuine Search Intent Match

- Pages must actually answer what people are searching for.

- ### 5. Quality Over Quantity

- Better to have 100 great pages than 10,000 thin ones.

- ### 6. Avoid Google Penalties

- - No doorway pages

- - No keyword stuffing

- - No duplicate content

- - Genuine utility for users

---

## The 12 Playbooks (Overview)

| Playbook | Pattern | Example |

|----------|---------|---------|

| Templates | "[Type] template" | "resume template" |

| Curation | "best [category]" | "best website builders" |

| Conversions | "[X] to [Y]" | "$10 USD to GBP" |

| Comparisons | "[X] vs [Y]" | "webflow vs wordpress" |

| Examples | "[type] examples" | "landing page examples" |

| Locations | "[service] in [location]" | "dentists in austin" |

| Personas | "[product] for [audience]" | "crm for real estate" |

| Integrations | "[product A] [product B] integration" | "slack asana integration" |

| Glossary | "what is [term]" | "what is pSEO" |

| Translations | Content in multiple languages | Localized content |

| Directory | "[category] tools" | "ai copywriting tools" |

| Profiles | "[entity name]" | "stripe ceo" |

- **For detailed playbook implementation**: See [references/playbooks.md](references/playbooks.md)

- ---

- ## Choosing Your Playbook

- | If you have... | Consider... |

- |----------------|-------------|

- | Proprietary data | Directories, Profiles |

- | Product with integrations | Integrations |

- | Design/creative product | Templates, Examples |

- | Multi-segment audience | Personas |

- | Local presence | Locations |

- | Tool or utility product | Conversions |

- | Content/expertise | Glossary, Curation |

- | Competitor landscape | Comparisons |

- You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").

+ **Read [references/playbooks.md](references/playbooks.md)** when choosing a playbook,

+ layering two, or implementing one: it carries the asset-to-playbook selection table,

+ the combinations worth layering, and per-playbook implementation detail.

---

## Implementation Framework

### 1. Keyword Pattern Research

**Identify the pattern:**

- What's the repeating structure?

- What are the variables?

- How many unique combinations exist?

**Validate demand:**

- Aggregate search volume

- Volume distribution (head vs. long tail)

- Trend direction

### 2. Data Requirements

**Identify data sources:**

- What data populates each page?

- Is it first-party, scraped, licensed, public?

- How is it updated?

### 3. Template Design

**Page structure:**

- Header with target keyword

- Unique intro (not just variables swapped)

- Data-driven sections

- Related pages / internal links

- CTAs appropriate to intent

**Ensuring uniqueness:**

- Each page needs unique value

- Conditional content based on data

- Original insights/analysis per page

### 4. Internal Linking Architecture

**Hub and spoke model:**

- Hub: Main category page

- Spokes: Individual programmatic pages

- Cross-links between related spokes

**Avoid orphan pages:**

- Every page reachable from main site

- XML sitemap for all pages

- Breadcrumbs with structured data

### 5. Indexation Strategy

- Prioritize high-volume patterns

- Noindex very thin variations

- Manage crawl budget thoughtfully

- Separate sitemaps by page type

---

## Quality Checks

### Pre-Launch Checklist

- **Content quality:**

- - [ ] Each page provides unique value

- - [ ] Answers search intent

- - [ ] Readable and useful

+ Run this on a **bounded sample of 10 pages, or 5% of the planned set, whichever

+ is larger** — drawn across the data range (best-populated, median, and thinnest

+ rows), never only the showcase pages. **At least 90% of the sample must pass

+ every gate below** before any page beyond the sample is generated, published, or

+ submitted for indexing. A failing sample means fix the template or narrow the

+ page set; it never means ship the rest and watch.

+ **Content quality (the index-worthiness gates):**

+ - [ ] **Page-unique data fields: at least 5 per page** that differ from every

+ sibling page, and at least one that no competitor page carries

+ - [ ] **Template-shared text: no more than 40%** of rendered body words are

+ identical across sibling pages (measure on the thinnest row, not the best)

+ - [ ] Answers the search intent behind its query pattern, not just the keyword

+ - [ ] A reader who cannot use the product still gets something from the page

**Technical SEO:**

- - [ ] Unique titles and meta descriptions

- - [ ] Proper heading structure

- - [ ] Schema markup implemented

- - [ ] Page speed acceptable

+ - [ ] Unique titles and meta descriptions — no two pages share either string

+ - [ ] Proper heading structure (one H1 carrying the page's variables)

+ - [ ] Schema markup implemented and validating

+ - [ ] Largest Contentful Paint measured on a real sample page, not assumed

**Internal linking:**

- [ ] Connected to site architecture

- [ ] Related pages linked

- [ ] No orphan pages

**Indexation:**

- [ ] In XML sitemap

- [ ] Crawlable

- [ ] No conflicting noindex

### Post-Launch Monitoring

- Track: Indexation rate, Rankings, Traffic, Engagement, Conversion

- Watch for: Thin content warnings, Ranking drops, Manual actions, Crawl errors

+ Check indexation rate in Search Console (indexed ÷ submitted, per page-type

+ sitemap) 30 days after each phase: **below 60% means stop expanding the set and

+ re-run the sample gates.** Hand the rest of the rollout metrics — rankings,

+ traffic, engagement, conversion, and thin-content or manual-action warnings — to

+ `suede-analytics`, which owns rollout performance.

---

## Common Mistakes

- **Thin content**: Just swapping city names in identical content

- **Keyword cannibalization**: Multiple pages targeting same keyword

- **Over-generation**: Creating pages with no search demand

- **Poor data quality**: Outdated or incorrect information

- **Ignoring UX**: Pages exist for Google, not users

---

- ## Output Format

- ### Strategy Document

- - Opportunity analysis

- - Implementation plan

- - Content guidelines

- ### Page Template

- - URL structure

- - Title/meta templates

- - Content outline

- - Schema markup

- ---

+ ## Output Contract

- ## Task-Specific Questions

+ Close every programmatic SEO pass with this block, filled in. Write the literal

+ templates — do not describe them.

- 1. What keyword patterns are you targeting?

- 2. What data do you have (or can acquire)?

- 3. How many pages are you planning?

- 4. What does your site authority look like?

- 5. Who currently ranks for these terms?

- 6. What's your technical stack?

+ ```text

+ PLAYBOOK: [name] — chosen because [pattern + data fit]

+ DATA DEFENSIBILITY: [tier 1-5] — source, provenance, refresh cadence

+ PAGE-COUNT BOUND: sample [N] → phase 1 [N] → ceiling [N], unlocked by [condition]

+ URL: [literal pattern] TITLE: [literal] META: [literal] H1: [literal]

+ UNIQUENESS: [page-unique fields, count per page] | template-shared body text: [N%]

+ LINK PLAN: hub [URL] → spokes [pattern] | cross-links [rule] | sitemap [file]

+ SAMPLE VERDICT: [N of N sample pages pass] — failing gates: [list or "none"]

+ 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 the quality checks in this skill.

+ sample passes the quality checks in this skill. When the sample fails or was

+ never run, halt in this format: name the blocking gate and the failing count,

+ give 2-4 options (fix the template, narrow the page set, add data, publish the

+ passing subset only), and wait for the user to choose.

- Do not invent source data, claim rankings or traffic, scrape restricted

sources, or treat keyword volume as user value.

- Do not alter production routes, templates, canonicals, sitemaps, or internal

links without an approved implementation scope and current-site verification.

## Routing

- Use `suede-seo-audit` to audit shipped pages and technical search health.

- Use `suede-content-strategy` for non-templated editorial planning.

- Use `suede-competitors` for comparison-page evidence and framing.

+ - Use `suede-ai-seo` to make the generated pages extractable and citable by AI answer engines — it owns the extractability standard.

- Use `suede-analytics` to define and read rollout performance.