Skill: geoly-geo/geo-ai-plugin-builder (version 0.1.0)

--- name: geo-ai-plugin-builder description: > Master orchestrator for turning high-value GEO content and capabilities into AI plugins/tools across ChatGPT, Claude, Perplexity, Gemini and other ecosystems. Use this skill whenever the user mentions building, designing, packaging, or standardizing AI plugins/tools around their content, APIs, or GEO assets, or wants to move from being passively cited to actively embedded inside AI workflows. --- # GEO AI Plugin Builder This skill helps you design and standardize AI plugins/tools that wrap your highest-value GEO content and capabilities, so they can be embedded directly into AI ecosystems (ChatGPT, Claude, Perplexity, Gemini, etc.). The core goal is to shift from **"waiting to be cited"** to **"being a first-class tool inside AI workflows"**, while staying aligned with GEO (Generative Engine Optimization) strategy. --- ## When to use this skill Use this skill whenever: - You want to **turn content, data, or services into AI plugins/tools**. - You want to **increase brand exposure inside AI tool flows**, not just in plain-text answers. - You are **mapping website/GEO assets to structured tool endpoints**. - You are **designing or refactoring an AI plugin catalog** for your brand. - You need **standard templates** for OpenAI-style tools, Claude Tools, function calling, or custom internal agents. - You want to **prioritize which content should become a plugin first**. Do **not** use this skill when the user only wants: - Simple content rewrites for GEO (use their GEO content skills instead). - Pure analytics/reporting about GEO performance (metrics-only work). - Low-level SDK usage without any GEO or plugin strategy involved. --- ## Mindset and principles - **Tool-first GEO**: Treat your top content and capabilities as *services* that can be invoked as tools, not just pages to be cited. - **User journey > endpoints**: Begin from real end-to-end tasks users want to完成 with AI, then design tools that make those workflows smooth. - **Cross-ecosystem thinking**: Design schemas and naming so your plugin concepts map cleanly across multiple AI platforms. - **Small, composable tools**: Prefer a set of focused tools that can be combined, rather than one mega-tool that does everything. - **Explainability for AIs**: Include clear descriptions, examples, and constraints so AI models can reliably choose and call tools. --- ## High-level workflow When the user asks for help, follow this 5-step workflow unless they explicitly request a narrower slice: 1. **Clarify goals and context** - Understand the brand, target users, and GEO priorities. - Identify which AI ecosystems matter most (e.g., ChatGPT plugins, Claude Tools, Perplexity collections, internal agents). - Clarify what "success" looks like: visibility, conversions, leads, authority, usage of specific tools, etc. 2. **Inventory candidate assets** - Ask for or infer a list of high-value assets: - Evergreen content, calculators, wizards, internal tools. - Datasets, pricing engines, recommendation logic. - Workflows sales or support teams execute repeatedly. - Group assets by use case and by stage in the customer journey (discovery, evaluation, decision, post-purchase, retention). 3. **Design plugin concepts and tool set** - Propose a **plugin catalog**: 3–10 core plugin ideas or tool groups. - For each plugin/tool, define: - Primary user jobs-to-be-done. - Input parameters and output structure. - GEO role (discovery, trust building, conversion, retention). - Prioritize plugins by potential impact and implementation effort. 4. **Generate detailed tool specifications** - For the **highest-priority plugin(s)**, generate detailed specs: - Tool name, description, and rationale. - JSON schema for inputs and outputs. - Example calls and example responses. - Mapping to backend endpoints or content sources. - GEO hooks (links, snippets, brand voice guidance). 5. **Produce implementation-ready artifacts** - Output one or more of: - **Technical blueprints** (OpenAI tools, Claude Tools, HTTP endpoints, or internal APIs). - **Developer handoff docs** with clear TODOs and edge cases. - **Backlog / roadmap** outlining order of implementation. Whenever possible, structure outputs so the user can copy-paste directly into their codebase or internal specs. --- ## Information to ask from the user When the initial information is incomplete, explicitly ask the user for: - **Business and brand** - Industry, main products or services. - Primary GEO/AI goals (visibility, conversions, retention, authority). - **Target AI ecosystems** - Which AI platforms and tool surfaces matter most. - Internal vs public tools (e.g., sales-assist, support-assist). - **Existing assets** - URLs for core content, tools, or APIs. - Any existing plugins, agents, or integrations. - **Constraints** - Technical stack and data sources. - Compliance/privacy constraints (PII, regulated data, etc.). - Resource constraints (team size, timelines). If the user cannot provide all details, make **reasonable assumptions**, but document them clearly in the output. --- ## Output formats Adapt to the user's request, but default to these structured formats: - **Plugin catalog overview** - A table or bullet list summarizing each proposed plugin/tool with: - Name - Primary user job - Main AI surfaces/platforms - GEO role - Implementation difficulty (rough) - Priority (high/medium/low) - **Detailed plugin specification** - For each selected plugin, provide: - High-level description and purpose. - User stories / example prompts that should call this tool. - Tool schema: - `name` - `description` - `parameters` JSON schema - `response` JSON schema - 2–4 **example calls and responses**. - GEO notes: - Key URLs/content to surface. - Brand and messaging constraints. - Tracking/telemetry suggestions. - **Implementation checklist / roadmap** - Ordered list of steps for developers: - API design / implementation. - Authentication / permissions. - Logging, analytics, and monitoring. - Security and compliance checks. - Include clear "Done when…" criteria. When the user wants code snippets (e.g., OpenAI, Node, Python), generate idiomatic examples but keep them as **implementation guidance**, not as the primary output of the skill. --- ## GEO-specific guidance When designing plugins and tools, always connect back to GEO strategy: - **Exposure inside AI tools** - Prefer tools that solve high-frequency, high-intent problems. - Make descriptions explicit about when they should be chosen by the model (e.g., "Use this tool whenever the user asks for…"). - **Authority and trust** - Tie outputs back to authoritative sources: - Official docs, research, internal datasets, or calculators. - Suggest how to surface citations or reference links when allowed. - **Conversion paths** - For tools near purchase or signup decisions, include: - Next-step suggestions ("book a demo", "see pricing"). - Structured fields that map to CRM or analytics events. - **Lifecycle coverage** - Encourage a mix of plugins across the customer lifecycle: - Discovery (educational, comparison, diagnostics). - Evaluation (calculators, configurators, ROI models). - Decision (quote builders, plan selectors). - Post-purchase (onboarding, troubleshooting, optimization). --- ## Using bundled scripts and references This skill may ship with helper scripts and reference guides under: - `scripts/` — reusable helpers to generate JSON schemas, boilerplate plugin specs, or check consistency across a plugin catalog. - `references/` — conceptual guides and best practices for GEO-aware plugin and tool design. When you need more detailed patterns or want to generate many similar tools at once, first: 1. Check `references/geo-ai-plugin-patterns.md` for archetypes and naming conventions. 2. Use `scripts/plugin_blueprint_generator.py` as a mental model for how to turn an abstract "job" into one or more tool specs. You do **not** need to literally run these scripts inside the model, but you should imitate their behavior and structures when helpful. --- ## Example use cases Here are a few example tasks where this skill should be used end-to-end: - "We run a B2B SaaS for marketing analytics. Help us design a set of AI tools so that ChatGPT or Claude can analyze a client's data and recommend campaigns using our platform." - "We have a library of in-depth medical articles and calculators. Turn them into a plugin catalog for AI assistants that doctors or patients might use, with clear safety and disclaimers." - "Our ecommerce brand has rich buying guides and fit finders. Design AI tools that help shoppers choose products and that we can expose as plugins in multiple AI platforms." --- ## Working style When using this skill: - Stay **strategic first, then technical**: - Clarify positioning, value, and GEO role before writing schemas. - Be **explicit about assumptions** and clearly flag trade-offs. - Optimize for **reuse and extendability**: - Make it easy to add more tools or platforms later. - Keep outputs **copy-paste friendly**: - Use consistent headings, JSON blocks, and formatting. If the user asks to iterate on a previous catalog or spec, treat the old version as a baseline, highlight key changes, and explain why the new design is stronger for GEO + AI plugin exposure.

