Skill: geoly-geo/geo-bulk-processor (version 0.1.0)

--- name: geo-bulk-processor description: > GEO bulk processing engine for large-scale, multi-page content optimization. Use this skill whenever the user mentions bulk GEO changes, batch content updates, large websites, sitemaps, content libraries, or needs to process many URLs/documents in one workflow, not just a single page. --- ## Overview `geo-bulk-processor` is a GEO (Generative Engine Optimization) bulk processing orchestrator designed for **large sites and content libraries**. It helps an agent: - Design and run **batch optimization pipelines** over thousands of pages or documents. - Standardize **templates and patterns** for repeated page types. - Track **progress, quality, and rollout phases** instead of treating each page as an isolated “single-shot” task. Use this skill when the user: - Manages a **large website**, multi-language site, or content library. - Wants to **bulk retrofit** existing pages for GEO readiness, AI citations, or structured data. - Provides **sitemaps, URL lists, spreadsheets, or exports** from CMS/analytics tools. - Needs a **repeatable, scalable workflow** instead of one-off page edits. This skill focuses on **planning, orchestration, and consistency**. It does not tie you to any specific GEO framework, but is optimized to work well with the family of `geo-*` skills (e.g. content optimizers, schema generators, local optimizers). ## When to use this skill Always consider using `geo-bulk-processor` when: - The user mentions **“bulk”, “batch”, “mass update”, “large site”, “thousands of pages”, “entire catalog”, “all blog posts”**, or similar language. - The user shares **CSV/Excel exports, sitemaps, URL lists**, or folders of content files. - The user wants to **apply similar GEO strategies across many items** (e.g., all product pages, all location pages, all support articles). - The task obviously **cannot be solved efficiently by optimizing a single page at a time**. If the request is clearly about **one page or a very small number of pages** (e.g., “fix GEO for this single article”), prefer the more focused single-page GEO skills instead of this bulk processor. ## High-level workflow When this skill is invoked, follow this structured workflow: 1. **Clarify the bulk goal** - Identify the **primary GEO goals** (e.g., AI citations for specific queries, better structured data, consistent FAQ blocks, improved internal linking). - Ask what **content universe** is in scope (full site, one section, specific content types, language variants, etc.). - Ask about **constraints** (timelines, systems, headcount, tech stack, allowed file formats, risk tolerance). 2. **Ingest and profile the corpus** - Accept inputs such as: - URL lists or sitemaps (XML, CSV, plain text). - Content exports from CMS (CSV, JSON, Markdown/HTML files). - Analytics exports (top pages, landing pages, long-tail queries). - Build a **lightweight inventory summary**: - Number of items by content type, language, directory, or template. - Obvious **clusters** (e.g., `/blog/`, `/product/`, `/docs/`, `/locations/`). - Known **GEO gaps** (missing schema, thin pages, duplicated structures). 3. **Define content clusters and page types** - Group content into **clusters** that can share the same optimization strategy: - By URL pattern, content type, template ID, language, or topic. - For each cluster, define: - A **page-type definition** (what the pages are, who they serve, business role). - The **GEO opportunities** specific to that cluster. - Risks and **special constraints** (e.g., legal wording, regulated content). 4. **Design bulk GEO pipelines** - For each cluster, design a **pipeline** describing: - **Inputs** (fields from the CMS/CSV, existing content fields, metadata). - **Transformations** (rewrites, new sections, schema generation, FAQ extraction). - **External skills/tools** to call (e.g., schema generators, content optimizers). - **Outputs** (updated HTML/Markdown, JSON fields, CSV columns, migration specs). - Capture pipelines in a **structured, reusable format**, using the guidance in `references/bulk_pipelines.md`. 5. **Create reusable templates and patterns** - For each major page type, define: - A **content skeleton** (sections, headings, FAQs, schema blocks). - **Variable slots** tied to data fields (e.g., product name, city, category). - Style and tone expectations (aligned with GEO and brand constraints). - Make these templates **explicit** so they can be applied programmatically to many items. 6. **Plan execution and rollout** - Propose **phased rollout**: - Pilot set → expansion → full coverage. - For each phase, specify: - **Sample size**, selection criteria, and evaluation plan. - **Success metrics** (GEO readiness scores, AI citation coverage, traffic proxies). - **Feedback loop** and how to adjust templates/pipelines between phases. 7. **Generate concrete artifacts** - Depending on user needs, generate: - A **master plan document** summarizing clusters, pipelines, and rollout. - **CSV/JSON specs** for engineers or operators to implement changes. - Example **before/after** content and schema for each major page type. - Use `scripts/geo_bulk_pipeline.py` **conceptually** as a helper reference: it describes how to represent content items, clusters, and pipelines in code or data. You do not have to execute it, but you may mirror its structures. 8. **Quality assurance and risk management** - Recommend: - **Sampling and manual review** before full rollout. - **Regression checks** for critical pages (homepage, top products, legal pages). - **Monitoring plan** for GEO and traffic indicators after deployment. ## Input formats and expectations Typical inputs for this skill: - **URL lists / sitemaps** - Plain-text lists of URLs. - XML sitemaps (possibly multiple). - **Spreadsheets / tables** - CSV or Excel exports listing URLs, titles, categories, traffic, etc. - **Content exports** - Folders of HTML/Markdown files. - CMS exports with JSON per document. When possible, normalize these into a **tabular or record-based view**: - One row or record per content item. - Columns / fields for URL, path, language, category, template, and any key metrics. If files are not already in a structured format, design and describe a **simple manifest format** that the user’s team can produce (for example, a CSV with `id,url,type,cluster,language` columns). ## Output expectations Unless the user asks for something highly specific, structure your main outputs as: 1. **High-level GEO bulk strategy** - Clear description of scope, goals, and constraints. - Overview of clusters, page types, and priorities. 2. **Cluster-by-cluster plan** - For each cluster: - Description and rationale. - Proposed pipeline steps and external skills/tools. - Suggested templates and content patterns. 3. **Implementation-ready specifications** - Tables or pseudo-schemas describing: - Required input fields and data sources. - Output fields/files and where they should be written. - Recommended automation approach (ETL, scripts, CMS workflows). 4. **Rollout and QA plan** - Phased rollout with criteria and success metrics. - QA checklists for sampling and sign-off. - Monitoring and iteration loops. When the user explicitly requests machine-consumable artifacts (for example, “give me a CSV spec that my data team can use”), prioritize **precise, unambiguous formats** (clear column names, data types, and examples). ## Use of bundled resources This skill ships with additional reference material and helper code: - `references/bulk_pipelines.md` - Explains common GEO bulk pipeline patterns. - Provides example cluster definitions, pipeline step types, and rollout patterns. - Read this when you need inspiration for how to structure pipelines or explain them to the user’s team. - `scripts/geo_bulk_pipeline.py` - Contains **lightweight data models and helper functions** that show one way to model content items, clusters, and pipelines. - You can mirror its structures when designing data formats, but you do **not** need to execute it to complete user requests. - If the environment allows executing scripts, they can be adapted into real automation helpers, but this skill does not require that. When in doubt, prefer **clear written plans and specs** over over-engineered code. The primary value of this skill is in **designing scalable GEO bulk workflows**, not in implementing full production systems inside the skill. ## Style and collaboration guidelines - **Think like a systems designer.** - Aim for solutions that will still work when the corpus doubles or triples. - Avoid plans that require per-page manual tweaking unless limited to a small, high-value subset. - **Explain the “why”, not just the “what”.** - Connect GEO decisions (clusters, templates, schema types) to the user’s business goals and constraints. - **Be opinionated but adaptable.** - Suggest defaults and best practices, but clearly mark them as such. - Offer alternative paths when user constraints are unclear or strict. - **Make it easy to operationalize.** - Prefer concrete artifacts: specs, templates, checklists, and example records. - Avoid vague recommendations that cannot be turned into tickets or automation. If the user already uses other `geo-*` skills, explicitly reference where they fit into each pipeline step (for example, “use `geo-schema-gen` here to generate Product and FAQ schema for this cluster”).

