aeo-transform

name	aeo-transform
description	Use when restructuring website content for better AI citation — splitting long paragraphs, adding FAQ schema, removing keyword stuffing, improving heading structure, or injecting structured data into HTML or Markdown files

AEO Transform — AI-Friendly Content Restructuring

Transform SEO-optimized content into AI-search-ready format using language understanding. This skill uses your Claude subscription — no additional API costs.

Transformation Strategies

Strategy	What it does	Impact
Split paragraphs	Break long paragraphs (>150 words) into self-contained statements	High
Extract FAQ	Find implicit Q&A content and convert to explicit FAQ with schema	High
Remove keyword stuffing	Replace repeated keywords with natural synonyms	High
Improve headings	Rewrite vague headings as specific, question-format headings	Medium
Add structured data	Inject JSON-LD based on content analysis	Medium
Fix dangling references	Rewrite paragraphs starting with "This", "It", "They" to be self-contained	Medium

Workflow

1. Identify targets. Ask the user which files to transform. If unsure, suggest running /aeo-scan first to find the lowest-scoring pages.

2. Read and analyze. For each file:

   • Read the full content
   • Run npx aeoptimize scan <file> --json to get the current score
   • Identify which strategies apply based on the issues found

3. Transform incrementally. Apply one strategy at a time:

   • Show the proposed change as a diff
   • Explain why this change improves AI readability
   • Wait for user approval before applying
   • Move to the next strategy

4. Preserve voice. Critical rules:

   • Never invent new content or add claims not in the original
   • Preserve the author's writing style and tone
   • Only restructure — do not rewrite meaning
   • Keep all existing data, quotes, and references intact

5. Verify improvement. After all transforms:

   • Re-run npx aeoptimize scan <file> --json
   • Show before/after score comparison
   • Highlight which dimensions improved

Strategy Details

Split Paragraphs

For each paragraph over 150 words:

• Identify distinct ideas within the paragraph
• Split at natural boundaries (topic shifts, "Additionally", "However")
• Ensure each new paragraph is self-contained (has its own subject, not just "It..." or "This...")

Extract FAQ

Look for patterns like:

• Heading followed by a short answer paragraph
• "What is X?" / "How does X work?" patterns in body text
• Implicit questions answered in the content

Convert to:

• Explicit <h3> question headings
• Concise answer paragraphs
• FAQPage JSON-LD schema

Remove Keyword Stuffing

When a word appears >3% of content (excluding stop words):

• Replace some occurrences with synonyms or related terms
• Remove redundant mentions that don't add meaning
• Ensure remaining usage feels natural

Fix Dangling References

For paragraphs starting with pronouns/conjunctions:

• Replace "This feature" with "[Product name]'s feature"
• Replace "It provides" with "[Subject] provides"
• Replace "However," with a self-contained restatement

Important

• Always show diffs before applying changes
• Transform one file at a time, one strategy at a time
• Score comparison before/after is mandatory
• This skill is interactive — never batch-transform without review
• Supports .html and .md files