aeo-optimize

AEO Optimize

Source: github.com/psyduckler/aeo-skills Part of: AEO Skills Suite (v2 Core) Reads: aeo-data/*.json (evidence) + optional aeo-reports/*.md Writes: A Markdown work queue (printed to chat or saved to file)

The action layer of the AEO loop. aeo-baseline measures, aeo-report analyzes, aeo-optimize recommends.

How this skill works

This is a SKILL.md-only skill — there is no script to run. The agent reads the methodology in this file plus the references in references/, then applies that methodology to the user's actual data.

The agent should:

1. Locate the latest evidence file. Sort aeo-data/*.json by run timestamp and load the latest.
2. Optionally read the latest aeo-report output at aeo-reports/*.md for pre-computed trend signals.
3. Optionally fetch one or more brand URLs when a recommendation involves a specific page (use web_fetch).
4. Apply the playbooks in references/action-playbooks.md to map gaps in the data to concrete actions.
5. Output a prioritized Markdown work queue with the structure shown below.

Output format

# AEO Action Plan — <brand>

Generated from `aeo-data/<latest-evidence-file>` covering prompts: <list>.

## Quick wins (high impact, low effort)

### 1. Refresh `<url>` with entity "<entity>"
**Evidence:** Mentioned in 14/20 Gemini responses for prompt `<prompt_id>` but missing from your page (`citation_rate = 60%, position avg #4.2`).
**Action:** Add a section that names "<entity>" and explains how it relates to <topic>. Aim for 2–3 sentences of natural mention.
**Effort:** ~30 min
**Expected gain:** Citation rate from 60% → 75–80% based on the recurring retrieval set.

### 2. Add JSON-LD `<schema-type>` to `<url>`
**Evidence:** All cited competitor pages on prompt `<prompt_id>` include `<schema-type>` markup; your page does not.
**Action:** Use [aeo-schema](../aeo-schema/) to generate the JSON-LD block.
**Effort:** ~15 min
**Expected gain:** Improves structural signals for citation.

## Strategic plays (higher effort, higher impact)

### 3. Create comparison page: `<You> vs <Competitor>`
**Evidence:** 8/20 Gemini runs for prompt `<prompt_id>` cited a comparison page from <competitor> (`<competitor>.com/<you>-vs-<competitor>`). You have no comparison page in your sitemap.
**Action:** Draft a 1500–2000 word vs page covering pricing, features, integrations, ideal use case.
**Effort:** ~4 hours
**Expected gain:** Entry into the recurring retrieval set for this prompt; ~15–25pp lift in citation rate over 4–8 weeks.

## Maintenance (alerts, decay)

### 4. Refresh `<url>` — citation rate decaying
**Evidence:** prompt `<prompt_id>` shows citation rate decay: 80% → 45% over the last 6 baselines (METHODOLOGY.md §4: HIGH severity).
**Action:** Audit the page for stale claims, outdated stats, missing competitive context. Update timestamps. Re-publish.
**Effort:** ~1 hour
**Expected gain:** Reverse the decay; restore to 70%+ over 2–4 weeks.

## Hub-page consolidation

### 5. Double down on `<url>` — your strongest hub
**Evidence:** This URL is cited across 4 of 6 tracked prompts (66% coverage). It is your highest-leverage page.
**Action:** Add 3–5 additional sections covering the entities and questions surfaced in `aeo-report` for those prompts. One page that wins more prompts is cheaper than five pages winning one each.
**Effort:** ~2 hours
**Expected gain:** Reinforces hub status; may pick up additional prompts.

## Cannibalization fixes

### 6. Consolidate `<url-a>` and `<url-b>`
**Evidence:** Both pages are cited for prompt `<prompt_id>` with 60%/40% share — the model can't decide which to surface. Internal competition is diluting both.
**Action:** Pick the canonical URL (the one ranking better; usually the older or more comprehensive). 301 the other. Merge unique content into the canonical.
**Effort:** ~1 hour
**Expected gain:** Concentrated citation share on one URL; cleaner signal to the model.