---
name: "programmatic_seo"
description: "Design, build, and audit programmatic SEO page systems: template design, data sourcing, URL patterns, and quality gates that keep scaled pages on the right side of Google's scaled content abuse policy. Triggers on 'programmatic SEO', 'pSEO', 'pages at scale', 'template pages', 'location pages', 'comparison pages', 'integration pages', or any request to generate many similar SEO pages from data."
---

# Programmatic SEO

## Purpose

Plan and ship template-driven page systems (tens to thousands of pages) that survive Google's scaled content abuse policy. The skill covers opportunity scoring, data sourcing, template design, URL strategy, progressive rollout, and a local quality gate that flags thin content before anything publishes.

## Workflow

1. **Score the opportunity.** Confirm a repeatable query pattern with real long-tail demand: `[entity] + [modifier]` where the modifier is stable (Zapier's "[App A] + [App B]", Wise's "[Currency A] to [Currency B]"). Kill patterns that only exist to capture keyword variants. See `references/canonical_cases.md` for the seven proven shapes.
2. **Audit the data source.** Every record must carry enough unique attributes to make its page genuinely different from its siblings: CSV/API/DB rows need 5+ populated, differentiating fields. Flag records with >80% field overlap as duplicates. Stale data = stale pages, so verify freshness and update cadence now.
3. **Design the template.** Structure: title/H1/meta/schema with variable injection, static shared blocks (capped, clearly labeled), dynamic blocks unique per record, conditional sections that hide when data is missing, and supplementary blocks (related records, computed context). Hard rule: no mad-libs pages where only the city or product name changes. See `references/template_spec.md`.
4. **Lock the URL pattern.** Lowercase hyphenated slugs, no query params on primary content URLs, uniqueness enforced at generation time, logical hierarchy. See `references/url_patterns.md`.
5. **Run the quality gate.** Generate a sample batch, then run `bin/pseo-quality-check.py` against it. Fix what it flags before generating the rest. Do not skip this step.
6. **Roll out progressively.** Publish 50-100 pages, monitor indexing and rankings for 2-4 weeks, then expand. Never publish 500+ pages in one shot without a human-reviewed audit. Log the batch, the gate output, and the monitoring window in `references/rollout_log.md`.

## Output Contract

A finished engagement delivers: (1) a scored opportunity with the killed patterns listed, (2) a data source audit showing field uniqueness and freshness, (3) a template spec where static vs dynamic blocks are labeled, (4) the URL pattern with slug rules, (5) a passing quality-gate report on the sample batch, and (6) a rollout plan with monitoring windows.

## Operating Rules

- **The policy test is purpose, not method.** Google's scaled content abuse policy (March 2024) penalizes many pages generated primarily to manipulate rankings rather than help users, regardless of whether humans or machines made them. AI authorship is not the violation; scale plus unoriginality plus no user value is. Read `developers.google.com/search/docs/essentials/spam-policies` before any programmatic project.
- **Every page must pass the standalone test:** would this page be worth publishing even if no similar page existed? Would the data alone, without the template chrome, still be useful? If no, the record does not get a page.
- **30-40% genuinely unique content per page** is the working floor. Below 30% is a hard stop, not a warning. Word count floor is 300 per page (location pages: 500-600 at 60%+ unique).
- **Differentiated data is the moat.** A page that answers a question with data unavailable elsewhere in that form is safe. A page that says the same three things in AI-polished prose is exactly what the policy targets.
- **Site reputation abuse applies** when templated content goes under a domain that is not yours, or when third-party content publishes on yours without oversight. Treat that as a policy risk from day one.
- No spending, no crawling at hostile rates, no scraping copyrighted sources to build the dataset. Only use data you have rights to.