Skill: geoly-geo/geo-conversion-optimizer-2 (version 0.1.0)

--- name: geo-conversion-optimizer description: > GEO conversion optimization engine that balances AI citation readiness with real user conversion. Use this skill whenever the user wants content that both ranks well in AI answers and actually drives sign-ups, leads, purchases, or other business outcomes, not just “SEO/GEO for its own sake”. --- ## Overview `geo-conversion-optimizer` is a GEO (Generative Engine Optimization) conversion-focused skill. Its purpose is to help you systematically **optimize content for both**: - **AI / GEO performance**: structure, clarity, citability, schema, FAQ sections, etc. - **Real-world conversion**: sign-ups, purchases, demo requests, bookings, downloads, or other business KPIs. This skill exists to avoid the trap of **“content that AIs love but humans never convert on”**. Whenever you are asked to optimize or create content for GEO, **explicitly consider and protect conversion quality** using this skill. `geo-conversion-optimizer` can be used alone or together with other `geo-*` skills such as `geo-schema-gen`, `geo-bulk-processor`, and content-focused GEO optimizers. ## When to use this skill Always consider `geo-conversion-optimizer` when: - The user mentions **conversion**, **sign-ups**, **leads**, **sales**, **bookings**, **trial activations**, or **ROI**. - The goal is to **change or create content** for: - Landing pages and product pages. - Pricing pages and comparison pages. - Long-form articles with embedded calls to action. - Local / location pages that ultimately need calls, bookings, or visits. - The user is worried about trade-offs like: - “Will this hurt my conversion rate?” - “This feels written for bots, not people.” - “We optimized for AI but leads went down.” If the task is **purely informational** (for example, an internal knowledge base article with no conversion goal), you may not need this skill. But whenever **business outcomes** are in scope, prefer to invoke `geo-conversion-optimizer`. ## High-level workflow When this skill is invoked, follow this structured workflow: 1. **Clarify business and conversion goals** 2. **Map user and AI intents** 3. **Audit current content (if it exists)** 4. **Design a dual-track GEO + conversion strategy** 5. **Redesign structure, messaging, and CTAs** 6. **Plan measurement, experiments, and safeguards** 7. **Produce concrete deliverables and implementation notes** Each step is described below. ### 1. Clarify business and conversion goals Always start with the business outcome, not just “improve GEO”. - Identify: - **Primary conversion goal** (e.g., demo request, free trial, add to cart, book appointment). - **Secondary goals** (newsletter sign-up, add to wishlist, download content, account creation). - **Constraints**: - Brand tone and visual identity. - Legal / compliance requirements. - Traffic sources and existing funnels. - Ask (or infer) the **time horizon**: - Short-term campaign vs. always-on evergreen content. - Need for quick uplift vs. long-term learning and optimization. Document these clearly in the plan so all later choices can be traced back. ### 2. Map user and AI intents GEO content must serve **two overlapping but distinct “consumers”**: - The **human user** with: - A specific problem, job to be done, or context. - A stage in the funnel (awareness, consideration, decision, post-purchase). - The **AI model** that: - Needs clear structure, unambiguous facts, and stable patterns. - Prefers well-defined entities, relationships, and FAQs. Actions: - Define the **top 3–7 user intents** this page/content should satisfy. - For each intent, note: - Funnel stage. - Desired **next action** (what good looks like). - Potential **AI queries** or prompts that should surface this content. - Identify where **human and AI needs overlap**, and where they diverge. ### 3. Audit current content (if applicable) If the content already exists (e.g., a landing page or product page): - Evaluate **GEO readiness**: - Clear headings and structure? - Concise, factual sections suitable for AI summarization? - FAQs and schema present where appropriate? - Evaluate **conversion readiness**: - Clear primary CTA above the fold? - Compelling value propositions and social proof? - Friction points (confusing copy, missing information, trust gaps)? - Identify **points of conflict**: - Overloaded with keywords and robotic language. - Walls of text that harm scannability and decision-making. Summarize issues as **tensions** (e.g., “explains features well for AI, but hides pricing and CTAs”). ### 4. Design a dual-track GEO + conversion strategy For this skill, every recommendation should explicitly show how it serves **both tracks**: - **GEO / AI track**: - Improve structure, clarity, and citability. - Ensure important entities, relationships, and FAQs are explicit. - Align with relevant schemas (Article, Product, LocalBusiness, FAQPage, etc.). - **Conversion track**: - Prioritize information architecture that mirrors the decision journey. - Make CTAs, proof, and risk reducers visible and compelling. - Support multiple entry points (e.g., from AI answers deep-linking into sections). Define: - **Key sections** and their roles for both GEO and conversion. - **Message hierarchy** (what must be seen first vs. later). - **Non-negotiables**: - “These CTAs must remain above the fold.” - “These trust elements (logos, reviews) must be clearly visible.” ### 5. Redesign structure, messaging, and CTAs For the page or content in scope: - Propose a **section-by-section structure**: - Top hero: clear value proposition + primary CTA. - Problem / pain section. - Solution / product overview. - Proof (logos, testimonials, case snippets). - Detailed comparison, pricing, or feature breakdown. - FAQs (designed for both AI and human objections). - Supporting resources / long-form content if relevant. - For each section, specify: - **GEO role**: what entities, phrases, or queries it should help with. - **Conversion role**: what objection it answers, what action it nudges. - **Design notes**: any requirements for clarity, brevity, or visual emphasis. - Design **CTAs and microcopy**: - Primary and secondary CTAs with clear labels. - Contextual microcopy that reduces friction and fear (e.g., “no credit card required”, “cancel anytime”). Avoid sacrificing conversion just to “sound more GEO-friendly”. If a GEO change risks hurting clarity or trust, flag it and propose safer alternatives. ### 6. Plan measurement, experiments, and safeguards Always include a **measurement and experimentation plan**: - **Metrics**: - GEO / AI metrics: AI citation presence/coverage if available, impressions or traffic proxies. - Conversion metrics: CR%, CTR to CTA, lead quality indicators, downstream revenue where available. - **Experiments**: - A/B or multivariate tests on key elements (hero message, CTAs, FAQ section). - Controlled rollouts (e.g., a subset of traffic or a subset of pages). - **Safeguards**: - Baseline snapshots before changes. - Guardrail metrics (e.g., “do not accept a GEO uplift that causes >X% drop in CR”). Make sure the plan is practical for the user’s team and tools (e.g., GA, experimentation platform, internal dashboards). ### 7. Produce concrete deliverables and implementation notes Outputs should be **ready to act on**, not just high-level advice. Examples: - **Conversion-aware content blueprint**: - Section list, brief description, and GEO vs. conversion role per section. - **Copy and content recommendations**: - Example headlines, CTAs, FAQ questions and answers, proof elements. - **Integration notes for other `geo-*` skills**: - Where to call `geo-schema-gen` for structured data. - How to align with `geo-bulk-processor` if many similar pages must be optimized. - **Rollout and testing checklist**: - Steps for implementation, QA, and measurement. Be explicit about **what is opinionated guidance** vs. what is **strictly required**. ## Input and output expectations ### Inputs Expect to work with: - URLs, HTML/Markdown content, or copy drafts. - Screenshots, wireframes, or descriptions of current pages. - Conversion data (if shared) such as: - Current conversion rates. - Click maps, scroll depth summaries, or common user complaints. - Business constraints (e.g., mandatory legal text, forbidden claims). If information is missing, **state reasonable assumptions** instead of getting blocked, and clearly mark them as assumptions. ### Outputs Unless the user asks for something very specific, default to the following structures: - **Conversion-aware GEO optimization report** - Executive summary. - Business goals and constraints. - Main recommendations with GEO vs. conversion rationale. - **Page/content blueprint** - Section-by-section outline. - Key messages, CTAs, and proof elements. - GEO and schema notes. - **Experiment and measurement plan** - Proposed tests. - Metrics and guardrails. - Rollout and iteration approach. If the user wants directly usable copy, produce **draft copy** that already embeds both GEO and conversion principles. ## Use of bundled resources This skill ships with additional resources: - `references/conversion_playbook.md` - Contains patterns and checklists for balancing GEO and conversion across common page types (landing pages, product pages, blogs, local pages). - Provides ready-made section archetypes and objection-handling patterns. - `scripts/conversion_blueprints.py` - Contains simple data models and helper functions for representing page blueprints, CTAs, and experiments at a structured level. - Can be used as inspiration for how teams might represent and track conversion-aware GEO changes across many pages. Use these resources when you need more concrete examples or templates to structure your recommendations. ## Style and collaboration guidelines - **Think like a performance marketer plus GEO architect.** - Protect user clarity, trust, and intent-to-buy while also serving AI needs. - **Explain trade-offs.** - When a suggestion helps GEO but may harm conversion (or vice versa), make the trade-off explicit and offer alternatives. - **Be concrete and operational.** - Favor checklists, sections, and examples that can be implemented directly. - **Respect domain constraints.** - For regulated industries (health, finance, legal), be extra cautious about claims and wording. Encourage review by legal/compliance teams. The mission of `geo-conversion-optimizer` is to make GEO work for the business, not just for rankings or AI citations in isolation.

