---
name: geo-optimizer
description: Submit GEO (Generative Engine Optimization) analysis tasks to the GEO-Optimizer platform, poll for results, and download optimization reports. Use this skill when users want to analyze a website's AI search engine visibility, get GEO scores across 11 AI engines, generate optimization plans, or download multi-platform content packages.
version: 1.0.0
author: GEO-Optimizer Team
license: MIT
tags:
  - GEO
  - AI search optimization
  - website analysis
  - SEO
  - generative engine optimization
---

# GEO-Optimizer Skill

Analyze websites for AI search engine (GEO) readiness via the GEO-Optimizer platform API. Covers 11 AI engines: Doubao, Qwen, Hunyuan, Zhipu, DeepSeek, Google AI, ChatGPT Search, Perplexity, Claude, Copilot, Gemini.

## Prerequisites

- Python 3.10+
- `httpx` package (`pip install httpx`)
- A running GEO-Optimizer platform instance
- A valid API key (starts with `geo_`)

## Quick Start

```python
import sys
sys.path.insert(0, "<path-to-geo-skill-dir>")
from geo_skill_client import GeoSkillClient

client = GeoSkillClient(
    base_url="http://localhost:5001",
    api_key="geo_your_api_key_here"
)

# Submit a full analysis task (evaluation + optimization plan)
task_id = client.submit("https://example.com", task_type="plan")
print(f"Task submitted: {task_id}")

# Wait for completion and get results
result = client.wait_and_get_result(task_id, timeout=600)
print(f"GEO Score: {result['overall_score']}/100")

# Download the full report package
client.download(task_id, "./output/report.zip")
```

## Workflow

This skill operates in a 4-step workflow:

### Step 1: Submit Task

```python
task_id = client.submit(target_url, task_type="plan")
```

**Parameters:**
- `target_url` (required): The website URL to analyze
- `task_type`: `"eval"` (score only) or `"plan"` (score + optimization plan + multi-platform content)

**Returns:** `task_id` string

### Step 2: Monitor Progress

```python
status = client.get_status(task_id)
# status: {"status": "running", "progress": 45, "message": "..."}
```

**Status values:** `queued` → `running` → `completed` / `failed` / `cancelled`

### Step 3: Get Results

```python
result = client.get_result(task_id)
# result: {"overall_score": 72, "result": {...}, "download_url": "..."}
```

**Result structure:**
- `overall_score`: 0-100 composite GEO score
- `result.domestic_score`: Domestic 5-dimension score
- `result.international_score`: International 6-dimension score
- `result.dimensions`: Per-dimension breakdown
- `result.engines`: Per-engine evaluation details
- `download_url`: ZIP package download path (plan tasks only)

### Step 4: Download Report

```python
path = client.download(task_id, "./output/geo_report.zip")
```

**ZIP contents (plan task):**
- `geo_analysis_report.md` — Full analysis report
- `schema.jsonld.html` — Schema.org structured data
- `wechat_*.md` — WeChat article
- `zhihu_*.md` — Zhihu article
- `toutiao_*.md` — Toutiao article
- `medium_*.md` — Medium article
- `quora_*.md` — Quora answer
- `reddit_*.md` — Reddit post
- `plan_items/` — Prioritized action items

## CLI Usage

```bash
# Full analysis with download
python geo_skill_client.py \
  --base-url http://localhost:5001 \
  --api-key geo_your_key \
  --url https://example.com \
  --type plan \
  --output ./report.zip

# Score-only evaluation
python geo_skill_client.py \
  --base-url http://localhost:5001 \
  --api-key geo_your_key \
  --url https://example.com \
  --type eval
```

## API Reference

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/tasks` | Submit analysis task |
| GET | `/api/v1/tasks/{id}` | Query task status |
| GET | `/api/v1/tasks/{id}/result` | Get task result |
| GET | `/api/v1/tasks/{id}/download` | Download ZIP report |
| POST | `/api/v1/tasks/{id}/cancel` | Cancel task |
| GET | `/api/v1/usage` | API usage statistics |

**Authentication:** All endpoints require `Authorization: Bearer geo_<key>` header.

## Error Handling

```python
from geo_skill_client import GeoSkillError

try:
    task_id = client.submit(url, task_type="plan")
    result = client.wait_and_get_result(task_id, timeout=300)
except GeoSkillError as e:
    print(f"API Error [{e.status_code}]: {e.error} - {e.message}")
except TimeoutError as e:
    print(f"Task timed out: {e}")
```

**Common errors:**
- `401 invalid_token` — API key expired or incorrect
- `403 quota_exceeded` — Evaluation quota exhausted
- `429 concurrent_limit` — Too many concurrent tasks
- `404 not_found` — Task ID does not exist

## Scoring Dimensions

**Domestic (5D):** Content Quality, Structured Data, Citation Friendliness, AI Crawler Compatibility, User Experience

**International (6D):** Content Quality, Structured Data, Citation Friendliness, AI Crawler Compatibility, User Experience, E-E-A-T Signals

## Notes

- Task execution typically takes 30-120 seconds depending on target site complexity
- `plan` tasks generate LLM-powered content using configured AI models
- Maximum concurrent tasks per user: 3
- Global concurrent limit: configurable by platform admin
- Queued tasks automatically start when slots become available