skills/aeo-optimization/SKILL.md
AI Engine Optimization - semantic triples, page templates, content clusters for AI citations
npx skillsauth add alinaqi/claude-bootstrap aeo-optimizationInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Purpose: Optimize content for AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) so your brand gets cited in AI-generated answers.
Source: Based on HubSpot's AEO Guide and industry best practices.
┌────────────────────────────────────────────────────────────────┐
│ THE GREAT DECOUPLING │
│ ──────────────────────────────────────────────────────────── │
│ Impressions ≠ Clicks anymore. │
│ AI engines compile answers from multiple sources. │
│ More buyer journey happens inside chat experiences. │
│ 58% of Google searches = zero clicks (AI overviews). │
├────────────────────────────────────────────────────────────────┤
│ THE OPPORTUNITY │
│ ──────────────────────────────────────────────────────────── │
│ Shape what AI engines say about your category and product. │
│ Get cited as the authoritative source. │
│ Best answer > Best page ranking. │
└────────────────────────────────────────────────────────────────┘
Key Stats:
AI engines use three main signals to select content for answers:
Facts that appear across multiple credible sources get trusted and reused.
How to build consensus:
Net-new insight beats generic advice. AI engines prefer content that adds value.
How to add information gain:
Clear entities and tidy structure reduce ambiguity and boost quotability.
How to optimize structure:
What they are: Compact facts that AI engines (and humans) can't misread.
Pattern: [Subject] [verb] [object].
✅ GOOD (clear triples):
- HubSpot CRM syncs contact and company data.
- Lead Scoring assigns priority based on engagement.
- Workflows trigger email sequences from events.
❌ BAD (vague, no clear entity):
- The system helps with various tasks.
- It can do many things for users.
- This improves overall performance.
For every key claim, ask:
Every substantive paragraph should follow this structure:
[Feature] helps [User/Role] with [Job].
It [mechanism/inputs] to [process].
Teams see [metric/result] in [timeframe/context].
Triples:
- [Subject] [verb] [object].
- [Subject] [verb] [object].
Lead Scoring helps sales teams prioritize prospects. It combines
page views, email engagement, and firmographic data to assign a
numeric score, then auto-enrolls high scorers into follow-up
sequences. Reps focus on qualified accounts and book 40% more
meetings.
- Lead Scoring assigns scores from engagement data.
- High scorers trigger automated follow-up sequences.
Goal: Define the category, tie it to your product, earn citations.
# What is [Category]? — [1-2 line value promise]
## What is [Category]? (~80 words)
[Plain definition in everyday language. Name adjacent entities.]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
## Why it matters now (~60 words)
[One paragraph. Mention shift to answers over links; tie to buyer outcomes.]
## How to apply it (3-5 bullets)
- [Action 1]
- [Action 2]
- [Action 3]
## FAQ
**Q: [Question]?**
A: [~1 sentence answer]
**Q: [Question]?**
A: [~1 sentence answer]
**Q: [Question]?**
A: [~1 sentence answer]
---
**Links:** [Category hub] | [Product/Feature] | [Credible source 1] | [Credible source 2]
**CTA:** [Demo / Template / Signup]
**Schema:** Article + FAQ. Author + last updated.
Goal: Clarify capability, fit, and next step; reinforce category linkage.
# [Product/Feature] — [Outcome in 3-5 words]
**[Product/Feature] enables [Outcome] for [User/Role].**
## [Feature Area 1]
[2-4 sentences using Feature → How → Outcome]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
## [Feature Area 2]
[2-4 sentences using Feature → How → Outcome]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
## [Feature Area 3]
[2-4 sentences using Feature → How → Outcome]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
## FAQ
**Q: [Question]?**
A: [~1 sentence]
**Q: [Question]?**
A: [~1 sentence]
**Q: [Question]?**
A: [~1 sentence]
---
**Links:** Back to [Category Explainer] | Forward to [Demo/Trial]
**Proof:** [Benchmark/Analyst/Customer proof]
**Notes:** Requirements/limits (pricing tier, integrations)
**Schema:** Article + FAQ. Author + last updated.
Goal: Help readers decide with clear criteria; earn fair citations.
# [Product] vs. [Alternative] — Which fits [Use case]?
## Comparison Table
| Criterion | [Product] | [Alt A] | [Alt B] | Source |
|-----------|-----------|---------|---------|--------|
| [Feature/Limit] | [value] | [value] | [value] | [link] |
| [Requirement] | [value] | [value] | [value] | [link] |
| [Best for] | [value] | [value] | [value] | [link] |
*Source-back all claims in the table or footnotes.*
## Fit Statements
1. **[Product]** suits [Team/Use case] when [Condition].
2. **[Alt A]** fits [Team/Use case] when [Condition].
3. **[Alt B]** works for [Team/Use case] when [Condition].
---
**Links:** [Category Explainer] | [Feature pages]
**CTA:** [Try / Demo / Talk to Sales]
**Schema:** Article. Author + last updated.
Goal: Connect product to outcomes in a context readers recognize.
# [Industry/Use Case] — [Outcome KPI]
**Teams reduce [Metric] by [Y%] in [Timeframe].**
## Mini Case Study
[Company/Role] used [Product/Feature] to [Action], resulting in
[Metric improvement] within [Timeframe].
## How It Works
### [Feature 1]
[Feature → How → Outcome paragraph]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
### [Feature 2]
[Feature → How → Outcome paragraph]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
## Who Uses This
**Roles:** [Role 1], [Role 2], [Role 3]
**Workflows:** [Workflow 1], [Workflow 2]
**Integrations:** [Integration 1], [Integration 2]
---
**Links:** [Product/Feature pages] | [Supporting blog]
**CTA:** [Industry template / Demo variant]
**Schema:** Article. Author + last updated.
Goal: Add information gain and support your content cluster.
# [Topic] — [Specific promise]
## Opening (~60-80 words)
[State the problem. Align terminology with Category Explainer. Preview outcome.]
## [Section 1 Heading] (~120 words max)
[Feature → How → Outcome]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
**Internal link:** [Related page]
**External citation:** [Credible source]
## [Section 2 Heading] (~120 words max)
[Feature → How → Outcome]
Triples:
1. [Subject] [verb] [object].
2. [Subject] [verb] [object].
**Internal link:** [Related page]
**External citation:** [Credible source]
## Key Takeaway
[1-2 lines summarizing the main point]
**CTA:** [Single primary action]
---
**Schema:** Article. Author + last updated.
| Element | Implementation | |---------|----------------| | Schema markup | Article + FAQ (if FAQ exists) | | Author attribution | Name, bio, credentials, photo | | Last updated date | Visible, machine-readable | | Internal links | 3-5 per page (upstream/downstream) | | External citations | 1-2 credible sources per section | | Single CTA | Demo, template, or signup (repeated once near end) |
<!-- Article Schema -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "[Page Title]",
"author": {
"@type": "Person",
"name": "[Author Name]",
"url": "[Author Bio URL]"
},
"datePublished": "[ISO Date]",
"dateModified": "[ISO Date]",
"publisher": {
"@type": "Organization",
"name": "[Company]",
"logo": "[Logo URL]"
}
}
</script>
<!-- FAQ Schema (if FAQ section exists) -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "[Question 1]",
"acceptedAnswer": {
"@type": "Answer",
"text": "[Answer 1]"
}
},
{
"@type": "Question",
"name": "[Question 2]",
"acceptedAnswer": {
"@type": "Answer",
"text": "[Answer 2]"
}
}
]
}
</script>
┌─────────────────────┐
│ Category Explainer │
│ "What is AEO?" │
└──────────┬──────────┘
│
┌──────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Product Page │ │ Product Page │ │ Product Page │
│ "Feature A" │ │ "Feature B" │ │ "Feature C" │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Blog Post │ │ Use Case │ │ Comparison │
│ (supports) │ │ (industry) │ │ (vs. alt) │
└───────────────┘ └───────────────┘ └───────────────┘
Linking Rules:
| Metric | How to Track | |--------|--------------| | AI citations | Manual checks in ChatGPT, Claude, Perplexity | | Brand mentions in AI | Search "[brand] + [category]" in AI engines | | Share of answer | How often you're cited vs competitors | | LLM traffic | GA4 referral from chatgpt.com, claude.ai, perplexity.ai | | Impressions-to-clicks gap | GSC impressions vs actual clicks |
| Mistake | Fix | |---------|-----| | Vague language ("it helps with things") | Use specific entities and triples | | No clear structure | Use Feature → How → Outcome | | Missing schema | Add Article + FAQ schema | | No author attribution | Add author name, bio, credentials | | Generic content | Add original data, examples, POV | | Orphan pages | Link into content cluster | | Fence-sitting ("it depends") | Take a clear position | | No external citations | Add 1-2 credible sources per section |
| Aspect | Traditional SEO | AEO | |--------|-----------------|-----| | Goal | Rank on page 1 | Get cited in AI answers | | Success metric | Click-through rate | Share of answer | | Content focus | Keywords | Entities + facts | | Structure | Headers for scanning | Triples for extraction | | Links | Backlinks for authority | Citations for consensus | | Updates | Periodic refresh | Continuous accuracy |
[Entity/Product] [active verb] [concrete object/result].
[Feature] helps [User] with [Job].
It [mechanism] to [process].
Teams see [result] in [timeframe].
testing
Multi-model validation council — auto-validate plans, architecture changes, and PRs via validate-plan/review before executing
development
Mandatory code reviews via /code-review before commits and deploys
development
# Visual Validation — Autonomous Screenshot Verification ## Philosophy Every UI change should be visually verified before it ships. Peekaboo captures pixel-accurate screenshots. The system compares before/after and flags visual regressions. No manual "looks good to me" — the machine verifies what the machine built. ## Autonomous Flow ``` static/* files modified (detected by auto-review-hook or E2E testkit) ↓ peekaboo image --mode screen → ~/.maggy/visual-verify/after-{ts}.png ↓ Compa
tools
# Model Routing System ## How Routing Decisions Are Made Every user prompt goes through a 9-tier classification pipeline before any AI model processes it. The system answers three questions: 1. **Which model should handle this?** — 9-tier cost/complexity classification 2. **Is the classifier itself working?** — Cascading fallback (qwen3 → kimi → deepseek → cache) 3. **Can we verify the result?** — Tool-level fallback + auto-evaluation ### The Pipeline ``` User types prompt ↓ UserPromptS