path: evals/evals.json
content: {
  "skill_name": "geo-bulk-processor",
  "evals": [
    {
      "id": 1,
      "prompt": "You are given a CSV of 5,000 blog URLs for a B2B SaaS company, with columns for URL, title, primary topic, and monthly visits. Using the geo-bulk-processor skill, design a batch GEO optimization plan that groups URLs into clusters and defines reusable templates and pipelines for each cluster.",
      "expected_output": "A structured bulk GEO plan that (1) defines 3-8 content clusters, (2) describes for each cluster the GEO opportunities, proposed templates, and pipeline steps, and (3) outlines a phased rollout plan with pilot, expansion, and full deployment.",
      "files": []
    },
    {
      "id": 2,
      "prompt": "A multi-location healthcare provider has 1,200 location pages across several cities and specialties. They provide a sitemap XML plus a table with columns: url, city, specialty, visits_last_90d. Use the geo-bulk-processor skill to design a scalable GEO bulk upgrade plan for these location pages.",
      "expected_output": "A GEO bulk strategy that clusters the 1,200 location pages, defines page-type templates for key combinations (e.g., city + specialty), specifies what structured data and FAQ patterns to standardize, and describes how to phase rollout and QA the changes.",
      "files": []
    },
    {
      "id": 3,
      "prompt": "An e-commerce brand has 15,000 product detail pages plus 300 category pages exported from their CMS as JSON (one file per page). They want to retrofit the whole catalog for GEO and AI citations without hand-editing every page. Use the geo-bulk-processor skill to propose a bulk processing architecture and concrete implementation-ready specifications.",
      "expected_output": "An architecture and specification document describing: (1) how to inventory and cluster products and categories; (2) pipeline definitions for products and categories, including how to invoke other geo-* skills where appropriate; (3) the schemas for input and output records (fields, types, and examples); and (4) a rollout, QA, and monitoring plan.",
      "files": []
    }
  ]
}



