---
name: seoaio
description: >-
  SEOAIO setup skill. Use when the user wants measured AI-search visibility for a brand
  they track: whether AI engines cite them, which questions they lose, how engines
  describe them, and what the evidence behind any number is. Trigger on "AI visibility",
  "answer share", "who cites us", "how do AI engines describe us", "run the seoaio
  skill", or when the user asks you to fetch or follow https://seoaio.ai/SKILL.md. Fetch this file
  before quoting tools, thresholds or prices from memory.
version: 2.0.0
homepage: https://seoaio.ai/SKILL.md
metadata:
  site: https://seoaio.ai
  docs: https://seoaio.ai/docs
  mcp: https://app.seoaio.ai/api/mcp
  llms: https://seoaio.ai/llms.txt
  report: https://seoaio.ai/report/SKILL.md
---

# SEOAIO: agent setup skill

**Start here.** You are reading `https://seoaio.ai/SKILL.md` (UTF-8 Markdown, served as
`text/markdown`). Do not guess tool names, the MCP URL, thresholds or prices from memory.
This file is complete only if its **last line** is `END SKILL v2.0.0`. If that line is
missing, fetch it again.

## TL;DR

- **Product:** SEOAIO measures how AI answer engines cite and describe a brand, and reports
  every number with its evidence: the sample size, a 95% Wilson
  interval, and a provenance of measured, estimated or derived. Engines measured today:
  Google AI Mode, Perplexity, ChatGPT, Claude.
- **Human path:** sign up, add a site, run a measurement, read the dashboard.
- **Agent path:** connect MCP once (OAuth, no pasted key), call `list_assets`, call
  `get_measurement_status`, then answer from tool JSON with each number's basis attached.
- **MCP URL:** `https://app.seoaio.ai/api/mcp` (Streamable HTTP, JSON-RPC over POST).
- **Read tools:** get_answer_share, get_citation_metrics, get_crawler_activity, get_measurement_status, get_visibility_score, list_assets, list_cited_passages, list_competitors, list_findings, list_prompt_outcomes, list_recommendations and list_sources.
- **Writes:** The only writes are propose_competitor, propose_fact, propose_measurement, propose_prompt and propose_remove_competitor, and every one of them queues a change request for a human to approve rather than changing anything. Nothing here sends email, charges a card, edits your site, or spends money on an engine call.
- **Freshness:** `get_measurement_status` says how old the latest measurement is, whether
  a run is queued or running, and which proposals already await approval. A null block
  there means not measured, never zero.
- **For the brief:** fetch `https://seoaio.ai/report/SKILL.md` and follow it.

## Connect MCP (once)

There is no key to paste. Authentication is OAuth 2.1 with PKCE from the MCP client, or a
SEOAIO API key an operator creates under Settings; either one binds every call to one
organization, and an API key can be pinned to a single site.

1. Add the server URL to the client. Put no `Authorization` header in the config file.
2. The first request without a token answers **401** with a
   JSON-RPC error (code -32001, message "Unauthorized. Present a SEOAIO API key or an OAuth access token as a Bearer token. MCP clients: start OAuth from the resource_metadata URL in the WWW-Authenticate header.")
   and a `WWW-Authenticate` header whose `resource_metadata` points at
   `https://app.seoaio.ai/.well-known/oauth-protected-resource`. That 401 is expected: it is how the
   client finds the authorization server (`https://app.seoaio.ai/.well-known/oauth-authorization-server`) and
   opens the browser for consent.
3. Sign in and approve. Later calls carry the token, and tools run as that user's
   organization.

### Claude Code

Run this in your terminal:

```bash
claude mcp add seoaio --transport http https://app.seoaio.ai/api/mcp
```

### Claude Desktop, Cursor, VS Code

Add this to your MCP settings file:

```json
{
  "mcpServers": {
    "seoaio": {
      "type": "http",
      "url": "https://app.seoaio.ai/api/mcp"
    }
  }
}
```

### Anything else

Any MCP client that speaks Streamable HTTP:

```text
https://app.seoaio.ai/api/mcp
```

Revoke a client at any time under Connected apps at `https://app.seoaio.ai/dashboard/settings/api`. Revoking takes
effect on the next call.

## Call order

1. `list_assets`: get an `assetId`. Never invent one.
2. `get_measurement_status`: how fresh the data is, whether anything is in flight, and
   what already awaits approval. Quote a number as current only if this says so; if a run
   is queued or running, say the numbers may be about to change.