path: evals/evals.json
content: {
  "skill_name": "geo-conversion-optimizer",
  "evals": [
    {
      "id": 1,
      "prompt": "You are given a SaaS product landing page that drives free-trial sign-ups. The marketing team wants to make it more GEO-friendly so AI models will cite it for relevant queries, but they are afraid of hurting the trial signup conversion rate. Using the geo-conversion-optimizer skill, propose a new page structure and content strategy that balances AI citation readiness with trial conversion.",
      "expected_output": "A structured recommendation that (1) states the business and conversion goals; (2) maps user and AI intents; (3) proposes a section-by-section page blueprint with both GEO and conversion roles per section; and (4) includes a simple experiment and measurement plan with guardrail metrics for conversion rate.",
      "files": []
    },
    {
      "id": 2,
      "prompt": "An e-commerce brand has a high-traffic product detail page (PDP) for a flagship item. They want to retrofit it for GEO so it can appear in AI answers for \"best [product category] for [use case]\" queries, but previous SEO changes have reduced add-to-cart rate. Using the geo-conversion-optimizer skill, design recommendations that improve GEO and AI citability while protecting or improving add-to-cart conversion.",
      "expected_output": "A PDP-focused conversion-aware GEO plan that (1) clarifies primary and secondary conversion goals; (2) audits likely issues that past SEO/GEO changes caused; (3) defines key sections such as hero, benefits, proof, comparison, FAQs, and their GEO vs. conversion functions; and (4) suggests specific copy and CTA improvements plus an A/B test plan.",
      "files": []
    },
    {
      "id": 3,
      "prompt": "A B2B company uses long-form comparison articles (\"[Product] vs [Competitor]\") to feed their sales pipeline. These articles now receive traffic from AI recommendations, but sales says the leads are low intent and not converting. Using the geo-conversion-optimizer skill, redesign the content strategy for one comparison article to keep it attractive for AI while improving lead quality and sales conversion.",
      "expected_output": "A comparison-article strategy that (1) redefines the article's role in the funnel; (2) maps user and AI intents around comparison queries; (3) proposes a new outline that includes clear POV, qualification content, and targeted CTAs; and (4) outlines how to measure lead quality and protect sales conversion while adjusting for GEO.",
      "files": []
    }
  ]
}