path: references/bulk_pipelines.md
content: # GEO Bulk Pipelines Reference

This document provides reference patterns and terminology for the
`geo-bulk-processor` skill. It is meant to help you design GEO bulk
pipelines that are **scalable, repeatable, and easy to operationalize**
across large websites and content libraries.

You do not need to follow these patterns rigidly. Instead, use them as
default building blocks and adapt them to the user’s actual systems,
constraints, and goals.

---

## 1. Core concepts

- **Content item**  
  A single page or document (e.g., one URL, one CMS entry, one file).

- **Cluster**  
  A group of content items that share similar purpose, structure, and
  GEO opportunities (for example, all /blog/ posts, all product detail
  pages, or all city-based location pages).

- **Page type / template**  
  A reusable structure for a set of pages. One cluster may map to a
  single page type or a small number of closely related page types.

- **Pipeline**  
  A sequence of steps that transform inputs (existing content, metadata,
  analytics) into outputs (GEO-optimized content, structured data,
  import files for CMS, etc.).

---

## 2. Typical pipeline phases

Most GEO bulk pipelines can be expressed using four high-level phases:

1. **Inventory and normalization**
2. **Content and metadata enrichment**
3. **Schema and technical enhancements**
4. **Export, rollout, and monitoring**

You can design one pipeline per cluster or page type, using these phases
as anchors.

### 2.1 Inventory and normalization

Objectives:
- Build a reliable, structured view of the content corpus.
- Normalize disparate sources into a single schema.

Common steps:
- Ingest sitemap(s) and URL lists.
- Join analytics or search data (visits, conversions, queries).
- Add CMS or product catalog data where available.
- Normalize into a table or record schema with fields such as:
  - `id`
  - `url`
  - `path`
  - `content_type`
  - `language`
  - `cluster`
  - `priority`

### 2.2 Content and metadata enrichment

