# Alt Page > - Skill: `harsh719/alt-page` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add harsh719/alt-page` - Raw SKILL.md: https://api.skillmd.com/api/skills/harsh719/alt-page/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: harsh719 (https://skillmd.com/u/harsh719) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/harsh719/alt-page --- ## Before you run this skill This skill is brand-neutral. It reads its brand, palette and endpoints from `brand.config.json` at the repo root. **On first use, do this before anything else:** 1. Run `python3 brandkit.py`. It prints the config source and any placeholder that is still unset. 2. If it says `configured: False`, copy `brand.config.example.json` to `brand.config.json`. 3. Ask the operator for each value under `missing`, then write them in. Do not guess a brand name, a domain, or a colour. 4. Anything the skill writes out should be passed through `brandkit.fill(text)`, which swaps every `{{TOKEN}}` for its configured value and remaps the default palette to the operator's. Text below uses `{{TOKEN}}` where a value is operator-specific. Treat an unresolved `{{TOKEN}}` in your output as a bug, not as literal copy. ## Publishing: which CMS Never write CMS calls by hand in this skill. Use the shared adapter layer, which covers Strapi, WordPress, Contentful, Sanity, Ghost, Webflow, Payload, Directus, and plain files. ```python from cms import get_adapter, Page, CMSError cms = get_adapter() # reads cms.kind from brand.config.json page = Page(slug=slug, title=title, description=meta_desc, html=body_html, blocks=components, jsonld=graph) entry_id = cms.upsert(page) # ALWAYS a draft, whatever the CMS admin, public = cms.locate(page, entry_id) ``` Rules: - `upsert()` creates a draft. There is no way to publish through it, by design. - `cms.publish(page)` goes live. Call it **only** after the operator says so, for this page, in this session. Approval never carries forward. - If `cms.kind` is `none`, `get_adapter()` raises. Report that and offer `files`, which writes the page to disk instead, rather than guessing a CMS. - `python3 -c "import cms; print(cms.describe())"` tells the operator what is wired and whether that adapter has been verified live. - Only `strapi` and `files` are verified against real instances. For the rest, build the page, run the audit, then tell the operator to expect a possible field-name mismatch on the first push. # /alt-page — {{BRAND_NAME}} Alternative / Comparison Page Builder End-to-end skill that produces a {{BRAND_NAME}} alternative page ({{BRAND_NAME}}-vs-X) or A-vs-B comparison page (X-vs-Y, {{BRAND_NAME}} as third option), matching the design system, structure, and quality of the live references: - `/jotform-vs-typeform/` (A-vs-B, {{BRAND_NAME}} as third option) - `/google-forms-vs-microsoft-forms/` (A-vs-B, {{BRAND_NAME}} as third option) - `/fillout-alternative/` ({{BRAND_NAME}}-vs-X, canonical design source) - `/qualtrics-alternative/` ({{BRAND_NAME}}-vs-X, canonical FACT-PROCESS source — first page rebuilt under the research-first contract, 2026-08-10) The skill: 1. Collects the minimum required inputs from the user 2. Runs the full research protocol (SERP + content gap + AEO/LLM + first-party fact verification) BEFORE any copy 3. Generates the HTML component files matching the canonical design system 4. Assembles a standalone prototype.html for browser preview 5. pushes to your CMS as a draft page with each component as a separate `micro-components.raw-html` block 6. Runs the mandatory technical SEO + schema audit AND the final fact-check gate 7. Produces the per-page Source Document 8. Waits for user approval before publish, then flips `publishedAt` and confirms live rendering ## Core principle (governs every other rule) **Accuracy over assumptions. Research over copying. Useful information over word count. Human writing over AI-sounding SEO copy. Honest comparisons over exaggerated competitor criticism. User experience over search-engine manipulation. Verified facts over convenient claims.** The final page should read like it was written by someone who genuinely understands the competitor, understands {{BRAND_NAME}}, understands the search intent, and is helping the visitor make the right product decision. The goal is not simply to rank; the page is a decision-making resource. ## Rule A — Inspiration pages are design-only, never fact sources (GLOBAL HARD RULE) Root cause: the Aug 2026 factual audit found 4 alternative pages shipped with the inspiration page's facts (Wufoo's pricing tiers, "$0.05 overage", "owned by SurveyMonkey", "since 2006") left in place for different competitors, because components were cloned and find-and-replaced. This must never recur. - An internal inspiration/reference page may be reused ONLY for: page structure, information architecture, section structure, layout, design patterns, visual treatment, formatting, component patterns, UX approach. - NEVER carry over from an inspiration page: content, claims, facts, statistics, pricing, product information, competitor information, comparisons, sentences, or paragraphs. - **Research first. Writing second.** Every factual statement is independently researched and verified for THIS page's competitor. - Never assume information is correct because it exists on another {{BRAND_NAME}} page. Never copy incorrect information from one alternative page to another. Never guess or hallucinate. If information cannot be confidently verified, do not publish it as fact — flag it for the user instead. - Cloned template blocks that carry competitor-specific facts (pricing tables, "why teams leave" cards, honest-comparison cards, glance tables) must be REBUILT from fresh research for every new subject, never find-and-replaced. ## Rule 0 — Ask these inputs first (in this order) Before touching any file, ask the user each of these one at a time. Do not proceed until all are collected. After collection, echo the full input block back and ask "OK to proceed?" before starting the build. 1. **Page type** — one of: - `{{BRAND_NAME}}-vs-one` ({{BRAND_NAME}} positioned against a single competitor, e.g. `/fillout-alternative/`) - `a-vs-b` (two competitors compared head-to-head, {{BRAND_NAME}} enters as the third option, e.g. `/jotform-vs-typeform/`) 2. **Slug** — the URL path, kebab-case, no leading slash. E.g. `wpforms-alternative`, `jotform-vs-typeform`. 3. **Primary keyword** — target search term. E.g. `wpforms alternative`, `jotform vs typeform`. 4. **Competitor A** — brand name in correct casing (check the `competitor-research.md` dossier: `Jotform` not `JotForm`, `WPForms` not `WP Forms`, `forms.app` lowercase with dot, etc.). Also confirm the competitor's `/pricing/` URL. 5. **Competitor B** — same, only if page type is `a-vs-b`. Skip if `{{BRAND_NAME}}-vs-one`. 6. **Hero H1 override** — optional, one line, 40-60 chars. If skipped, the skill generates one following the pattern ` vs : the honest comparison` (a-vs-b) or `The alternative with <{{BRAND_NAME}} differentiator>` ({{BRAND_NAME}}-vs-one). ## Rule 0.5 — Research protocol (mandatory, BEFORE any copy is written) **The competitor is a VARIABLE, never a fixed subject.** Every research pass below targets the actual competitor of the page being created or updated, and switches automatically with the page: a Jotform Alternative build researches Jotform's SERP, pricing, features, limitations, G2/Capterra reviews, third-party sentiment, LLM/AEO presence, user pain points, competitors, and content gaps; a SurveySparrow build researches SurveySparrow's; and so on. The workflow and methodology stay constant, the research subject always follows the page. Reference implementation of the full protocol: the /qualtrics-alternative/ recreation (2026-08-10). After Rule 0 collects inputs and BEFORE any content is drafted, run ALL FOUR research passes. Never skip any of them — every content skill that shipped without this in 2026-07 landed with 0/4 LLM citations and wrong-intent positioning; every page that skipped fact research in 2026-08 shipped fabricated competitor facts. ### 0.5a — SERP research + content gap analysis (DataForSEO) Google SERP top-10 via DataForSEO Live SERP (US, desktop, depth 10). Extract top-10 organic, SERP features (AI Overview, PAA, Video pack, Related Searches, Discussions & Forums), and PAA questions verbatim. Firecrawl the top 5 commercial results: H2/H3 tree, word count, entity coverage, EEAT signals, distinctive sections. From the SERP set, identify: search intent, common topics, content structures, questions being answered, feature comparisons, pricing presentation, product limitations, switching considerations, common objections, competitor positioning, related searches, recurring terminology and entities. Then run the **content gap analysis** explicitly. Determine: what the top-ranking pages cover, what they cover poorly, what they completely miss, what users likely need but are not getting, what {{BRAND_NAME}} can explain better, and what unique information our page should include. Do NOT add content merely to increase word count — the gap analysis picks sections, it does not pad them. ### 0.5b — AEO / LLM research Probe how the competitor and category are represented in ChatGPT (via `gpt-4o-search-preview` citation probe × 4 query variants), and where available Claude/Perplexity (DataForSEO `ai_optimization` llm_responses). Parse `annotations[].url_citation` for cited domains and track {{BRAND_NAME}} mentions. Analyze: which products are recommended and why, common contextual queries, brand mentions, entity associations, sources being cited, authority signals, product positioning, common comparison questions, user questions, information gaps, and content structures LLMs lift from. Use this to make the page easy to understand, factually precise, entity-rich, contextually relevant, and citation-worthy — for users first, answer engines second. Do not write robotic content just to optimize for LLMs. ### 0.5c — First-party fact research (the fact base for every claim) For the competitor(s) on THIS page, research and record before writing: - Company: ownership, parent company, founders, founding year, HQ (newsroom/press releases/about page) - Product: real capabilities, real limitations, AI capabilities, integrations, enterprise features, offline/mobile support - Pricing: full current tier structure (see Rule P below) - Security/compliance: certifications actually held (never inferred) - Reputation: recurring strengths and complaints from G2/Capterra/Reddit — always kept attributed **Source priority (highest first):** 1. Official product website → 2. Official pricing page → 3. Official documentation → 4. Official help center → 5. Official company/about page → 6. Official press release → 7. Other authoritative sources. Never rely on SEO blogs or comparison sites when a first-party source is available. If an official pricing page renders via JavaScript and cannot be scraped, verify in a browser or flag it — never substitute a guess. Existing helpers: `competitor-research.md` dossier (8 tracked competitors — a starting point, ALWAYS re-verified against live sources, never treated as current), `memory/brand-facts.md` ({{BRAND_NAME}}'s own facts — canonical, §12 pricing), Firecrawl live scrapes of every competitor `/pricing/` + `{{SITE_HOST}}/pricing/` saved to `output/alt-pages//research/`. ### 0.5d — Synthesize and get approval Present the ranking-factor report: current state, SERP snapshot, competitor pattern, LLM citation status, content-gap findings, fact-base summary (with anything unverifiable flagged), proposed component/section plan, meta title + description, compliance framing decision. **Wait for explicit user approval before building.** ## Rule P — Pricing requires extra verification (HARD) Pricing is the most sensitive claim class on these pages. Before any pricing appears in copy: 1. Find the competitor's official pricing source and verify the current price there. 2. Determine whether the figure is monthly or annual billing, and whether annual billing is required to get it. Label the cadence in the copy. 3. Verify plan limits, free-plan limitations, feature restrictions, and usage/submission/response caps (including whether caps are per month, per year, or lifetime). 4. Record the source in the Source Document (Rule S). 5. Only then write the pricing into the page. Never copy pricing from another {{BRAND_NAME}} alternative page. Never assume an old price is still valid. Never infer pricing from third parties when official pricing exists. If pricing cannot be verified (e.g. quote-only vendors like Qualtrics), say that honestly on the page instead of inventing numbers; review-reported figures may be used only with explicit in-copy attribution ("reviews on G2 commonly report..."). ## Rule S — Source Document (one per page, organized SECTION-BY-SECTION, mandatory) Every alternative/comparison page ships with a separate clean source document. Sources are logged **under the page section they support**, not as one general list (format updated 2026-08-10). Structure: ``` ### Section: Why teams choose {{BRAND_NAME}} over [Competitor] | Source link | Information | |---|---| | | Exact claim/text this source supports | ### Section: How {{BRAND_NAME}} compares with [Competitor] | Source link | Information | |---|---| | | Exact claim/text this source supports | ``` ...continuing for every section that contains externally verifiable information. The **Information column carries the actual claim the source supports**, specifically — e.g. `G2 reviewers frequently mention ease of use and a lower learning curve as reasons for choosing lighter tools` — never "this source was used for the section". A human reviewer must be able to open any source and immediately see which part of the page it supports. No commentary, no methodology, no filler. Save as `output/alt-pages//sources.md` AND as a Google Doc (via `~/.claude/skills/gdoc/build_gdoc.py`, `GDOC_AUTH_DIR={{GOOGLE_AUTH_DIR}}`) titled ` — Source Document`, updated in place via `--doc-id` on subsequent runs. ## Rule E — Review-evidence hierarchy for switching-driver sections (mandatory) The **"Why teams choose {{BRAND_NAME}} over [Competitor]"** and **"Why teams leave [Competitor]"** sections are built primarily from INDEPENDENT third-party user evidence, never from {{BRAND_NAME}}'s own marketing claims about the competitor. Source priority: 1. **G2** (competitor's review pages, esp. "dislikes"/cons) 2. **Capterra** 3. Other reputable third-party review/aggregator platforms (TrustRadius, Software Advice, Gartner Peer Insights) 4. Independent industry publications/reviews 5. The competitor's own website/documentation (for capability facts, not sentiment) 6. Other reliable sources only when the above do not provide enough evidence Research recurring themes across reviews — ease of use, learning curve, setup/onboarding, pricing/value, complexity, user experience, flexibility, speed, small-team usability, feature accessibility, administrative overhead, workflow limitations, and other repeated pain points — and include ONLY themes the evidence actually supports. Distinguish "why users choose lighter alternatives" (what they value) from "why users leave [Competitor]" (their stated frustrations). **Never manufacture a pain point to make {{BRAND_NAME}} look better.** If review sources are thin on a claim, step down the hierarchy and verify, or drop the claim. Every theme used gets a row in the Source Document under its section. ## Rule C — On-page content hygiene (what never appears in user-facing copy) The published page must NOT contain: - Research notes, source links, or verification notes ("According to our research", "Based on our analysis", "We checked/reviewed...", "verified against each vendor's live pricing page") - Date-stamped verification lines: "As of [date]", "Checked [month/year]", "(checked August 2026)" — these read as editorial notes and go stale. Freshness belongs in `dateModified` schema and the Source Document, not in copy. (Flagged by Harsh 2026-08-10 on /qualtrics-alternative/.) - Research methodology, internal editorial notes, writer commentary - Unnecessary quotation marks around headlines, product descriptions, feature descriptions, or comparison statements — normal factual statements are not pseudo-quotes. Real quotations only when genuinely necessary and properly sourced. - Self-referential media captions ("Real {{BRAND_NAME}} UI, captured in-app", "actual product screenshot") — a caption may state only WHAT is shown ("Form builder, Design tab"), never that it is real/actual/captured. - Filler: generic introductions, "In today's..." openers, repetitive sections, unnecessary FAQs, generic conclusions, padding of any kind. Every section must have a clear purpose and provide genuine visitor value. Do not add sections solely because a competitor page has them or a keyword exists. In-copy attribution of review-sourced claims IS allowed and encouraged ("a steep learning curve is a recurring theme in G2 reviews") — that is honesty, not commentary. The line is: attribute claims naturally in prose; never annotate the page with the research process. ## Rule H — Honest comparison (content contract) The comparison must be genuinely honest. Never: manufacture competitor weaknesses, exaggerate {{BRAND_NAME}} advantages, misrepresent competitor features, use knowingly outdated information, make misleading comparisons, or present opinions as facts. The page must clearly cover, based only on verified differences: - **Where {{BRAND_NAME}} is stronger** (each item tied to a verified feature/plan fact) - **Where the competitor is stronger** — transparent, specific, useful - **Who should choose which product** — help the visitor self-select The **"When [Competitor] is still the better choice"** section gets a strong, polished presentation: real competitor strengths (certifications held, ecosystem depth, specialized tooling), concrete "choose them if" scenarios, and an honest-tradeoff line. It is a decision-making section, not an apology. Honesty increases trust and conversion. Reference implementation: /qualtrics-alternative/ (rebuilt 2026-08-10: certified enterprise research depth + XM-platform consolidation, both verified). Conversion frame — a visitor should be able to answer all ten within one scroll: (1) What is the competitor? (2) What does it cost? (3) What does it do well? (4) What are its limitations? (5) How does {{BRAND_NAME}} compare? (6) Where is {{BRAND_NAME}} better? (7) Where is the competitor better? (8) What does switching involve? (9) Which product is right for them? (10) What should they do next? ## Rule L — Competitor logos Every compared product carries its correct official brand mark — no generic icons, no placeholders, no AI-generated logos, no wrong marks. Standard implementation: Google favicon service `https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://&size=64` (renders the vendor's real favicon; use the product's own domain, e.g. `forms.office.com` for Microsoft Forms, gstatic's official Forms icon for Google Forms). Sizing/treatment is uniform page-wide: 20x20 (22-24px in pricing card headers), `border-radius: 4px`, inline-flex with 8px gap before the name. Logos appear in: glance table column headers, pricing card headers, vs-cards, and "other alternatives" cards. ## Rule V — Voice: world-class product-marketing copy (mandatory) The copy is written to the standard of a world-class product marketer and conversion copywriter, with visible command of user psychology, buying anxiety, friction, objections, emotional triggers, decision-making, product positioning, sentence rhythm, information hierarchy, and conversion psychology. The reader should feel: *"this company understands exactly why I'm considering leaving [Competitor], and they're showing me a better path."* The objective is never "salesy" — it is understanding, progressively built as the reader scrolls. **Write from the reader's perspective, not from a positioning framework.** Before drafting the hero, articulate what the searcher is actually thinking (e.g. for an enterprise-tool alternative: "this is more complicated than what we need", "why does a simple form require this much setup?", "we're paying for a huge platform for one workflow", "how fast can my team actually start?"). The hero must make that visitor feel "yes, this is exactly the problem I'm trying to solve" — not read a compressed summary of our positioning. **Banned constructions** (these read as AI even with perfect grammar): - Stacked-descriptor sentences: "X is enterprise-quoted, procurement-gated, and slow to onboard" — three compressed adjectives standing in for a real thought - The "X is this. Y is that." contrast formula, unless the sentence genuinely earns it - Words chosen for compression instead of natural communication; sentences that summarize a framework instead of talking to a buyer - Empty superlatives, excessive adjectives, artificial contrasts, repetitive structures, generic SaaS phrases, keyword stuffing, AI-style headings, predictable transitions, overly compressed sentences, em dashes - "In today's..." intros, repeated "whether you're..." and "from X to Y..." constructions, generic conclusions, generic CTA language, fake enthusiasm **Required:** natural sentence lengths (varied), strong verbs, specific language, concrete examples, human phrasing, appropriate emotional tension, clear explanations, transitions that connect sections, persuasive but honest positioning. **Every sentence must have a reason to exist. The copy must read naturally aloud** — read it aloud (mentally) as a gate. - **Run the `/humanizer` skill over every copy block** during writing and again before push. Non-negotiable. - **Style references (style ONLY, never content):** Jotform, ClickUp, monday.com alternative/comparison/product pages — sentence rhythm, tone, information density, how they explain differences, address objections, structure comparisons. Derive principles; write in {{BRAND_NAME}}'s own voice; never copy sentences. - Never write like: an SEO content generator, a template, a generic SaaS landing page, a feature comparison engine, or a corporate brochure. ## Rule N — Narrative arc + switching anxiety (page-level content design) The page is a story, not a stack of independent SEO sections. Target arc: **Problem → Friction → Recognition → Better alternative → Proof → Product experience → Confidence → Decision → Conversion** Scrolling top to bottom, the reader should naturally learn: (1) why [Competitor] may not fit them, (2) why other teams consider alternatives, (3) what {{BRAND_NAME}} does differently, (4) how it solves their specific frustrations, (5) what the product experience actually looks like, (6) why they can trust the comparison, (7) why switching is practical, (8) why it is worth trying now. Section subheads do transition work — each one picks up where the previous section left off; generic connective tissue is banned. **"How to switch" section — reduce switching anxiety.** The section exists to answer the reader's real question: *"if I move away from [Competitor], how hard is this going to be?"* The steps must feel simple, practical, predictable, low-risk, fast, and manageable, and be written specifically for someone migrating from THIS competitor (name its actual export screens and artifacts). Never a generic migration workflow. **Step 1 presentation:** the first step must make the reader think "this is what I would actually do first." Headline, supporting copy, and visual must reinforce each other; the visual shows the relevant product moment (real footage per Rule D), not a generic screen. If the right footage does not exist, ask for it. Steps flow visibly into each other (step 1's output is step 2's input). ## Rule D — Product demonstrations (real, PAGE-SPECIFIC footage only; updated 2026-08-11) A demo video/GIF must match the page it sits on. **Ask the user for the specific video associated with this page/competitor before building the demo section** — never drop in footage from another page because it exists, and never use generic or AI-generated video. A clip of the AI building a consent form does not belong on a survey-tool comparison; the mismatch reads as generic filler (flagged by Harsh 2026-08-10 on /qualtrics-alternative/). If the right footage does not exist yet, OMIT the demo section and request a recording; ship the section when the footage arrives. - Source walkthrough library: keep your own screen-recording clips in one place and reference them by filename. Use a clip ONLY where its content matches the section's story. - Never fabricate or simulate UI. **GIF/clip production pipeline (locked 2026-08-11):** cut from the page's Loom recordings → crop ALL recorder chrome and delogo the Loom bubble (it moves; probe its position per segment and time-gate delogo boxes if needed) → cut every loading state and idle stretch → ~2x speed → export GIF at 900px wide, 14fps, two-pass palettegen → upload to your CMS media library. Each embed ships `width`/`height` attributes (no CLS), `loading="lazy"`, descriptive alt, no authenticity captions. When the display slot is wider than ~700px, use an MP4 `