ai-visibility

Files (21)

• .gitattributes
• .gitignore
• EXAMPLES.md
• LICENSE
• README.md
• SKILL.md
• brand.example.json · assets/
• prompts.example.json · assets/
• schema.example.json · assets/
• content-rubric.md · references/
• diagnosis.md · references/
• playbook.md · references/
• prompt-research.md · references/
• technical-fixes.md · references/
• workspace.md · references/
• aeo.py · scripts/
• aeo_selftest.py · scripts/
• aeolib.py · scripts/
• aeoreport.py · scripts/
• aeoweb.py · scripts/
• package.py · scripts/

SKILL.md (first lines)

# AI visibility

## What this is for

Search used to rank pages; assistants recommend brands. When someone asks
ChatGPT "which is the best X for Y", they get three to five names and pick from
that list. There is no second page. If the brand is not in the list, it does not
exist for that buyer.

Three facts shape everything below:

- **Answers vary by model.** Overlap between the domains ChatGPT and Perplexity
  cite is roughly 11%. Checking one assistant tells you almost nothing.
- **The description matters as much as the mention.** When a model names a
  brand, it also characterises it in one sentence the brand did not write. That
  sentence is the positioning buyers act on.
- **Most of the signal is off-site.** Around 85% of brand mentions in AI answers
  trace back to third-party sources, not the brand's own pages. Rewriting the
  homepage alone rarely moves the number.

This skill measures the current state, then produces a ranked list of fixes.
It runs locally on plain files — no account, no database, no API key required.

## Workflow

Work through these in order. Steps 1-5 are the measurement; 6-8 are the fix.
Announce which step you are on so the user can follow along.

Everything lives in a **workspace directory** — create it inside the user's
project (or wherever they ask), never in a temp folder they will lose.

All scripts are `python3` with the standard library only. Invoke them as
`python <skill>/scripts/aeo.py -w <workspace> <command>`.

### 1. Set up the brand

```bash
python scripts/aeo.py -w ./ai-visibility init example.com --name "Example"
```

Then interview the user and fill in `brand.json`. Getting this right decides
whether the whole audit is accurate:

| Field | Why it matters |
|---|---|
| `domain` | The strongest mention signal. Bare domain, no `www`, no protocol. |
| `aliases` | Other names the brand goes by, including in other alphabets. A brand called in Cyrillic will be missed without this. |
| `keywords` | Distinctive product or service names that identify the brand even when its name is absent. |
| `competitors` | Named rivals. Unknown competitors are discovered automatically; listing the known ones makes share-of-voice comparable across runs. |
| `positioning` | One sentence: what it does, for whom, what makes it different. Used later to judge whether the model's description is right. |

If the user does not know their competitors, run step 4 first with a handful of
prompts — the answers will name them.

### 2. Build the prompt set

This is the step most people get wrong, and it determines whether the audit is
useful. Read `references/prompt-research.md` before writing prompts.

The short version: buyers write ~23 words describing their situation, not 3
keywords. Brand-name prompts are easy and nearly worthless. What you want are
the unbranded, situation-specific questions asked right before a decision.

Generate 15-25 prompts with the user, in **their buyers' language** (not
necessarily English), each tagged with `category` and `intent`. Write them to
`prompts.json`. Intent drives prioritisation later, so classify honestly:
`high` = close to buying, `low` = browsing.

### 3. Collect answers

Three routes; pick based on what the user has. **B is the most trustworthy**
because it captures what real assistants actually serve today.

**A — you answer them (no setup).** Create the files, then answer each prompt
yourself using web search, writing the answer into the file below the `====`
line.

```bash
python scripts/aeo.py -w ./ai-visibility run --models claude
```

Answer each prompt as you would for any user asking it cold: search, then give
your honest recommendation. Do this *before* reading `brand.json`, and do not
let the tracked brand influence the answer — otherwise the measurement is
worthless. Label this run `claude` and tell the user plainly that it is one
model's view, produced by the same assistant running the audit.

**B — the user pastes real answers (recommended).**

```bash
python scripts/aeo.py -w ./ai-visibility run --models chatgpt gemini perplexity claude
```

This creates one file per prompt × model. The user opens each assistant, asks
the prompt, and pastes the full answer under the `====` line, replacing
`(no response)`. Tell them to paste everything including links — citations are
data. Leaving a file untouched is fine; unfilled answers are excluded from the
percentages rather than counted as misses.

**C — automated via OpenRouter.** One API key covers every model.

```bash
export OPENROUTER_API_KEY=sk-or-...
python scripts/aeo.py -w ./ai-visibility collect --models chatgpt gemini perplexity
```

Roughly $0.02-0.10 per prompt × model with the default lightweight models. Warn
the user before spending their money, and quote the count: 20 prompts × 3
models = 60 calls.

### 4. Analyze and report

```bash
python scripts/aeo.py -w ./ai-visibility analyze
python scripts/aeo.py -w ./ai-visibility report
```

This scores every answer — mentioned or not, the sentence describing the brand,
position in any ranked list, sentiment, competitors, cited URLs — and writes

From sgpopov/ai-kit, MIT.

More from sgpopov/ai-kit