path: evals/evals.json
content: {
  "skill_name": "geo-ai-plugin-builder",
  "evals": [
    {
      "id": 0,
      "prompt": "We operate a B2B SaaS platform for marketing analytics (attribution, ROAS dashboards, cohort analysis). Help us design an AI plugin catalog so that ChatGPT and Claude can use our data and workflows as tools. Prioritize tools that increase trial-to-paid conversion and upsell existing customers to higher tiers.",
      "expected_output": "A structured plugin catalog with 4-8 tools, each including name, purpose, target AI surfaces, GEO role, and priority, plus at least one detailed tool specification with JSON schemas for inputs and outputs.",
      "files": []
    },
    {
      "id": 1,
      "prompt": "We run an ecommerce brand selling running shoes and sports apparel. We already have sizing guides, product comparison pages, and a 'shoe finder' quiz on our website. Design a set of AI tools/plugins that help a shopper pick the right shoe and outfit when they ask a general AI assistant for recommendations, and connect each tool back to our existing GEO content.",
      "expected_output": "A plugin catalog covering discovery, evaluation, and purchase decision stages for ecommerce, with tools that map to existing sizing guides and quizzes. At least one tool should include example user prompts, JSON tool schema, and sample responses.",
      "files": []
    },
    {
      "id": 2,
      "prompt": "We maintain a large library of expert articles and calculators about personal finance (budgeting, retirement planning, tax optimization). We want to move from being occasionally cited by AI models to becoming a default 'finance tools' plugin set. Design an AI plugin blueprint that wraps our calculators and guides into a coherent tool suite for AI assistants.",
      "expected_output": "A high-level blueprint that groups tools by user journey (discovery, planning, decision, follow-up), plus 2-3 detailed tool specifications (name, description, input/output schema, example calls, GEO notes) aimed at personal finance use cases.",
      "files": []
    }
  ]
}



