# SEO · GEO · ASO — a free, all-in-one optimization skill for Claude

A single [Claude Agent Skill](https://code.claude.com/docs/en/skills) that helps you optimize
**websites, web pages, and mobile apps** across all three modern discovery channels:

- **SEO** — organic ranking in Google & Bing
- **GEO / AEO** — getting **cited and recommended by AI answer engines** (Google AI Overviews & AI Mode, ChatGPT, Perplexity, Gemini, Claude, Copilot)
- **ASO** — App Store Optimization for the Apple App Store & Google Play

Built on **2025–2026 best practices**, grounded in primary sources (Google Search Central,
web.dev, the Princeton/KDD'24 GEO study, Apple/Google developer docs). **100% free — it never
requires a paid tool or subscription.** Every task has a keyless, open-source path.

> Why this exists: most SEO/GEO/ASO tools are either paywalled, single-channel, or repeat
> outdated myths. This skill unifies all three channels under one workflow, runs on free tools
> only, and is honest about what actually works in 2026 (e.g. `llms.txt` is *not* a proven AI
> citation lever; blocking `GPTBot` does *not* remove you from ChatGPT Search).

---

## What it does

Give Claude a URL or an app, and it will:

1. **Scope** the goal (rankings? AI citations? installs? conversions?).
2. **Audit** with deterministic, pure-Python evidence collectors (no guessing).
3. **Diagnose** every issue with a `Finding → Evidence → Impact → Fix` rubric, tagged with
   **severity** and **confidence** (`Confirmed` / `Likely` / `Hypothesis`).
4. **Recommend / implement** fixes ranked by impact × effort, with copy-paste snippets.
5. **Verify** the fix landed and give a **SHIP / FIX / BLOCK** verdict.

### Example prompts

```
Audit https://example.com for SEO and tell me the most important things to fix.
I want my blog to show up when people ask ChatGPT and Perplexity about my topic.
Help me optimize the App Store and Google Play listing for my meditation app.
Is blocking GPTBot going to stop me appearing in ChatGPT search results?
Check whether AI search crawlers can reach https://mysite.com.
Generate structured data (JSON-LD) for my product page and validate it.
```

---

## Installation

### Claude Code (recommended)

Clone into your personal skills directory so it triggers in every project:

```bash
git clone https://github.com/artificialguybr/seo-geo-aso-agent-skill.git ~/.claude/skills/seo-geo-aso-agent-skill
```

Or per-project:

```bash
git clone https://github.com/artificialguybr/seo-geo-aso-agent-skill.git .claude/skills/seo-geo-aso-agent-skill
```

Claude Code auto-discovers it via `SKILL.md`. Ask any SEO/GEO/ASO question and it activates —
or invoke it explicitly with `/seo-geo-aso-agent-skill`.

### Other agents (Cursor, Windsurf, Codex, ChatGPT, etc.)

The skill is plain Markdown + Python. Point your agent at `SKILL.md` as a rule/context file, or
paste a reference file (`references/*.md`) into context. The scripts run standalone from any
shell (see below).

---

## The scripts (run standalone too)

Six evidence collectors in `scripts/`. **Pure Python standard library — no `pip install`
required.** All support `--json` for piping into other tools.

| Script | What it checks | Example |
|---|---|---|
| `seo_audit.py` | On-page + technical SEO: title, meta, H1, canonical, robots meta, schema presence, render/SPA risk, robots.txt, viewport, hreflang | `python3 scripts/seo_audit.py https://example.com` |
| `psi_audit.py` | Core Web Vitals (field + lab) via the free PageSpeed Insights API | `python3 scripts/psi_audit.py https://example.com --strategy mobile` |
| `ai_crawler_check.py` | Whether AI **search** bots (OAI-SearchBot, PerplexityBot, Claude-SearchBot…) can reach the site — the #1 GEO check | `python3 scripts/ai_crawler_check.py https://example.com --live` |
| `schema_check.py` | Extracts & validates JSON-LD structured data (free Rich-Results-Test replacement) | `python3 scripts/schema_check.py https://example.com` |
| `aso_keywords.py` | Free ASO keyword mining from store autocomplete + iTunes competitor scan | `python3 scripts/aso_keywords.py "meditation" --store apple --competitors` |
| `gen_llms_txt.py` | Generates a spec-compliant `llms.txt` from your sitemap | `python3 scripts/gen_llms_txt.py https://example.com/sitemap.xml --name "Brand"` |

**Optional upgrades (still free):** set `PSI_API_KEY` (free PageSpeed Insights key) to raise the
keyless quota; install `google-play-scraper` for true Play autocomplete; install `extruct` for
richer structured-data extraction (Microdata/RDFa). The scripts degrade gracefully without them.

---

## Repository layout

```
seo-geo-aso-agent-skill/
├── SKILL.md                 # entry point: router + workflow + rubric + principles
├── references/
│   ├── seo.md               # ranking systems, Core Web Vitals, technical/on-page/off-page, E-E-A-T
│   ├── geo.md               # AI-search: the GEO study, how engines cite, crawler control, measurement
│   ├── aso.md               # Apple + Google Play exact field limits, algorithms, CRO, localization
│   ├── free-tools.md        # every free/OSS tool with exact CLI/API invocation
│   └── schema-recipes.md    # copy-paste JSON-LD for high-value schema.org types
├── scripts/                 # six pure-stdlib, --json evidence collectors
├── assets/
│   ├── robots-ai.txt        # AI-crawler robots.txt template (allow search, block training)
│   └── aso-metadata-worksheet.md
└── evals/evals.json         # sample test prompts
```

The design follows **progressive disclosure**: a thin `SKILL.md` routes to fat reference files
that load only when needed.

---

## Principles

- **Free only.** No task ever requires a paid subscription; a free alternative is always named.
- **Evidence over vibes.** Claude runs a script before asserting a technical fact and tags its
  confidence honestly.
- **Honest about 2026 reality.** `llms.txt` is low-value for AI citation; `GPTBot` ≠
  `OAI-SearchBot`; FAQ/HowTo rich results are deprecated (keep the markup anyway); circulating
  stats are flagged `[directional]` unless from a named study.
- **No manipulation.** No cloaking, keyword-stuffing (it *reduces* AI visibility), fake reviews,
  PBNs, review-gating, or schema that doesn't match visible content.

---

## Contributing

Issues and PRs welcome — especially: updated store character limits, new AI crawler tokens,
changed API endpoints, and fresh 2026+ research with primary sources. Please keep the
free-only and evidence-tagged principles intact.

## License

[MIT](LICENSE) — free to use, modify, and distribute.

## Disclaimer

Search engines, AI answer engines, and app stores change their algorithms, fields, thresholds,
and rich-result support frequently and without notice. Treat the references as a well-sourced
snapshot, verify limits against current official docs before shipping, and never rely on a
single directional statistic. Not affiliated with Google, Apple, OpenAI, Anthropic, Perplexity,
or Microsoft.