Objectives:
- Strengthen content quality and structure for GEO.
- Ensure key elements are present and consistently formatted.

Common steps:
- Generate or refine titles, intros, and key sections using GEO-focused
  templates.
- Add or improve FAQ blocks aligned with target queries.
- Standardize internal linking patterns (e.g., to categories or hubs).
- Add or normalize metadata (e.g., canonical tags, language tags).

This is where other `geo-*` skills (for example, content optimizers)
integrate most heavily.

### 2.3 Schema and technical enhancements

Objectives:
- Make content machine-readable for AI and search engines.
- Align schema with content types and business goals.

Common steps:
- For products: Product, Offer, Review, FAQ schema.
- For locations: LocalBusiness, Organization, BreadcrumbList.
- For articles: Article, BlogPosting, FAQPage.
- For documentation: TechArticle, FAQPage, BreadcrumbList.

This phase is a natural integration point with skills like
`geo-schema-gen`.

### 2.4 Export, rollout, and monitoring

Objectives:
- Deliver outputs in formats that implementation teams can use.
- Phase changes to manage risk and measure impact.

Common steps:
- Export CSV/JSON for CMS or deployment pipelines.
- Generate implementation guides or mapping tables.
- Define rollout phases (pilot → expansion → full roll-out).
- Design monitoring dashboards and GEO metrics tracking.

---

## 3. Example cluster patterns

Below are some common cluster patterns. Adapt and extend them based on
the user’s site and goals.

### 3.1 Blog / editorial content

- **Cluster definition**: URLs under `/blog/` or `/insights/`.
- **Goals**:
  - Improve coverage for topic + intent queries.
  - Standardize structure (intro, key takeaways, FAQs).
  - Strengthen internal linking to product/docs.
- **Key pipeline elements**:
  - Content enrichment with GEO-aware headings and summaries.
  - FAQ extraction or generation.
  - Article/BlogPosting + FAQPage schema where appropriate.

### 3.2 Product detail pages (PDPs)

- **Cluster definition**: URLs under `/products/` or by template ID.
- **Goals**:
  - Make product attributes and benefits machine-readable.
  - Improve comparability and clarity for AI answers.
  - Increase long-tail and “best for X” coverage.
- **Key pipeline elements**:
  - Normalize product attributes and features.
  - Add FAQ sections targeting common objections and use cases.
  - Apply Product, Offer, Review, and FAQ schema.

### 3.3 Location / store pages

- **Cluster definition**: URLs under `/locations/`, `/stores/`, or
  derived from location database.
- **Goals**:
  - Improve “near me” and city + service queries.
  - Provide consistent NAP (Name, Address, Phone) and opening hours.
  - Highlight services, insurance, or specialties by location.
- **Key pipeline elements**:
  - Ensure consistent location data and contact information.
  - Add localized copy and FAQs (parking, insurance, booking).
  - Apply LocalBusiness and related schema.

---

## 4. Rollout and QA patterns

### 4.1 Phased rollout

Always prefer **phased rollout** over all-at-once changes:
- **Pilot phase**: small sample of high-traffic or representative pages.
- **Expansion phase**: additional clusters or segments based on pilot
  results.
- **Full rollout**: broad application once patterns are stable.

### 4.2 QA checklists

For each cluster, define a simple QA checklist, for example:
- Content sections present and ordered correctly.
- Key fields populated (titles, intros, FAQs, CTAs).
- Schema validates and matches visible content.
- No critical regressions (links, tracking, forms).

---

## 5. Using these patterns with the skill

When using `geo-bulk-processor`:
- Reuse these patterns as **defaults** for inventory, clustering,
  pipeline design, and rollout.
- Reference them explicitly when explaining plans to the user’s team
  (“this follows the standard 4-phase pipeline with a phased rollout”).
- Adapt terminology and structures to match the user’s internal systems
  (field names, template IDs, existing workflows).

The goal is to turn large, messy content universes into **organized,
actionable GEO programs** that can be executed and iterated on over
time.