path: references/geo-ai-plugin-patterns.md
content: # GEO AI Plugin Patterns

This reference file describes common patterns for GEO-aware AI plugins
and tools. Use these patterns as starting points when designing a
plugin catalog with the `geo-ai-plugin-builder` skill.

The patterns below are platform-agnostic but map cleanly to:

- OpenAI tools / function calling
- Claude Tools
- Perplexity and Gemini tool-like integrations
- Internal AI agents in your own stack

---

## 1. Diagnostic / Assessment Tool

**Purpose:** Quickly assess a user's current situation and segment them
into a few actionable profiles or next steps.

**Typical GEO role:** Discovery and early-funnel qualification.

**Good for:**

- "Maturity" assessments (marketing, security, analytics).
- Health checks (site performance, SEO/GEO readiness).
- Fit checkers (ideal plan/product recommendation starting point).

**Key design tips:**

- Limit outputs to a small number of clear segments or scores.
- Always attach a recommended next action.
- Map segments to existing GEO content (guides, playbooks, case studies).

**Example output structure (simplified):**

```json
{
  "segment_id": "intermediate",
  "score": 67,
  "summary": "You have solid foundations but lack automation.",
  "recommended_next_steps": [
    {
      "label": "Implement automated campaign reporting",
      "url": "https://example.com/docs/auto-reporting"
    }
  ]
}
```

---

## 2. Calculator / Estimator Tool

**Purpose:** Turn business inputs into numerical outputs that support
decisions (ROI, pricing, savings, risk).

**Typical GEO role:** Evaluation and decision support.

**Good for:**

- ROI and payback period calculators.
- Cost comparison between plans or vendors.
- "What if" scenario analysis.

**Key design tips:**

- Require only a few high-leverage inputs.
- Make assumptions explicit in the description and output.
- Include fields for uncertainty or ranges when appropriate.
- Point to deeper content for methodology and disclaimers.

**Example input schema (simplified):**

```json
{
  "type": "object",
  "properties": {
    "monthly_spend": { "type": "number" },
    "expected_lift_percent": { "type": "number" },
    "time_horizon_months": { "type": "integer" }
  },
  "required": ["monthly_spend", "expected_lift_percent"],
  "additionalProperties": false
}
```

---

## 3. Recommendation / Matching Tool

**Purpose:** Recommend products, plans, or configurations based on user
preferences, constraints, or behavior.

**Typical GEO role:** Evaluation and conversion.

**Good for:**

- Product finders (ecommerce, SaaS plans, financial products).
- Content recommendation engines (next best article, video, guide).
- Partner or expert matching (consultants, agencies, clinics).

**Key design tips:**

- Normalize preferences into a small set of parameters.
- Return ranked options with reasons and trade-offs.
- Include stable IDs and URLs for tracking and deep links.

**Example response snippet:**

```json
{
  "recommendations": [
    {
      "id": "shoe_123",
      "name": "Marathon Pro Runner",
      "reason": "Best for neutral runners doing high weekly mileage.",
      "url": "https://example.com/products/shoe_123"
    }
  ]
}
```

---

## 4. Workflow Orchestrator Tool

**Purpose:** Guide a multi-step process where the AI assistant and the
user collaborate over several turns.

**Typical GEO role:** Deep engagement, onboarding, or configuration.