path: references/conversion_playbook.md
content: # GEO + Conversion Optimization Playbook

This playbook supports the `geo-conversion-optimizer` skill. It
provides patterns and checklists for creating and refining content
that both:

- Performs well for GEO and AI citations.
- Drives meaningful business conversions (sign-ups, leads, purchases,
  bookings, etc.).

Use these patterns as defaults and adapt them to the specific product,
audience, and constraints of the user.

---

## 1. Core principles

1. **Start from the business outcome.**  
   GEO and AI visibility are a means, not an end. Clarify the primary
   and secondary conversion goals before touching structure or copy.

2. **Serve humans and AIs simultaneously.**  
   Good structure, clarity, and explicit answers help both human
   decision-making and AI understanding. Avoid writing “for bots”
   at the expense of human trust and clarity.

3. **Make trade-offs explicit.**  
   When a change risks harming conversion to improve GEO, or vice versa,
   call it out and suggest mitigations or experiments instead of hiding
   the tension.

4. **Design for journeys, not just pages.**  
   GEO may bring users into the site at many entry points. Clarify
   where each page sits in the funnel and which next steps it should
   drive.

---

## 2. Common page types and patterns

### 2.1 SaaS / product landing pages

**Goal:** Drive sign-ups, trials, demos, or qualified leads.

**Typical sections:**
- Hero (value proposition + primary CTA).
- Problem / pain section.
- Solution overview and key benefits.
- Social proof (logos, testimonials, metrics).
- Feature or capability breakdown.
- Pricing or plan overview (if appropriate).
- FAQs and objection handling.
- Supporting resources (case studies, guides).

**GEO considerations:**
- Use clear, descriptive headings that include the product category
  or job to be done.
- Make entities and relationships explicit: who it is for, what it does,
  which problems it solves.
- Include a focused FAQ block aligned with real queries and objections.