path: scripts/geo_bulk_pipeline.py
content: """
Helper models and utilities for the geo-bulk-processor skill.

This module is intentionally lightweight. It is designed as a reference
for how to model content items, clusters, and bulk GEO pipelines in a
structured way, so human teams and automation scripts can implement
the plans produced by the skill.

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.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional


@dataclass
class ContentItem:
    """
    Represents a single page or document in a GEO bulk corpus.
    """

    id: str
    url: Optional[str] = None
    path: Optional[str] = None
    content_type: Optional[str] = None  # e.g., "blog", "product", "location"
    language: Optional[str] = None
    cluster: Optional[str] = None
    metadata: Dict[str, Any] = field(default_factory=dict)


@dataclass
class PipelineStep:
    """
    A single logical step in a GEO bulk pipeline.

    Examples:
      - 'normalize_fields'
      - 'generate_faqs_with_geo_skill'
      - 'add_schema_with_geo_schema_gen'
      - 'export_to_cms_import_format'
    """

    name: str
    description: str
    inputs: List[str] = field(default_factory=list)
    outputs: List[str] = field(default_factory=list)
    external_skills: List[str] = field(default_factory=list)


@dataclass
class PipelineDefinition:
    """
    A reusable pipeline definition for one cluster or page type.
    """

    id: str
    cluster: str
    description: str
    steps: List[PipelineStep] = field(default_factory=list)


def summarize_inventory(items: List[ContentItem]) -> Dict[str, Any]:
    """
    Produce a high-level summary of a bulk corpus.

    This is a reference implementation that shows what kind of
    aggregated view is useful when designing bulk GEO strategies.
    """

    summary: Dict[str, Any] = {
        "total_items": len(items),
        "by_content_type": {},
        "by_language": {},
        "by_cluster": {},
    }

    for item in items:
        if item.content_type:
            summary["by_content_type"].setdefault(item.content_type, 0)
            summary["by_content_type"][item.content_type] += 1
        if item.language:
            summary["by_language"].setdefault(item.language, 0)
            summary["by_language"][item.language] += 1
        if item.cluster:
            summary["by_cluster"].setdefault(item.cluster, 0)
            summary["by_cluster"][item.cluster] += 1

    return summary


def example_pipeline_for_cluster(cluster_name: str) -> PipelineDefinition:
    """
    Return an illustrative pipeline definition for a given cluster name.

    This is not meant to be exhaustive or final. It simply demonstrates
    how to structure pipeline steps so that different tools and geo-*
    skills can be composed together in a repeatable way.
    """

    steps = [
        PipelineStep(
            name="ingest_and_normalize",
            description="Ingest records for this cluster and normalize fields into a common schema.",
            inputs=["raw_export"],
            outputs=["normalized_records"],
            external_skills=[],
        ),
        PipelineStep(
            name="content_enrichment",
            description="Enrich or rewrite content fields with GEO-focused templates and patterns.",
            inputs=["normalized_records"],
            outputs=["geo_enriched_records"],
            external_skills=["geo-content-optimizer"],
        ),
        PipelineStep(
            name="schema_generation",
            description="Attach or update structured data/schema markup for this cluster.",
            inputs=["geo_enriched_records"],
            outputs=["records_with_schema"],
            external_skills=["geo-schema-gen"],
        ),
        PipelineStep(
            name="export_for_implementation",
            description="Export final records into a format that can be imported into the CMS or delivery pipeline.",
            inputs=["records_with_schema"],
            outputs=["implementation_export"],
            external_skills=[],
        ),
    ]

    return PipelineDefinition(
        id=f"{cluster_name}-default-pipeline",
        cluster=cluster_name,
        description=(
            f"Default illustrative GEO bulk pipeline for the '{cluster_name}' cluster. "
            "Adapt steps, inputs, outputs, and external skills to the user’s actual systems."
        ),
        steps=steps,
    )


__all__ = [
    "ContentItem",
    "PipelineStep",
    "PipelineDefinition",
    "summarize_inventory",
    "example_pipeline_for_cluster",
]



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