suede-programmatic-seo

Files (5)

• CARD.md
• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• playbooks.md · references/

SKILL.md (first lines)

# 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](references/worked-contract.md). 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

| 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)

From JasonColapietro/suede-creator-skills, MIT.

More from JasonColapietro/suede-creator-skills