Programmatic SEO

Use this skill when the task is to build SEO pages at scale from repeatable keyword patterns, structured data, and reusable renderers.

The goal is not to mass-produce thin pages. The goal is to build useful, indexable, differentiated page families where each page has a reason to exist.

Agent Contract

You are an expert in programmatic SEO. Decide whether a pSEO system should exist, design the page-family architecture, define the data and schema contracts, create sample outputs, and specify rollout and measurement.

Do not start by writing pages. Start by proving the pattern, data source, uniqueness model, and quality gate.

Use When

Use for:

• Programmatic SEO or pSEO strategy.
• Template pages.
• Pages at scale.
• Directory pages.
• Location or service-area pages.
• [keyword] + [city] pages.
• Comparison page families.
• Integration page families.
• Product or service variant pages.
• Profile or entity pages.
• Repeated long-tail SEO opportunities.

Do not use for a normal bespoke landing page, homepage, flagship service page, or one-off blog unless it is part of a scalable page family.

Core Rule

AI content should be built, not written.

The AI fills strict JSON schemas with niche-aware structured data. Purpose-built renderers handle presentation. Content data and design templates do not mix.

This lets the system:

• Redesign page layouts without regenerating content.
• Regenerate content without changing templates.
• Validate content before publishing.
• Batch pages progressively.
• Improve the system from GSC, GA4, ranking, and conversion feedback.

Initial Assessment

Before recommending pSEO, answer:

1. What business, product, or service is this for?
2. Who searches for this page family?
3. What conversion should these pages drive?
4. What repeatable keyword pattern exists?
5. What are the variables in the pattern?
6. How many possible pages exist?
7. How much search demand exists across the pattern?
8. Who ranks now, and what kind of page are they ranking with?
9. What proprietary, product, user, licensed, or public data can make each page unique?
10. What site stack will render and publish these pages?

If the answer is mostly "we only have city names and generic copy," do not proceed.

Fit Test

A pSEO project is a good fit when:

• Keyword research reveals 50 or more viable pages with the same repeatable structure.
• The brand has natural taxonomy dimensions such as product, use case, city, room type, audience, make, model, year, integration, competitor, or category.
• Pages can be populated from real data, not filler prose.
• The site has enough authority or internal architecture to support the page family.
• The team can monitor indexation and prune weak pages.

A pSEO project is a bad fit when:

• There are fewer than 10-20 pages.
• Pages would only swap names or cities.
• There is no differentiated data.
• Existing pages already satisfy the intent.
• The keyword pattern is informational but the proposed page is sales-first.
• Nobody will maintain taxonomy, schemas, renderers, or the performance loop.

Data Defensibility

Prefer data sources in this order:

1. Proprietary data created by the brand.
2. Product-derived data from catalog, usage, users, inventory, locations, or integrations.
3. User-generated or review-derived data.
4. Licensed or partner data.
5. Public data.

Public data alone is weakest. If public data is used, add proprietary interpretation, tooling, filtering, comparison, or local expertise.

Workflow

1. Validate The Keyword Pattern

Identify:

• Repeating query structure.
• Variables.
• Possible page count.
• Existing ranking pages.
• Search intent for head and long-tail terms.
• Whether one page type can satisfy all variants.

Use search volume, GSC queries, ranking data, or SERP inspection. Do not build a page family from intuition alone.

2. Build The Taxonomy First

For every taxonomy node, capture:

• Audience.
• Intent.
• Pain points.
• Key specs or attributes.
• Related products, services, or pages.
• Local or niche context.
• Competitive landscape.
• Required source facts.
• Internal links.
• Page eligibility status.

Drop taxonomy nodes with no search signal, no unique data, or high cannibalization risk.

3. Define Page Families

A page family is a repeatable content type with a shared structure.

Examples:

• Vehicle or product hub pages.
• Local service pages.
• Use-case pages.
• Comparison pages.
• Integration pages.
• Resource or checklist pages.
• Directory pages.
• Tool pages.