**Conversion considerations:**
- Ensure the primary CTA is visible and compelling above the fold.
- Use plain language that reflects how customers describe their problems.
- Provide enough proof (logos, quotes, numbers) for credibility without
  overwhelming the page.

### 2.2 Product detail pages (PDPs)

**Goal:** Drive add-to-cart and purchases.

**Typical sections:**
- Hero (product name, key benefit, price, primary CTA).
- Gallery or imagery.
- Core benefits and use cases.
- Detailed specs and technical details.
- Social proof (reviews, ratings, testimonials).
- Comparisons and alternatives.
- FAQs and support information.

**GEO considerations:**
- Use structured, scannable specs and attributes for AI and schema.
- Clearly articulate use cases and categories for “best for X” style
  queries.
- Provide FAQ content that answers common pre-purchase questions.

**Conversion considerations:**
- Make price, delivery, and return policies clear and easy to find.
- Reduce friction around commitment (e.g., guarantees, return windows).
- Highlight urgency or scarcity only when truthful and appropriate.

### 2.3 Comparison and “vs” content

**Goal:** Shape consideration and drive towards a preferred choice or
qualified lead.

**Typical sections:**
- Framing the comparison and intended audience.
- Side-by-side summary (table or bullets).
- Deep dives into key dimensions (features, support, pricing, fit).
- POV section (“When to choose A vs B”).
- Proof (case studies, quotes).
- FAQs about switching, migration, and risks.

**GEO considerations:**
- Use clear “A vs B” wording where appropriate.
- Explicitly list strengths and weaknesses for both options.
- Include neutral, factual information AIs can cite.

**Conversion considerations:**
- Ensure the preferred option’s ideal customer profile is clear.
- Provide CTAs that match intent (e.g., “Talk to sales”, “See migration
  plan”) instead of only generic sign-up.
- Avoid over-promising or misrepresenting competitors.

### 2.4 Local / location pages

**Goal:** Drive calls, bookings, or visits for specific locations.

**Typical sections:**
- Location name and primary service.
- Address, contact, hours, and map.
- Services and specialties at this location.
- Localized copy (city, neighborhood, landmarks).
- Social proof and local testimonials.
- FAQs (parking, insurance, preparation).

**GEO considerations:**
- Ensure consistent NAP (name, address, phone) and hours.
- Use LocalBusiness and related schema where appropriate.
- Include localized FAQ content aligned with real local queries.

**Conversion considerations:**
- Make booking or contact options obvious and easy to use.
- Surface key differentiators versus nearby alternatives (if known).
- Clarify insurance, payment, or eligibility where relevant.

---

## 3. GEO + conversion checklists

### 3.1 GEO readiness checklist

- Clear, descriptive H1/H2 headings that map to real queries.
- Concise summary of what the product/service is and who it is for.
- Explicit description of key entities and relationships.
- Structured sections for FAQs and key facts.
- Appropriate schema types identified (Article, Product, LocalBusiness,
  FAQPage, etc.).

### 3.2 Conversion readiness checklist

- Primary CTA visible without scrolling on typical devices.
- Copy clearly states the main benefit and outcome.
- Social proof is present and believable.
- Pricing or commitment expectations are not hidden.
- Common objections and questions are addressed.
- Friction is minimized (forms, required fields, unclear steps).

---

## 4. Experiment and measurement patterns

When applying GEO + conversion changes:

- **Baseline first.**  
  Capture current metrics (traffic, conversion, lead quality) before
  making changes.

- **Test focused changes.**  
  Group changes into coherent variants instead of changing everything
  at once when possible.

- **Use guardrails.**  
  Track key conversion metrics and set thresholds for acceptable
  degradation during tests.

- **Look beyond surface metrics.**  
  For B2B, lead quality and downstream revenue may matter more than
  form-fill conversion alone.

---

## 5. Using this playbook with the skill

When using `geo-conversion-optimizer`:

- Reference these patterns when designing page blueprints and
  recommendations.
- Explicitly call out which suggestions come from standard patterns
  and which are specific to the user’s case.
- Encourage the user to adapt and extend these patterns over time as
  they learn from experiments and performance data.

The goal is to make GEO work **with** conversion optimization, not
against it.