**Good for:**

- Onboarding flows (setting up an account or workspace).
- Implementation checklists (migrations, integrations).
- Configuration wizards (complex products or stacks).

**Key design tips:**

- Model each step explicitly and include a `next_step` field.
- Store partial state in a structured way (session or context object).
- Keep each tool call focused on one step or transition.

**Example stateful pattern (simplified):**

```json
{
  "step": "collect_requirements",
  "completed_steps": ["introduction"],
  "pending_questions": [
    "Which CRM do you use?",
    "How many monthly active users do you expect?"
  ]
}
```

---

## 5. Knowledge / Retrieval Tool

**Purpose:** Bring in authoritative, curated content from your corpus
rather than letting the model hallucinate or guess.

**Typical GEO role:** Authority building and accurate answers.

**Good for:**

- Answering detailed FAQs from your docs.
- Pulling in canonical definitions, limits, or policies.
- Linking back to long-form content that supports answers.

**Key design tips:**

- Return stable identifiers and URLs for each piece of content.
- Include short summaries plus "read more" links.
- Indicate content type (guide, API doc, case study, legal).

**Example response snippet:**

```json
{
  "results": [
    {
      "id": "doc_analytics_basics",
      "title": "Marketing Analytics Basics",
      "snippet": "An overview of attribution models and ROAS.",
      "url": "https://example.com/docs/analytics-basics"
    }
  ]
}
```

---

## Naming and description conventions

- Prefer **short, descriptive, action-oriented names**, e.g.:
  - `campaign_performance_analyzer`
  - `shoe_fit_recommender`
  - `roi_savings_calculator`
- In descriptions, explicitly tell the AI **when** to use the tool:
  - "Use this tool whenever the user asks to compare…"
  - "Call this tool when the user provides concrete numbers and wants…"

Clear, consistent naming and descriptions increase the chance that
AI models will choose the right tool at the right time and keep your
brand visible and authoritative inside AI ecosystems.



path: scripts/plugin_blueprint_generator.py
content: """
plugin_blueprint_generator.py

This helper module defines a simple, opinionated structure for
GEO-aware AI plugin/tool blueprints. It is not meant to be a
full framework, but rather a concrete reference for how to
organize information when designing tools programmatically.

You do not have to run this script directly; you can mirror
its data structures inside your own codebase or internal specs.
"""

from __future__ import annotations

from dataclasses import dataclass, asdict
from typing import List, Dict, Any, Optional


@dataclass
class ToolSchema:
    name: str
    description: str
    parameters: Dict[str, Any]
    response: Dict[str, Any]


@dataclass
class PluginBlueprint:
    plugin_name: str
    geo_role: str
    primary_job: str
    target_platforms: List[str]
    priority: str
    tools: List[ToolSchema]
    notes: Optional[str] = None

    def to_dict(self) -> Dict[str, Any]:
        """Return a JSON-serializable representation of the blueprint."""
        data = asdict(self)
        return data


def generate_plugin_blueprint(
    plugin_name: str,
    primary_job: str,
    geo_role: str,
    target_platforms: Optional[List[str]] = None,
    priority: str = "high",
    notes: Optional[str] = None,
) -> PluginBlueprint:
    """
    Create a minimal PluginBlueprint with a single empty ToolSchema stub.

    You can then fill in the ToolSchema fields manually. This function
    exists primarily as an example for how to structure plugin metadata.
    """
    if target_platforms is None:
        target_platforms = ["ChatGPT", "Claude", "Perplexity", "Gemini"]

    tool_stub = ToolSchema(
        name=f"{plugin_name}_core_tool",
        description=f"Core tool for: {primary_job}",
        parameters={
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": False,
        },
        response={
            "type": "object",
            "properties": {},
            "required": [],
            "additionalProperties": False,
        },
    )

    blueprint = PluginBlueprint(
        plugin_name=plugin_name,
        geo_role=geo_role,
        primary_job=primary_job,
        target_platforms=target_platforms,
        priority=priority,
        tools=[tool_stub],
        notes=notes,
    )
    return blueprint


def example_blueprint() -> Dict[str, Any]:
    """
    Return an example blueprint for documentation or quick experiments.
    """
    bp = generate_plugin_blueprint(
        plugin_name="marketing_analytics_insights",
        primary_job="Help users analyze campaign performance and suggest optimizations.",
        geo_role="evaluation_and_optimization",
        target_platforms=["ChatGPT", "Claude"],
        priority="high",
        notes=(
            "Designed as a high-intent tool for existing customers and "
            "qualified leads who want deep insight into campaign ROI."
        ),
    )
    return bp.to_dict()


