SEO + AEO Optimizer
This skill does the work, not just the diagnosis. The classic "SEO audit" hands back a report and leaves the fixing to someone else. Here, the deliverable is optimized source files (pre-deploy) or a validated live site plus a fix list (post-launch). The audit framework in references/audit-checklist.md is the checklist of what to fix, not the thing you output.
Step 0: Route to the right mode
The same /seo-aeo command handles two situations. Decide which one you're in before doing anything else:
- File mode (pre-deploy) — the user points at a directory, repo, uploaded files, or says nothing about a live site. This is the default. You will read and edit source files in place.
- Live mode (post-launch) — the user gives a deployed
https:// URL and wants the live site checked. You will fetch the live site and run validation that files alone can't support (real performance, indexing, SERP/competitor comparison, AI-citation testing).
If it's genuinely ambiguous (e.g. they paste a URL but it's a localhost/staging address, or they hand you a repo and a URL), ask one short question: "Are we optimizing the source files before deploy, or validating the live site?" Don't guess when the answer changes which files you touch.
A user typically runs this twice for one project: once on the files now, once on the live site after launch. That's expected — there's no state carried between runs except the Phase 2 playbook you write at the end of file mode.
FILE MODE (pre-deploy)
Goal: make every fix that can be made correctly from the source, so the site launches already optimized. Never fabricate facts. Never keyword-stuff. Never break the build.
Step 1: Detect the stack and locate where things live
Metadata, content, and routing live in completely different places per stack. Editing the wrong layer either does nothing or breaks the build. Detect first.
Read references/stack-adapters.md for the full per-stack map. Quick detection:
package.json present → JS app. Check dependencies:
next present → Next.js. Look for app/ (App Router: metadata export / generateMetadata in layout.tsx/page.tsx) vs pages/ (Pages Router: next/head).astro → Astro (.astro frontmatter + <head> in layout).- otherwise React/Vite SPA → metadata is usually in
index.html or injected via react-helmet; flag that SPA content may not be crawlable without SSR/prerender.
*.html files with no framework → edit the <head> and body directly.templates/ with {% %} or {{ }} → Jinja/Django/Flask. Metadata lives in base templates and blocks; per-page values come from the view/context.- Content pulled from SQL / a database → the fix belongs in the template or the data layer, not a static file. Identify the query/model, and either update the seed/content rows or the template that renders them. Flag clearly when a fix requires a data change you can't make blindly.
Output a one-line summary of what you detected and where metadata/content/sitemap live before editing. This prevents silent wrong-layer edits.
Step 2: Inventory pages and routes
List every page/route you'll optimize. For each, note its file path, its purpose, and its likely search intent (informational / commercial / transactional / navigational — see checklist). This is your work plan; show it briefly so the user can redirect before you start editing.
Step 3: Optimize each page in place
Work through references/audit-checklist.md per page. The high-leverage file-level fixes, in order:
- Title tags — unique per page, primary keyword near the front, ~50–60 chars, compelling not robotic. Rewrite, don't just flag.
- Meta descriptions — unique, ~150–160 chars, written for click-through, includes the query the page answers.
- Heading structure — exactly one H1 stating what the page is; H2/H3 in a logical semantic hierarchy. Fix duplicate/missing/skipped levels.
- Answer-first content — open key sections with a direct, extractable answer (the AEO payoff). A 2–3 sentence definition or direct answer near the top of a section is what AI engines lift. Restructure buried answers to the top.
- AEO content blocks — add FAQ sections, definitions, comparison tables, and checklists where the page genuinely supports them. These are the formats answer engines cite. Use real information from the existing content or the user; never invent stats, pricing, or claims.
- Schema / JSON-LD — add the right types (Organization, Product, FAQPage, Article, HowTo, BreadcrumbList, SoftwareApplication, etc.). See checklist for selection and
references/stack-adapters.md for where to inject per stack. Validate the JSON is well-formed.
- Image alt text — descriptive, not keyword-stuffed.
- Internal links — add contextual links between related pages to distribute authority and help crawlers; fix orphan pages.
- URL/slug structure — flag or fix slugs that are unclear or non-semantic (only rename if it won't break existing links/routing).
Step 4: Site-wide files
- robots.txt — ensure it exists, doesn't accidentally block important paths, and references the sitemap. Confirm AI crawlers (GPTBot, PerplexityBot, Google-Extended, ClaudeBot) are handled per the user's intent — explain the tradeoff rather than deciding for them.
- sitemap.xml — generate or correct it to list all canonical pages.
- Canonical tags — add where duplication risk exists.
Step 5: Deliver the changelog + Phase 2 playbook
Produce two things:
- A changelog — a concise per-file list of what changed and why (tie each to SEO or AEO impact). The user is about to deploy; they need to trust the diff.
- A Phase 2 playbook — copy
references/post-launch-playbook.md into the project (e.g. SEO-AEO-post-launch.md) and fill in the site-specific target questions and pages so it's ready to run after launch.
Flag anything you could not fix from files alone (real Core Web Vitals, render-blocking measured in-browser, SQL-content changes needing data access, third-party-script weight) and route it to Phase 2.
LIVE MODE (post-launch)
Goal: validate and fix what only the deployed site can reveal. Use web/fetch tools against the real URL.
Read references/post-launch-playbook.md and run it end to end:
- Performance — real Core Web Vitals (LCP/INP/CLS), render-blocking resources, image weight, third-party scripts.
- Indexing & crawl — is the site indexed, are key pages discoverable, does robots.txt/sitemap behave on the live host.
- SERP & competitor comparison — how target pages actually rank and what top results cover that this site doesn't (content-depth gaps).
- AEO citation loop (the highest-value step) — take the target questions and actually query ChatGPT, Perplexity, and Google AI / Gemini. Record whether the live site is cited or its facts surface. For every miss, diagnose why (answer not extractable, no schema, not authoritative, not indexed) and produce a specific fix. This loop is the reason to wait until live — you can't test citation against files.
Deliver a prioritized fix list (quick wins / mid-term / strategic) tied to what the live tests revealed.
Guardrails (both modes)
- Never fabricate. No invented statistics, pricing, testimonials, dates, or claims. If a high-value AEO block (e.g. a benchmark table) needs data the site doesn't have, propose it and ask — don't fill it in.
- Never keyword-stuff. Optimize for the human reader first; answer engines reward clarity, not density.
- Never break the build. Match the stack's conventions exactly. After edits to a JS/TS project, sanity-check that imports/exports and syntax are intact.
- Be specific, show the rewrite. Don't say "improve the title" — write the new title. Every recommendation that can be an edit should be an edit.
- Explain the why. Tie each change to a concrete SEO or AEO mechanism so the user can evaluate the diff.
Reference files
references/audit-checklist.md — the full SEO + AEO fix-checklist (what "good" looks like for every element), adapted from the enterprise audit framework into actionable fixes.references/stack-adapters.md — where metadata, schema, sitemap, and content live in HTML / Next.js (App + Pages) / React SPA / Astro / Jinja-Django / SQL-backed sites, and how to edit each safely.references/post-launch-playbook.md — the live-site validation workflow and AI-citation testing loop (Phase 2).
1---2name: seo-aeo3description: Optimize a website's source files (and, once live, the deployed site) for traditional search and AI/answer-engine visibility by directly editing the code rather than just producing an audit report. Triggered by the literal slash command /seo-aeo. When invoked, detect whether the user is pointing at local files or a repo (pre-deploy mode) or a live URL (post-launch mode), then run the matching workflow. In file mode it edits metadata, headings, schema, AEO content blocks, robots.txt, sitemap, and internal links in place. In live mode it runs real Core Web Vitals, indexing, SERP, and AI-citation validation against the deployed site.4---56# SEO + AEO Optimizer78This skill does the work, not just the diagnosis. The classic "SEO audit" hands back a report and leaves the fixing to someone else. Here, the deliverable is **optimized source files** (pre-deploy) or a **validated live site plus a fix list** (post-launch). The audit framework in `references/audit-checklist.md` is the checklist of *what to fix*, not the thing you output.910## Step 0: Route to the right mode1112The same `/seo-aeo` command handles two situations. Decide which one you're in before doing anything else:1314- **File mode (pre-deploy)** — the user points at a directory, repo, uploaded files, or says nothing about a live site. This is the default. You will read and **edit source files in place**.15- **Live mode (post-launch)** — the user gives a deployed `https://` URL and wants the live site checked. You will fetch the live site and run validation that files alone can't support (real performance, indexing, SERP/competitor comparison, AI-citation testing).1617If it's genuinely ambiguous (e.g. they paste a URL but it's a localhost/staging address, or they hand you a repo *and* a URL), ask one short question: "Are we optimizing the source files before deploy, or validating the live site?" Don't guess when the answer changes which files you touch.1819A user typically runs this twice for one project: once on the files now, once on the live site after launch. That's expected — there's no state carried between runs except the Phase 2 playbook you write at the end of file mode.2021---2223## FILE MODE (pre-deploy)2425Goal: make every fix that can be made correctly from the source, so the site launches already optimized. Never fabricate facts. Never keyword-stuff. Never break the build.2627### Step 1: Detect the stack and locate where things live2829Metadata, content, and routing live in completely different places per stack. Editing the wrong layer either does nothing or breaks the build. Detect first.3031Read `references/stack-adapters.md` for the full per-stack map. Quick detection:3233- `package.json` present → JS app. Check dependencies:34 - `next` present → Next.js. Look for `app/` (App Router: `metadata` export / `generateMetadata` in `layout.tsx`/`page.tsx`) vs `pages/` (Pages Router: `next/head`).35 - `astro` → Astro (`.astro` frontmatter + `<head>` in layout).36 - otherwise React/Vite SPA → metadata is usually in `index.html` or injected via `react-helmet`; flag that SPA content may not be crawlable without SSR/prerender.37- `*.html` files with no framework → edit the `<head>` and body directly.38- `templates/` with `{% %}` or `{{ }}` → Jinja/Django/Flask. Metadata lives in base templates and blocks; per-page values come from the view/context.39- Content pulled from **SQL / a database** → the fix belongs in the template or the data layer, not a static file. Identify the query/model, and either update the seed/content rows or the template that renders them. Flag clearly when a fix requires a data change you can't make blindly.4041Output a one-line summary of what you detected and where metadata/content/sitemap live before editing. This prevents silent wrong-layer edits.4243### Step 2: Inventory pages and routes4445List every page/route you'll optimize. For each, note its file path, its purpose, and its likely search intent (informational / commercial / transactional / navigational — see checklist). This is your work plan; show it briefly so the user can redirect before you start editing.4647### Step 3: Optimize each page in place4849Work through `references/audit-checklist.md` per page. The high-leverage file-level fixes, in order:50511. **Title tags** — unique per page, primary keyword near the front, ~50–60 chars, compelling not robotic. Rewrite, don't just flag.522. **Meta descriptions** — unique, ~150–160 chars, written for click-through, includes the query the page answers.533. **Heading structure** — exactly one H1 stating what the page is; H2/H3 in a logical semantic hierarchy. Fix duplicate/missing/skipped levels.544. **Answer-first content** — open key sections with a direct, extractable answer (the AEO payoff). A 2–3 sentence definition or direct answer near the top of a section is what AI engines lift. Restructure buried answers to the top.555. **AEO content blocks** — add FAQ sections, definitions, comparison tables, and checklists *where the page genuinely supports them*. These are the formats answer engines cite. Use real information from the existing content or the user; never invent stats, pricing, or claims.566. **Schema / JSON-LD** — add the right types (Organization, Product, FAQPage, Article, HowTo, BreadcrumbList, SoftwareApplication, etc.). See checklist for selection and `references/stack-adapters.md` for where to inject per stack. Validate the JSON is well-formed.577. **Image alt text** — descriptive, not keyword-stuffed.588. **Internal links** — add contextual links between related pages to distribute authority and help crawlers; fix orphan pages.599. **URL/slug structure** — flag or fix slugs that are unclear or non-semantic (only rename if it won't break existing links/routing).6061### Step 4: Site-wide files6263- **robots.txt** — ensure it exists, doesn't accidentally block important paths, and references the sitemap. Confirm AI crawlers (GPTBot, PerplexityBot, Google-Extended, ClaudeBot) are handled per the user's intent — explain the tradeoff rather than deciding for them.64- **sitemap.xml** — generate or correct it to list all canonical pages.65- **Canonical tags** — add where duplication risk exists.6667### Step 5: Deliver the changelog + Phase 2 playbook6869Produce two things:70711. A **changelog** — a concise per-file list of what changed and *why* (tie each to SEO or AEO impact). The user is about to deploy; they need to trust the diff.722. A **Phase 2 playbook** — copy `references/post-launch-playbook.md` into the project (e.g. `SEO-AEO-post-launch.md`) and fill in the site-specific target questions and pages so it's ready to run after launch.7374Flag anything you could **not** fix from files alone (real Core Web Vitals, render-blocking measured in-browser, SQL-content changes needing data access, third-party-script weight) and route it to Phase 2.7576---7778## LIVE MODE (post-launch)7980Goal: validate and fix what only the deployed site can reveal. Use web/fetch tools against the real URL.8182Read `references/post-launch-playbook.md` and run it end to end:83841. **Performance** — real Core Web Vitals (LCP/INP/CLS), render-blocking resources, image weight, third-party scripts.852. **Indexing & crawl** — is the site indexed, are key pages discoverable, does robots.txt/sitemap behave on the live host.863. **SERP & competitor comparison** — how target pages actually rank and what top results cover that this site doesn't (content-depth gaps).874. **AEO citation loop (the highest-value step)** — take the target questions and actually query ChatGPT, Perplexity, and Google AI / Gemini. Record whether the live site is cited or its facts surface. For every miss, diagnose why (answer not extractable, no schema, not authoritative, not indexed) and produce a specific fix. This loop is the reason to wait until live — you can't test citation against files.8889Deliver a prioritized fix list (quick wins / mid-term / strategic) tied to what the live tests revealed.9091---9293## Guardrails (both modes)9495- **Never fabricate.** No invented statistics, pricing, testimonials, dates, or claims. If a high-value AEO block (e.g. a benchmark table) needs data the site doesn't have, propose it and ask — don't fill it in.96- **Never keyword-stuff.** Optimize for the human reader first; answer engines reward clarity, not density.97- **Never break the build.** Match the stack's conventions exactly. After edits to a JS/TS project, sanity-check that imports/exports and syntax are intact.98- **Be specific, show the rewrite.** Don't say "improve the title" — write the new title. Every recommendation that can be an edit should be an edit.99- **Explain the why.** Tie each change to a concrete SEO or AEO mechanism so the user can evaluate the diff.100101## Reference files102103- `references/audit-checklist.md` — the full SEO + AEO fix-checklist (what "good" looks like for every element), adapted from the enterprise audit framework into actionable fixes.104- `references/stack-adapters.md` — where metadata, schema, sitemap, and content live in HTML / Next.js (App + Pages) / React SPA / Astro / Jinja-Django / SQL-backed sites, and how to edit each safely.105- `references/post-launch-playbook.md` — the live-site validation workflow and AI-citation testing loop (Phase 2).
BreRoz