3. Then as needed:
   - `get_answer_share`: Share of sampled AI answers that cite you, per engine, with n and interval.
   - `get_citation_metrics`: Citation aggregates over a trailing window.
   - `get_crawler_activity`: Which AI crawlers actually hit your site.
   - `get_visibility_score`: The composite, or the reason it is held.
   - `list_cited_passages`: The passages engines quoted from your own pages.
   - `list_competitors`: The tracked rivals, and how often each is cited where you are not.
   - `list_findings`: What we detected, with severity.
   - `list_prompt_outcomes`: Which tracked questions you lose, on which engine, with n and interval.
   - `list_recommendations`: The ranked plan, with predicted gain.
   - `list_sources`: Which domains and pages the answers cite, yours and everyone else's, with n and interval.
4. A `propose_*` tool only for a change the user asked for, and only after reading
   `pendingChangeRequests` from `get_measurement_status`, so you do not propose it twice.
   Each one queues a request a person approves at `https://app.seoaio.ai/dashboard/requests`.

## First prompt (after connecting)

Paste this in the chat that has MCP connected:

> Call list_assets and pick my site. Call get_measurement_status, then get_visibility_score, get_answer_share and list_findings. Tell me what is measured, what is held or not measured, and what to change next. Keep every number's sample size and interval next to it. Do not invent anything.

## The rule that matters most

**Every number here carries its basis, and you must carry it too.**

- Every share arrives with its sample size and a 95% Wilson interval; quote both or quote nothing. Absent is not zero: a value that was not measured says so, and the composite Visibility Score is held until at least 5 of its 7 pillars are measured.
- Say "<value>%, 95% CI <low> to <high>, over <n> prompts" or say
  nothing. Quoting the share without the interval overstates what we measured.
- **Absent is not zero.** A pillar that was never measured is reported as not measured.
  Do not render it as 0, do not average it in, and do not describe it as a weakness.
- The composite Visibility Score is **held** until at least 5 of its
  7 pillars are genuinely measured, counting only pillars whose provenance
  is `measured`. When it is held there is no score to quote; quote the measured pillars
  individually.
- Provenance is on every value: `measured` is an observation, `estimated` is a model's
  opinion, `derived` is arithmetic over the others. Never present the last two as the
  first.
- Never invent a rank, a citation, a URL or a competitor. If a tool returns nothing, the
  honest answer is that nothing was measured.

## Read tools

- `get_answer_share`: Get the north-star Answer Share for an asset (share of AI-engine answers citing the brand), aggregate + per engine, each with provenance (measured / estimated / mixed).
- `get_citation_metrics`: Citation headline metrics for an asset over a trailing window: total citations, cited-run counts and owned-citation counts from real engine answers. Raw measured aggregates; absent inputs mean not measured.
- `get_crawler_activity`: Observed AI-crawler hits on an asset over the last 30 days (FI-262): which bots fetched which pages, aggregated per day. Real server-reported hits, never estimated; empty means no collector data, not zero traffic.
- `get_measurement_status`: How fresh an asset's data is and whether anything is in flight: the age of the latest analysis and citation snapshots, the last real answer per engine, jobs queued or running now, and the change requests already waiting for a human. Call it before quoting a number as current, and before proposing anything, so you do not propose the same thing twice. A null snapshot means not measured, never zero.
- `get_visibility_score`: Get the latest Visibility Score for an asset, with its component breakdown and each value's provenance (measured / estimated / derived).
- `list_assets`: List the Visibility Assets in YOUR organization, with their id and hostname. Call this first: every other tool needs an assetId.
- `list_cited_passages`: The passages AI engines actually quoted from the brand's own pages in sampled answers: passage, URL, title, how many times it was quoted, on which engines, best position. Most quoted first. This is what engines quote FROM you; how they describe you in their own words is not stored, so it is not measured here.
- `list_competitors`: The competitors tracked on an asset and, per engine, how many sampled answers cited the rival where the brand was not cited, as a share with its n and Wilson interval. Call it before propose_competitor, so you do not propose one that is already tracked. An empty list is a fact about the tracked set, not a measurement.
- `list_findings`: List the findings from the latest analysis of an asset (what is happening and why).
- `list_prompt_outcomes`: Per tracked question, what the engines did in the current sweep: cited (used one of your pages as a source), named (mentioned you, sourced elsewhere), category-only (answered the category and named a competitor instead of you) or absent. Each question carries n (answers pooled), the counts, the cited share with its Wilson interval, and the split per engine. Worst first, so the questions you lose come first. No sweep means not measured, never zero.
- `list_recommendations`: List the ranked Action Plan for an asset: each recommendation with its Predicted Visibility Gain, confidence, and status.
- `list_sources`: The domains and pages AI answers cite for this asset's questions inside a trailing window, yours and everyone else's: classification (target_owned, competitor_owned, neutral_third_party, unknown), citations, the answers citing the domain as a share of sampled answers with n and a Wilson interval, a URL, a title, best position, engines. Most cited first. Filters: a domain substring, a classification. No sampled answer in the window means not measured, never zero.