Do not force all intents into one renderer.

4. Design The JSON Schema

Each page family needs a strict JSON schema defining:

• Page type.
• Slug rules.
• Title and meta templates.
• Required sections.
• Field types.
• Minimum and maximum array lengths.
• Allowed enums.
• Source fields.
• Internal-link fields.
• FAQ fields.
• Schema.org fields.
• Validation rules.

Titles should usually be deterministic templates, not AI-generated guesses.

5. Generate Structured Data

When using an LLM:

• Provide brand context.
• Provide taxonomy node context.
• Provide source facts.
• Provide the JSON schema.
• Request native JSON output.
• Reject markdown wrappers.
• Validate every output before storage.

The model fills data. The renderer creates the page.

6. Validate Outputs

Block pages when:

• JSON fails schema validation.
• Required fields are missing.
• Arrays are too short or padded with filler.
• Claims are unsupported.
• Product specs are fabricated.
• Pages are too similar to one another.
• Copy violates brand rules.
• The page cannibalizes an existing URL.
• Internal links are missing.
• Schema markup cannot be generated cleanly.

7. Build Specialized Renderers

Each page family gets its own renderer or template. Include:

• H1 and SEO metadata.
• Useful page-specific sections.
• Data-driven tables, cards, filters, or tools where appropriate.
• Breadcrumbs.
• Internal links.
• Related pages.
• CTA matched to intent.
• FAQ markup when useful.
• Relevant structured data such as Product, LocalBusiness, Service, BreadcrumbList, FAQPage, or ItemList.

Keep content JSON and renderer code separate.

8. Roll Out Progressively

Do not deploy everything at once.

Use batches:

1. Generate 10-20 sample pages.
2. Human-review the samples.
3. Fix taxonomy, schema, and renderer issues.
4. Deploy 50-100 pages.
5. Submit sitemap or batch to GSC.
6. Wait for indexation data.
7. Expand, pause, prune, or rework based on evidence.

If indexation rate drops below roughly 50 percent after two weeks, stop expanding and investigate quality, crawlability, duplication, and architecture.

9. Monitor And Feed Back

Track:

• Pages published.
• Pages indexed.
• Keywords ranking.
• Organic sessions.
• Engagement.
• Conversions.
• Internal-link performance.
• Page-family winners and losers.

Use this loop to expand winning taxonomy nodes, prune weak nodes, consolidate cannibalized pages, improve schemas, improve renderers, and add missing data sources.

Quality Test

For every page, ask:

1. Would this still be useful if search engines did not exist?
2. Would someone bookmark this page or use it again?
3. Does this page contain information meaningfully different from sibling pages?
4. Can every factual claim be traced to a source or known brand/product data?
5. Is this page reachable from the site architecture without relying only on a sitemap?

If the answer is no, the page should not ship.

Required Output

When this skill runs, return:

1. Fit decision: proceed, narrow, or do not proceed.
2. Keyword pattern and intent summary.
3. Taxonomy dimensions and candidate page count.
4. Data source inventory and defensibility rating.
5. Page-family architecture.
6. JSON schema outline.
7. Renderer/template outline.
8. Internal-linking plan.
9. Indexation and rollout plan.
10. QA checklist.
11. Open risks and missing inputs.

Use references/work-order-template.md when the user needs a reusable work order.

References

• references/playbooks.md: the 12 pSEO playbooks and when to use each one.
• references/pseo-2.0-process.md: deeper schema-first process, rollout model, and guardrails.
• references/work-order-template.md: agent-ready work order and JSON skeleton.

Common Failure Modes

• City-name swaps with no local substance.
• Programmatic pages competing with bespoke core service pages.
• Generating pages before defining taxonomy.
• Letting AI invent product specs or service claims.
• One generic template for multiple intents.
• Missing internal links and breadcrumbs.
• Publishing thousands of pages before Google validates the first batch.
• Treating sitemap inclusion as architecture.
• Ignoring GSC after launch.