path: scripts/conversion_blueprints.py
content: """
Helper models and utilities for the geo-conversion-optimizer skill.

This module is intentionally lightweight. It is designed as a reference
for how to represent GEO + conversion-aware page blueprints, calls to
action (CTAs), and simple experiment plans in a structured way.

You do not need to execute this file to use the skill. Treat it as an
optional helper and source of inspiration for data structures that
product, marketing, and engineering teams can adopt.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional


@dataclass
class CTA:
    """
    Represents a primary or secondary call-to-action on a page.
    """

    id: str
    label: str
    goal: str  # e.g., "free_trial", "book_demo", "add_to_cart"
    priority: str = "primary"  # "primary" or "secondary"
    location_hint: str = ""  # e.g., "hero", "mid-page", "footer"
    notes: str = ""


@dataclass
class Section:
    """
    Represents a logical section of a page or long-form content.
    """

    id: str
    title: str
    description: str
    geo_role: str  # how this section helps GEO / AI
    conversion_role: str  # how this section helps conversion
    key_elements: List[str] = field(default_factory=list)
    ctas: List[CTA] = field(default_factory=list)


@dataclass
class PageBlueprint:
    """
    High-level blueprint for a single page, designed for both GEO and conversion.
    """

    page_id: str
    page_type: str  # e.g., "saas_landing", "pdp", "comparison_article", "location_page"
    primary_goal: str  # business KPI this page should move
    secondary_goals: List[str] = field(default_factory=list)
    assumptions: Dict[str, Any] = field(default_factory=dict)
    sections: List[Section] = field(default_factory=list)


@dataclass
class ExperimentPlan:
    """
    Simple representation of an experiment plan for GEO + conversion changes.
    """

    id: str
    hypothesis: str
    variants: List[str]  # e.g., ["control", "geo_conv_variant_A"]
    primary_metric: str  # e.g., "conversion_rate", "add_to_cart_rate"
    guardrail_metrics: List[str] = field(default_factory=list)
    notes: str = ""


def example_saas_landing_blueprint() -> PageBlueprint:
    """
    Return an illustrative blueprint for a SaaS landing page
    that needs both GEO improvements and strong free-trial conversion.
    """

    hero_cta = CTA(
        id="hero_free_trial",
        label="Start free trial",
        goal="free_trial",
        priority="primary",
        location_hint="hero",
        notes="Emphasize low friction (no credit card required, if true).",
    )

    hero_section = Section(
        id="hero",
        title="Hero: Clear value proposition",
        description="Top-of-page section that states who the product is for and what main outcome it delivers.",
        geo_role="Provides concise, entity-rich description of the product and category for AI to understand relevance.",
        conversion_role="Quickly answers 'what is this?' and 'is it for me?' while presenting a strong primary CTA.",
        key_elements=[
            "Primary headline that names the category or job-to-be-done",
            "Short supporting subheading",
            "Primary CTA button",
            "Optional secondary CTA for low-commitment action",
        ],
        ctas=[hero_cta],
    )

    faq_section = Section(
        id="faqs",
        title="FAQs and objection handling",
        description="FAQ block targeting the most common questions and objections about the product and trial.",
        geo_role="Provides structured Q&A content that is easy for AI to cite and map to user questions.",
        conversion_role="Reduces friction and anxiety by proactively answering key objections before sign-up.",
        key_elements=[
            "Top 5–10 questions mapped to real user concerns",
            "Short, factual answers aligned with legal/compliance requirements",
        ],
        ctas=[],
    )

    return PageBlueprint(
        page_id="example_saas_landing",
        page_type="saas_landing",
        primary_goal="free_trial_signups",
        secondary_goals=["newsletter_signups"],
        assumptions={
            "traffic_source": "mixed organic + AI-recommended traffic",
            "stage": "consideration_to_decision",
        },
        sections=[hero_section, faq_section],
    )


def example_experiment_plan() -> ExperimentPlan:
    """
    Return an illustrative experiment plan for testing a GEO + conversion variant.
    """

    return ExperimentPlan(
        id="saas_landing_geo_conv_test",
        hypothesis=(
            "Adding a structured FAQ section and clarifying the hero value proposition "
            "will increase AI citability and maintain or improve free-trial conversion rate."
        ),
        variants=["control", "geo_conv_variant_A"],
        primary_metric="free_trial_conversion_rate",
        guardrail_metrics=["bounce_rate", "time_on_page"],
        notes="Run for a sufficient period to reach statistical confidence; monitor trial-to-paid conversion downstream.",
    )


__all__ = [
    "CTA",
    "Section",
    "PageBlueprint",
    "ExperimentPlan",
    "example_saas_landing_blueprint",
    "example_experiment_plan",
]



Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)