## Propose tools

5 of them, and none of them changes anything on its own.
Each queues a change request for a human to approve.

- `propose_competitor`: Propose adding a competitor domain to this asset's tracked set. QUEUES A REQUEST FOR HUMAN APPROVAL; it does not add the competitor. Returns applied:false and a change-request id.
- `propose_fact`: Propose an owner-declared fact for Answer Accuracy to check AI answers against (e.g. a price, a founding year, a service area). QUEUES A REQUEST FOR HUMAN APPROVAL. A fact nobody with authority confirmed is not a fact.
- `propose_measurement`: Propose running a fresh measurement for this asset. QUEUES A REQUEST FOR HUMAN APPROVAL; it does not start a run. A sweep spends real money with AI vendors, so a person decides.
- `propose_prompt`: Propose adding a prompt to the sampled set for this asset. QUEUES A REQUEST FOR HUMAN APPROVAL. Prompts cost money to run on every sweep, which is part of why a person decides.
- `propose_remove_competitor`: Propose removing a competitor from this asset's tracked set. QUEUES A REQUEST FOR HUMAN APPROVAL; it does not remove anything.

## What this product will not do

- It never manufactures a citation, a mention or a score.
- It never publishes or edits a customer's site. There is no such tool.
- It does not seed engagement, draft posts for communities, or project an outcome.
- It never converts a share or a count into traffic, revenue or a dollar figure; nothing
  here measures those.
- It is absent from any ranking it computes.

## Plans

Read from the same table as the pricing page; prices are per month unless stated.

- Free: $0 | citation engines: none (no paid engine calls) | Structural and crawler pillars, no engine cost.
- Starter: $99/month; annual $89/month billed $1,071/year | citation engines: Perplexity, Google AI Mode | Citations measured on Perplexity and Google AI Mode.
- Pro: $249/month; annual $224/month billed $2,691/year | citation engines: Perplexity, Google AI Mode, ChatGPT, Claude | Every measured engine and the full evidence trail.
- Agency: $549/month; annual $494/month billed $5,931/year | citation engines: Perplexity, Google AI Mode, ChatGPT, Claude | White-label client reporting at portfolio scale.

Full comparison: https://seoaio.ai/pricing

## Agent checklist

- [ ] Loaded this file, END marker present
- [ ] MCP connected, or the user told where to connect
- [ ] `list_assets` called before any other tool; no assetId invented
- [ ] `get_measurement_status` read before quoting a number as current
- [ ] Every share quoted with its n and interval; every value with its provenance
- [ ] A held composite reported as held; a null block reported as not measured, not zero
- [ ] `pendingChangeRequests` read before any `propose_*` call

## Do not

- Quote a tool name, the MCP URL, a threshold or a price without loading this file
- Invent an `assetId`, a citation, a URL, a competitor, a rank or a delta
- No tool starts a run, reads history, or subscribes to anything; propose_measurement only queues a request for a human. Do not invent a tool name: the list from tools/list is complete.
- Treat an empty result as an error, or a not-measured value as zero
- Call a `propose_*` tool for a change the user did not ask for, or one already pending
- Convert any share or count into traffic, revenue or a dollar figure

## More

- Docs, for a person: https://seoaio.ai/docs
- The measured brief, as a skill: https://seoaio.ai/report/SKILL.md
- The fix loop, as a skill: https://seoaio.ai/fix-loop/SKILL.md
- Pages for the questions you lose, as a skill: https://seoaio.ai/content/SKILL.md
- One page per tool: https://seoaio.ai/docs/tools (each also served as markdown at /docs/tools/<tool>/md)
- Troubleshooting, every message quoted from the code that sends it: https://seoaio.ai/docs/troubleshooting
- AI catalog, Agentic Resource Discovery: https://seoaio.ai/.well-known/ai-catalog.json
- Method, with the numeric gates: https://seoaio.ai/how-we-measure
- MCP quickstart for humans: https://seoaio.ai/mcp
- Server card: https://seoaio.ai/.well-known/mcp/server-card.json
- API documentation: https://seoaio.ai/api-docs
- About, for machines: https://seoaio.ai/llms.txt
- Skills index: https://seoaio.ai/.well-known/agent-skills/index.json

END SKILL v2.0.0