skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
boringmarketer/boring-marketing-skills122 installs

programmatic-seo

Validate, build, and ship a programmatic SEO library (one template × one dataset → 50-500 pages that each earn their existence with unique data). Use when a keyword pattern repeats across a modifier set (x for [industry], [city] x, x vs y, x alternatives, x integrations) and pages should be generated from data instead of written one at a time. A local service business that wants town or service-area pages uses /service-area-pages instead.

How do I install this agent skill?

npx skills add https://github.com/boringmarketer/boring-marketing-skills --skill programmatic-seo
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is generally safe but possesses an indirect prompt injection surface because it fetches and processes external data from search suggestions and web scraping to generate content without explicit sanitization. It also utilizes dynamic execution patterns by generating and running local scripts to automate the page build process.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Programmatic SEO

Turn one page template and one dataset into 50-500 pages that each deserve to exist. The real job is judgment, not generation: most PSEO fails because the pages differ only by find-replace, and Google's scaled-content enforcement plus LLM answer engines both reward pages where the data is the content. "Done" means a validated opportunity, a dataset with real per-row facts, a template that varies where it matters, pages that pass a uniqueness gate, and a measurement plan. This is the floor, not the ceiling. When the situation argues for a better path, take it and say why; the anti-doorway and data-honesty bars don't flex.

Context

