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:
-
Business Context
- What's the product/service?
- Who is the target audience?
- What's the conversion goal for these pages?
-
Opportunity Assessment
- What search patterns exist?
- How many potential pages?
- What's the search volume distribution?
-
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?
-
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:
- Proprietary (you created it)
- Product-derived (from your users)
- User-generated (your community)
- Licensed (exclusive access)
- 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/
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" |
Read 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
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):
Technical SEO:
Internal linking:
Indexation:
Post-Launch Monitoring
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 Contract
Close every programmatic SEO pass with this block, filled in. Write the literal
templates: do not describe them.
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. When the sample fails or was
never run, report it 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 recommend one. Proceeding past the gate
is the user's call, per the gate policy above.
- 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.