Aeko visibility report

AEKO Visibility Report

Produces a structured AI visibility report for one domain. Output is designed to be pasted into a board / team update without further editing.

Marketer-facing output contract

Write for a marketing lead or founder. Lead with business meaning, not backend scopes: "Are we being mentioned?", "Are we being cited?", "What changed?", and "What should we do next?" Keep depth=summary to one page.

Language: mirror the user's chat language for user-facing steps, summaries, questions, and next actions. Keep slash commands, IDs, file paths, channel slugs, schema keys, and tool names in English/ASCII.

Inputs

• domain-id (optional) — UUID. Missing → aeko_list_domains pick-list.
• window (optional) — 7d (default), 14d, 30d, 90d.
• depth (optional) — summary (default) or full.

Step 1 — Resolve domain + prompt context

1. Parse $1 for UUID. If absent → aeko_list_domains → pick.
2. aeko_get_domain_info(domain_id) for base_url, brand/domain names, domain keywords, AI-readiness flags, and any prompt-tracking context metadata surfaced by the backend.
3. Use context only for prompt tracking/report segmentation and for content/PDP recommendations.

Step 2 — Pull visibility data

Call in parallel:

• aeko_get_visibility_summary(domain_id, scope="overview") — 30-day mention / citation / source counts + sentiment + recent brand mentions + monthly trend.
• aeko_get_visibility_summary(domain_id, scope="tracked_prompt_metrics", window=$2) — 7-day performance with WoW trends (the tool window arg only affects this scope in v0.5.0; use 7d default).
• aeko_get_visibility_summary(domain_id, scope="cited_sources") — pages from this domain AI engines cite.

Step 3 — Compose report — summary depth

Always include:

# AEKO Visibility Report — <brand_name>
**Window:** <window> · **Depth:** summary · **Generated:** <ISO date>

## Headline

AI visibility: <total_mentions> mentions · <total_citations> citations
Mentions: <total_mentions> (<WoW trend>)
Citations: <total_citations> (<WoW trend>)
Sentiment: <avg_sentiment_score>% positive (<WoW trend>)

## What moved this week

- <one-line observation per notable metric movement>
- <e.g. "Citations up 12% — driven by new Claude coverage on 차렵이불 queries">

## Top new citations (this window)

- <page_url> — cited <N>× by {platforms} · top prompt: "<prompt text>"
- ...

## What AI appears to use from our pages

- <page_url> — inferred from overlapping facts/snippets, not a measured metric: <plain-language summary>
- If there is not enough crawl/response overlap, say "not enough evidence yet" instead of guessing.

## Infrastructure snapshot

- AI search/shopping crawler access: <yes|no|partial>
- llms.txt curated index: <yes|no> (optional)
- JSON-LD coverage: <yes|no>
(If crawler access or JSON-LD is "no" or "partial" → append "run `/aeko-action-center <domain_id> technical`")

## Recommended next step

<one specific command — based on which metric moved most or which infra gap is open>

Step 4 — Full depth (only if $3 == "full")

Add the following sections after the summary:

## Per-tracked-prompt performance

| Prompt | Platform | Country | Mentions | Citations | Brand cited? |
|--------|----------|---------|----------|-----------|--------------|
| ...    | ...      | ...     | ...      | ...       | Yes / No     |

(Pull from the tracked_prompt_metrics scope's breakdown if it surfaces per-prompt data; include context columns when present. Else cite the summary data and note that per-prompt detail requires /aeko-prompt-deep-dive <prompt_id>.)

## Cited-source breakdown

<Your pages AI engines cited, grouped by page URL>

| Page | Citations | AI Engines | Top triggering prompt |
|------|-----------|------------|-----------------------|
| ...  | ...       | ...        | ...                   |

When a competitor's page outranks yours for a prompt, note why in the plugin's AEO vocabulary (BLUF / PREP / Informational Gain / E-E-A-T — see skills/aeko-create-content/references/aeo-frameworks.md): "the cited winner leads with the answer (BLUF) and shows lived detail (Informational Gain); your page is generic." This makes the report's findings map straight to what the executor skills fix — for a single prompt, hand off to /aeko-prompt-deep-dive <prompt_id>.

Where response and crawl snippets are available, add a clearly labeled "inferred absorption" note: "AI appears to reuse these facts from the page..." This is an interpretation from text overlap, not a platform-provided metric.

## Competitive signal (from mentions[] across responses)

<Top 5 brands mentioned alongside or instead of this one — from the
`brand_mentions` field in the overview payload. For each, note the sentiment
and how often they appear next to tracked prompts.>

## Recommended actions (ranked)

1. <most impactful next move — e.g. "Add FAQPage JSON-LD to the 3 top cited
   pages; run /aeko-action-center <domain_id> technical">
2. <second>
3. <third>

Step 5 — Save the report

Write the full markdown to: ./aeko-artifacts/<domain_id>/reports/visibility-<window>-<depth>-<YYYYMMDD>.md

Step 6 — User-facing summary

✔ Report saved: <path>
  Visibility: <total_mentions> mentions · <total_citations> citations
  Recommended next: <the first command from Step 4's ranked list>

Error paths

• aeko_get_visibility_summary 500 → note which data is missing in the report ("visibility summary unavailable — backend returned error; rerun in a moment"). Do NOT block the whole report on one failed scope.
• Zero domains → tell user to add one at the AEKO dashboard.
• Zero tracked prompts (tracked_prompt_metrics scope returns empty) → note in report: "No tracked prompts yet. Run /aeko-find-prompts-to-track to start collecting data."

What this skill never does

• Never writes to a store.
• Never fabricates a metric — if data is missing, say so plainly.
• Never exceeds one-page length at depth=summary. Keep it scannable.