Only if ./brand/, ./brands/ or MARKETING.md exists (nothing to load otherwise), run: python3 ${CLAUDE_SKILL_DIR}/../start-here/scripts/brand_context.py --for programmatic-seo (${CLAUDE_SKILL_DIR} is this skill's folder; outside Claude Code use the folder this file was read from, e.g. .agents/skills/programmatic-seo. If the script or python3 is unavailable, read the brand folder directly: ./brands/<slug>/ when ./brands/active names one, else ./brand/; then MARKETING.md, preferences.md and the files in reads:. If none exist, proceed standalone and ask only for the keyword pattern and what the business sells.)

Entry points

  • From /keyword-research: a cluster brief marked pseo-shaped arrives with the pattern, modifier candidates, and SERP notes. Skip straight to Phase 1's anti-doorway and dataset tests; the modifier-spread evidence is already in the brief.
  • Standalone: the user names a pattern ("a page for every Shopify app we integrate with"). Run all of Phase 1.
  • Local service business, town or service-area pages ("a page for every city we serve"): route to /service-area-pages, which qualifies each town on real local proof, and to /local-seo-plan first if nobody has decided which towns earn a page. Stay here only when the data itself is the page, for example a permit-cost index across 80 metros built from public records. A plumber's 40 town pages are not a dataset.
  • Resume: if ./campaigns/pseo-<slug>/ already has a validated dataset, pick up at the phase after the last saved artifact. Don't re-validate a shipped library; that's Phase 5's job.

The unit of work is a pattern: <head term> × <modifier set>, e.g. [app] + Shopify integration, payroll software for [industry], [tool] alternatives. One pattern per run. A user who wants three patterns gets three runs, prioritized.

Phase 1: Opportunity validation

This phase kills more projects than it approves, and that is the value. Load references/pseo-judgment.md before issuing a verdict. It carries the failure patterns, the policy line, and the winning archetypes. Run four tests; all four must pass.

Test 1: Modifier spread. Does demand actually fan out across the modifier set, or is it one head term wearing costumes? Verify, don't assume:

  • Pull autocomplete for the pattern stem: curl -s 'https://suggestqueries.google.com/complete/search?client=firefox&q=<stem>' across several modifier prefixes. Real spread shows distinct suggestions per modifier.
  • Fan out 3-4 subagents to fetch live SERPs for sample modifier queries (Firecrawl search if FIRECRAWL_API_KEY is set, else WebSearch/WebFetch). Each returns: who ranks, page type (editorial / aggregator / competitor PSEO), and how data-rich the winners are. If deep-data aggregators (G2-class, Zillow-class) own every sample SERP, a thinner version of the same table loses, so reshape toward modifiers they ignore.
  • LLM-demand counts too: patterns people ask assistants ("best <x> for <modifier>") are valid targets even when classic search volume reads near zero. Assess AI-surface citation opportunity with references/pseo-judgment.md.

We use DataForSEO for the spread check: real monthly search volumes for each modifier, so you see whether demand fans out instead of inferring it from autocomplete. It's pay as you go with no subscription ($50 minimum top-up that does not expire, plus a $1 trial credit on sign-up). Without it, the autocomplete spread and the sample SERPs above are the evidence, and no volume number gets printed.

Prove the pattern from a sample; never enumerate it. Two or more observed substitutions of the same frame prove the shape exists. Size the modifier list from the dataset you could build (Test 3), not from a volume tool's tail. With a volume API: one bounded expansion of the stem (location, language and a minimum volume set in the request, 10 to 25 rows), one batch volume call for your candidate modifiers (never one call per modifier), then filter in code before judging anything: keep rows that match the frame, collapse close variants (they're one intent, never added together), drop junk (jobs, free downloads, other countries, navigation to someone else's site). A phrase the tool returned "no results" for is an observed zero; one that errored is unknown. Pulling the whole tail and asking a model to sort it is the expensive way to learn what a sample already showed.

Test 2: The anti-doorway test. Pick two random modifiers and draft the honest one-paragraph answer for each. If the two answers differ only by the noun, this is one page pretending to be fifty, a doorway farm and the #1 PSEO failure. Each page must answer a distinct intent with distinct data. The uniqueness bar for the whole project: would a human who just read page 3 learn something on page 7 they couldn't have gotten from page 3? If no dataset could make that true, the verdict is NO regardless of search volume.

Test 3: Dataset feasibility. Can you actually get ≥3 facts unique to every row? Name the source now (Phase 2 ranks them) and spot-check 3 sample rows end-to-end. If unique facts exist for the top 20 modifiers but not the long tail, the right move is a smaller library: 60 strong pages beat 400 where 340 are padding.

Test 4: Domain capacity and ramp. A 10-page site publishing 500 pages overnight is a spam signal to Google and a crawl-budget problem besides. Judgment rule: a launch batch should not multiply the site's indexed page count by more than ~2-3×, and later batches wait on indexing evidence (Phase 4). A 15-page site wanting 300 pages gets a phased plan measured in months, and you say so now, not after the build.

Verdict (saved to ./campaigns/pseo-<slug>/validation.md, with a short Sources and assumptions note at its foot: what the verdict rests on in plain words, the dates, how many modifiers were sampled and how. The gap-aware receipt is at most 3 lines of that note: what was checked, what could not be, and, when the evidence is thin, one named gap with one offer to fill it, e.g. "unique facts were spot-checked for 3 rows only; want me to check 10 more before we commit?". Never present model knowledge as live research):

  • GO: all four pass; record the approved modifier list and target page count.
  • RESHAPE: the pattern is right but the scope is wrong: narrow the modifier set to where unique data exists, or pivot to an adjacent archetype from the judgment file.
  • NO: fails the anti-doorway or dataset test. Recommend 3-5 editorial pages on the strongest modifiers via /seo-content instead. Saying NO here is the senior move; shipping a doorway farm damages the whole domain, not just the new pages.

Phase 2: Dataset

The dataset IS the moat. Template quality is replicable in an afternoon; data is not. Source options, ranked (always state which tier the project uses):

  1. First-party data (best, uncopyable): the product's own integration catalog, usage stats, support-ticket themes, customer counts per segment, benchmark results. If the business has any of this, use it even when it's harder to extract. It's the only tier a competitor can't scrape back.
  2. Public datasets and APIs: census/government data, registries, package indexes, app-store APIs, open datasets. Free and accurate, but shared, so pair with at least one differentiating field from tier 1 or 3.
  3. Scraped + enriched: fan out one subagent per entity (or per batch of 5-10) to gather real facts: official docs, pricing pages, changelogs, reviews. Each subagent returns a structured evidence pack: field values + verbatim quotes + source URLs, not prose. Scrape, don't guess: a pricing figure or feature claim comes from a fetched page or it doesn't go in the dataset. We use Firecrawl for this: it reads, crawls and extracts structured fields from pages, which is the whole job here (free tier of 1,000 credits a month, no card). Without it, WebFetch per entity does the job, read as summaries, and each figure still needs its source URL.
  4. LLM-generated: connective prose ONLY: intros, transitions, summaries of facts already in the row. Never for facts. An invented "supports SSO: yes" on an integrations page is the fastest path to a page that embarrasses the brand and a dataset nobody can trust.

Schema design. Define columns before gathering. Two classes:

  • Identity fields: slug, name, modifier, category. These make the row addressable.
  • Uniqueness fields: the per-row facts that make each page worth reading: numbers, feature flags, dated events, verbatim quotes, entity-specific gotchas. Minimum viable: every row carries ≥3 populated uniqueness fields. Rows that can't meet the bar get dropped from v1, not padded. Keep them in a backlog list for later enrichment.

Add a sources column (URLs per row) and a last_verified date column. Phase 5 and future refreshes depend on both.

Output: ./campaigns/pseo-<slug>/dataset.csv (or .json for nested data), plus a one-paragraph data dictionary at the top of validation.md. Run a completeness check and report one line: rows total, rows passing the ≥3-fact bar, and rows dropped.

Phase 3: Template

The template is a page architecture, not a paragraph with holes in it. Spec it in ./campaigns/pseo-<slug>/template.md before generating anything.

Title / H1 pattern with variation rules. One syntactic frame across 300 titles reads robotic to humans and to classifiers. Define 3-4 title frames and assign by row attribute (e.g. integration pages: "Connect {A} to {B}" vs "{A} + {B} integration: setup, sync fields, limits" vs "How {B} data flows into {A}"). H1 may differ from title. Meta descriptions draw on a uniqueness field, never a shared sentence.

Answer-first block. The first 40-80 words after the H1 directly answer the page's query, naming the entity and 1-2 row facts. This block is what an LLM extracts when someone asks "best <x> for <modifier>". Write it as the quotable verdict, not a warm-up. This is the GEO layer's core: each page should be the cleanest extractable answer in existence for its exact long-tail query.

Body sections. Order: per-row unique sections first (the data: comparison table, feature breakdown, local stats, persona workflow), shared educational boilerplate last and short. Budget rule: shared boilerplate ≤50% of rendered word count; the uniqueness fields must visibly drive the majority of the page. If a section would read identically across rows, it belongs on the hub page, not repeated on every spoke.

FAQ from real per-entity questions. 3-5 questions sourced from PAA for that specific modifier, entity docs/community threads, or first-party support themes, not one question set with the noun swapped. If real questions only exist for some rows, the FAQ section is conditional, not padded.

Internal linking: hub and spoke.

  • One hub pillar page introduces the pattern, links to every spoke, and carries ItemList schema over the spokes.
  • Each spoke links: up to the hub (breadcrumb + contextual), and across to 3-5 related spokes chosen by a real relationship in the data (same category, adjacent modifier), not random, not all-to-all.
  • Breadcrumbs on every page (BreadcrumbList schema). No orphans: every generated page reachable within 3 clicks of the hub.

Schema. Hub: ItemList. Spokes: the type that matches the entity: SoftwareApplication, Product, LocalBusiness/Place, DefinedTerm for glossary, FAQPage only where the FAQ is real (and note: FAQ rich results are restricted to authoritative sites, so its remaining value is LLM parseability, which is reason enough). Never HowTo (removed by Google, Sept 2023).

GEO layer checklist per page: answer-first block; at least one citable stat or concrete fact with a source; entity named consistently (matching the schema name); dateModified accurate; if the project maintains llms.txt, add the hub there.

Phase 4: Build

Detect the target and actually generate. This skill ships pages, not specs.

  • Next.js project (App Router): one dynamic route under the hub path (app/<hub>/[slug]/page.tsx) with generateStaticParams reading the dataset file (commit the dataset into the repo, e.g. data/<pattern>.json), generateMetadata implementing the title frames, JSON-LD injected per page, and a hub page at app/<hub>/page.tsx. Static generation, not SSR; these pages don't change per request. Add the routes to the sitemap. Slugs are permanent: derive them from stable identity fields and never from display names that might get re-edited.
  • Plain HTML site: a generation script (scripts/generate_pages.py or .mjs in the campaign dir) that renders dataset → HTML files from one template, plus the hub and a sitemap fragment. Re-runnable: dataset edits regenerate cleanly.
  • No codebase (CMS, non-coder): one markdown file per page in ./campaigns/pseo-<slug>/pages/<slug>.md with frontmatter (title, meta description, schema JSON-LD block) ready to paste/import, plus an import note for their CMS.

Quality gate, template level. After generating, silently sample 5 random pages (random, not the 5 best rows) and score each against the uniqueness bar. The per-page results go in ./campaigns/pseo-<slug>/notes.md; the client sees only the passing library:

  • Page-7-vs-page-3 test passes (distinct facts a reader couldn't get elsewhere in the set)
  • ≥3 row-unique facts visibly rendered, boilerplate ≤50%
  • Answer-first block actually answers, names the entity, uses row data
  • Title frame varies across the sample; FAQ questions are entity-real
  • Internal links resolve and the related-spokes choice makes sense

If ANY sampled page fails, the fix is the template or the dataset, not that page: hand-patching one sampled page leaves the same defect on the 295 you didn't sample. Fix, regenerate, resample. About 3 rounds is the practical ceiling; past that the dataset is too thin, so go back to Phase 2 or cut scope, and say so in one line in the note.

Ramp / publish guidance. Publish in batches of 20-50 pages. Start with the hub plus the strongest-data batch. Before releasing the next batch: check GSC (or site:domain.com/<hub>/ as a weak proxy) for indexing of the prior batch. Most of it indexed and impressions appearing means proceed; widespread "Crawled - currently not indexed" means stop and improve quality before adding volume, because that status at scale is Google telling you the pages aren't clearing the value bar. Update the sitemap per batch; ping IndexNow if the stack supports it (reaches Bing and Copilot; ChatGPT uses its own index, so keep its crawlers allowed in robots.txt).

Phase 5: Measure

Write the measurement plan into validation.md at ship time; execution belongs to /performance-review on a monthly cadence.

  • GSC pattern check: filter pages by the hub path prefix. Track indexed count, impressions, clicks, and average position per batch. Healthy PSEO shows a long-tail curve (many pages with modest impressions), not five pages carrying everything.
  • Cull-or-improve rule: any page with 0 impressions after 60 days indexed gets one of three treatments: enrich (add real data), consolidate (merge into a sibling or the hub with a redirect), or remove (410/redirect). Never leave it: index bloat drags the whole domain's quality signals, so dead pages tax the pages that work.
  • LLM citation spot-check: quarterly, run 5-10 "best <x> for <modifier>" prompts against AI surfaces and record whether the library's pages get cited. This is the channel classic rank trackers miss and often where PSEO pays first.
  • Refresh trigger: last_verified in the dataset is the clock. Stale rows (per the data's natural decay: pricing quarterly, census yearly) get re-enriched and pages regenerated; dateModified must reflect real content changes only.

Output

Per the four-section contract (start-here/references/output-format.md):

  1. Header: ## PSEO LIBRARY: <pattern> plus one line of date and what the library is for. The verdict goes in the content, not the header.
  2. Content: verdict and why, dataset stats in one line (rows kept and dropped), template decisions, the batch plan, then the Sources and assumptions note (10 lines at most, gap-aware receipt at most 3 of them). No sample scores, data tags or tool names. validation.md runs about 1,200 to 2,500 words; the dataset, template and pages are their own files.
  3. Files saved:
    • ./campaigns/pseo-<slug>/validation.md
    • ./campaigns/pseo-<slug>/dataset.csv
    • ./campaigns/pseo-<slug>/template.md
    • ./campaigns/pseo-<slug>/notes.md (sampled-page checks, evidence packs)
    • generated pages (repo paths or ./campaigns/pseo-<slug>/pages/)
    • ./brand/assets.md (1 entry appended)
  4. What's next (below).

A NO verdict still ships validation.md; a documented kill is a deliverable.

What's next:

  • /seo-content: write the hub pillar to editorial depth, or the 3-5 pages a NO verdict recommends (~30 min)
  • /performance-review: schedule the monthly GSC pattern check + 60-day cull pass (~10 min)
  • /keyword-research: mine the next pseo-shaped cluster once batch 1 is indexing (~20 min)
  • /ai-search: share-of-model audit for the modifier queries this library targets (~15 min)

Or tell me what you're working on and I'll route you.

When the user edits your work

Apply the edit, then make it stick: save a gold case to ./brand/gold/<this skill>/ and one to three yes/no checks to ./brand/checks.md, and confirm in one line. Before handing over any work, answer the checks the context block loaded, silently, and fix every no. How: ${CLAUDE_SKILL_DIR}/../start-here/references/taste-loop.md.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/boringmarketer/boring-marketing-skills/programmatic-seo">View programmatic-seo on skillZs</a>