if __name__ == "__main__":
    import json

    example = example_blueprint()
    print(json.dumps(example, indent=2))

"""
plugin_blueprint_generator.py

This helper module defines data structures and utilities that act as a
mental model for turning high-level "jobs to be done" into concrete AI
plugin/tool specifications.

The GEO AI Plugin Builder skill does not need to literally execute this
code. Instead, treat the structures and examples here as a reference for
how to shape outputs: small, composable, and implementation-ready.
"""

from dataclasses import dataclass, asdict
from typing import List, Dict, Any


@dataclass
class ToolParameter:
    name: str
    type: str
    description: str
    required: bool = True


@dataclass
class ToolSchema:
    name: str
    description: str
    parameters: List[ToolParameter]
    response_fields: List[ToolParameter]

    def to_openai_json(self) -> Dict[str, Any]:
        """Return an OpenAI-style JSON schema for this tool."""
        return {
            "name": self.name,
            "description": self.description,
            "parameters": {
                "type": "object",
                "properties": {
                    p.name: {
                        "type": p.type,
                        "description": p.description,
                    }
                    for p in self.parameters
                },
                "required": [p.name for p in self.parameters if p.required],
            },
        }

    def response_example(self) -> Dict[str, Any]:
        """
        Produce a stub example of the response shape.

        This is intentionally generic; callers should customize values and
        add domain-specific examples when using it inside the skill.
        """
        example: Dict[str, Any] = {}
        for field in self.response_fields:
            # Provide very lightweight defaults based on type.
            if field.type == "string":
                example[field.name] = f"<{field.name} string>"
            elif field.type == "number":
                example[field.name] = 0
            elif field.type == "boolean":
                example[field.name] = False
            elif field.type == "array":
                example[field.name] = []
            else:
                example[field.name] = None
        return example


@dataclass
class PluginBlueprint:
    """
    High-level blueprint for an AI plugin or tool group.
    """

    name: str
    primary_job: str
    geo_role: str
    target_platforms: List[str]
    tools: List[ToolSchema]

    def summary(self) -> Dict[str, Any]:
        """
        Return a compact summary suitable for catalogs or overview tables.
        """
        return {
            "name": self.name,
            "primary_job": self.primary_job,
            "geo_role": self.geo_role,
            "target_platforms": self.target_platforms,
            "tool_names": [tool.name for tool in self.tools],
        }

    def to_dict(self) -> Dict[str, Any]:
        """
        Serialize the entire blueprint into primitive Python types.
        """
        return {
            "name": self.name,
            "primary_job": self.primary_job,
            "geo_role": self.geo_role,
            "target_platforms": self.target_platforms,
            "tools": [
                {
                    "name": t.name,
                    "description": t.description,
                    "parameters": [asdict(p) for p in t.parameters],
                    "response_fields": [asdict(p) for p in t.response_fields],
                }
                for t in self.tools
            ],
        }


def example_blueprint() -> PluginBlueprint:
    """
    Return a minimal example blueprint for documentation and testing.
    """
    parameters = [
        ToolParameter(
            name="website_url",
            type="string",
            description="Public URL of the landing page to analyze.",
        ),
        ToolParameter(
            name="target_audience",
            type="string",
            description="Short description of the intended audience segment.",
        ),
    ]

    response_fields = [
        ToolParameter(
            name="summary",
            type="string",
            description="Concise summary of the page content.",
        ),
        ToolParameter(
            name="geo_opportunities",
            type="array",
            description="List of GEO opportunities identified on the page.",
        ),
    ]

    analysis_tool = ToolSchema(
        name="analyze_landing_page_for_geo",
        description=(
            "Analyze a landing page and suggest GEO-optimized messaging, "
            "FAQs, and potential AI tools that could be built from it."
        ),
        parameters=parameters,
        response_fields=response_fields,
    )

    return PluginBlueprint(
        name="geo_landing_page_analyzer",
        primary_job="Turn key landing pages into GEO-aware AI analysis tools.",
        geo_role="Discovery and optimization of high-intent pages.",
        target_platforms=["ChatGPT", "Claude", "Internal Agents"],
        tools=[analysis_tool],
    )


__all__ = [
    "ToolParameter",
    "ToolSchema",
    "PluginBlueprint",
    "example_blueprint",
]



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