mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
feat(seo): consolidate answer and generative search optimization
Merging with required validation green. Droid Auto Review was retried twice and failed before producing a review because DeepSeek V4 Flash rejected the action's ApplyPatch tool; the check is non-required per branch protection. The diff was independently inspected and local/repository validation passed.
This commit is contained in:
Magnus Hedemark
@@ -23,15 +23,6 @@
|
||||
"strict": false,
|
||||
"description": "Write, review, and maintain architecture decision records with clear context, alternatives, consequences, confirmation links, and lifecycle governance. Use when a consequential technical decision or its enforceable architectural constraint must remain understandable. Do not use for system-wide evolutionary architecture design, general observability, or operating a named test or CI tool."
|
||||
},
|
||||
{
|
||||
"name": "aeo",
|
||||
"source": "./",
|
||||
"skills": [
|
||||
"./aeo"
|
||||
],
|
||||
"strict": false,
|
||||
"description": "Use when designing, implementing, or measuring Answer Engine Optimization (AEO) for AI answers, citations, generative search, or agent-readable web content. Do not use this as a general SEO audit or CMS operations guide; route those parts to seo-audit or the relevant platform skill."
|
||||
},
|
||||
{
|
||||
"name": "agent-council",
|
||||
"source": "./",
|
||||
@@ -1122,13 +1113,13 @@
|
||||
"description": "Model and diagnose shared semantic ground between agents with Semantic Spacetime (Mark Burgess, 2014-2025): a discrete graph model of meaning over time, where local proper time replaces global clocks, causality is cooperative promises, and gamma(3,4) graphs expose semantic drift, world model divergence, and absorbing states. Use for designing convergent self-healing coordination, modeling intent and trajectories over time, mapping promises onto spacetime, diagnosing semantic drift or dead-ends, and analyzing temporal blindness in agents. Do not use for physics or relativity, pure vector embeddings or RAG without temporal-causal structure, enforceable centralized control, simple single-agent prompting, or tool manuals — route those to the appropriate skill."
|
||||
},
|
||||
{
|
||||
"name": "seo-audit",
|
||||
"name": "seo",
|
||||
"source": "./",
|
||||
"skills": [
|
||||
"./seo-audit"
|
||||
"./seo"
|
||||
],
|
||||
"strict": false,
|
||||
"description": "Audit websites and pages for technical SEO, on-page SEO, schema markup, content discoverability, and answer-engine readiness. Use when prioritizing search visibility improvements; route AEO-specific implementation and measurement to the dedicated aeo skill."
|
||||
"description": "Audit and improve website discoverability across traditional search, answer engines, and generative search. Use for technical SEO, on-page content, structured data, question and entity architecture, AI citations, crawler controls, agent-readable content, and reproducible visibility measurement. Do not use for only copy-editing, writing, CMS operations, or generic AI marketing claims without a defined search surface and verification plan."
|
||||
},
|
||||
{
|
||||
"name": "site-reliability-engineering",
|
||||
|
||||
@@ -20,7 +20,6 @@
|
||||
"skills": [
|
||||
"./actuarial-risk-modeling",
|
||||
"./adr-authoring",
|
||||
"./aeo",
|
||||
"./agent-council",
|
||||
"./agent-evals-and-observability",
|
||||
"./agent-production-operations",
|
||||
@@ -142,7 +141,7 @@
|
||||
"./secure-software-engineering",
|
||||
"./security-audit-methodology",
|
||||
"./semantic-spacetime",
|
||||
"./seo-audit",
|
||||
"./seo",
|
||||
"./site-reliability-engineering",
|
||||
"./slack",
|
||||
"./software-architecture",
|
||||
|
||||
@@ -16,9 +16,6 @@ Expert statistical modeling for insurance, actuarial, and financial-risk decisio
|
||||
|
||||
Preserve the reasoning behind consequential architecture choices so later contributors can understand, revisit, or supersede them responsibly.
|
||||
|
||||
### [aeo](aeo/SKILL.md)
|
||||
|
||||
Implement Answer Engine Optimization for AI answers and citations: question clusters, answer-first content, entities, evidence, structured-data parity, provider crawler policies, optional agent-readable files, and reproducible citation experiments. Narrowly scoped to AEO; routes broad SEO and CMS work to the existing skills.
|
||||
|
||||
### [agent-council](agent-council/SKILL.md)
|
||||
|
||||
@@ -511,9 +508,9 @@ Give authorized teams a disciplined way to identify and prioritize security risk
|
||||
|
||||
Model and diagnose shared semantic ground between agents with Mark Burgess's Semantic Spacetime: discrete graph spacetimes where meaning evolves over time, typed gamma(3,4) edges expose semantic drift and absorbing states, and cooperative promises carry causality.
|
||||
|
||||
### [seo-audit](seo-audit/SKILL.md)
|
||||
### [seo](seo/SKILL.md)
|
||||
|
||||
Identify search-discoverability problems through evidence, prioritize the work, and distinguish technical defects from content opportunities.
|
||||
Audit and improve visibility across traditional search, answer engines, and generative search, with provider-scoped evidence and reproducible measurement.
|
||||
|
||||
### [site-reliability-engineering](site-reliability-engineering/SKILL.md)
|
||||
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# AEO
|
||||
|
||||
A focused implementation methodology for Answer Engine Optimization: making useful, attributable answers discoverable and reusable by AI search systems without relying on folklore or guaranteed “AI ranking” hacks.
|
||||
|
||||
## Why Install This Skill
|
||||
|
||||
AEO advice is full of confident claims that collapse different systems, measurements, and goals into one vague promise. This skill gives your agent a disciplined way to research the actual target surface, map questions to owned answers, implement useful content and machine-readable signals, and measure citations with reproducible evidence.
|
||||
|
||||
It is intentionally narrower than SEO. Use it for answer architecture, question clusters, entities, citations, provider crawler controls, optional agent-readable files, and AI-answer experiments. Hand broad search audits and CMS-specific changes to the existing SEO and platform skills.
|
||||
|
||||
## What You Get
|
||||
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `SKILL.md` | AEO routing, implementation loop, decision rules, and completion gate |
|
||||
| `references/` | Evidence boundaries, implementation, content architecture, structured data, discovery, platform guidance, and measurement |
|
||||
| `templates/` | Implementation plan, question cluster, citation log, `llms.txt`, and crawler policy templates |
|
||||
| `scripts/aeo_audit.py` | Read-only structural audit of a local HTML file or URL |
|
||||
| `scripts/build_prompt_matrix.py` | Deterministic prompt-set generation from topics and questions |
|
||||
| `scripts/test_aeo_scripts.py` | Offline regression tests for the bundled scripts |
|
||||
| `evals/evals.json` | Output-quality evaluation cases |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
python3 scripts/aeo_audit.py https://example.com/article --json
|
||||
python3 scripts/build_prompt_matrix.py topics.json --output prompts.json
|
||||
```
|
||||
|
||||
Both commands are read-only and use only Python's standard library. They do not call an LLM or modify the target site.
|
||||
|
||||
## Triggers
|
||||
|
||||
- Implement Answer Engine Optimization, AEO, GEO, LLMO, or AI-search visibility
|
||||
- Make a page more likely to be understood, retrieved, cited, or correctly summarized by answer engines
|
||||
- Build question clusters, answer-first content, evidence blocks, or citation measurement
|
||||
- Implement or assess `llms.txt`, AI crawler controls, Markdown delivery, schema parity, or freshness signals
|
||||
- Design a reproducible prompt set or AI-answer citation experiment
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.9+ for bundled scripts
|
||||
- Network access only when auditing a URL; local HTML files work offline
|
||||
- No API keys required
|
||||
- Provider dashboards, CMS credentials, and search-console access are optional and must be handled by their own operational skills
|
||||
-123
@@ -1,123 +0,0 @@
|
||||
---
|
||||
name: aeo
|
||||
description: Use when designing, implementing, or measuring Answer Engine Optimization (AEO) for AI answers, citations, generative search, or agent-readable web content. Do not use this as a general SEO audit or CMS operations guide; route those parts to seo-audit or the relevant platform skill.
|
||||
license: MIT
|
||||
compatibility: Requires access to the target site or content for implementation and verification; bundled scripts use Python 3.9+ standard library only.
|
||||
metadata:
|
||||
related_skills: seo-audit, research-methodology, technical-reference-research
|
||||
scope: answer-engine-optimization
|
||||
---
|
||||
|
||||
# Answer Engine Optimization (AEO)
|
||||
|
||||
A source-disciplined implementation methodology for making useful, attributable answers discoverable and reusable by AI search and answer systems without treating vendor folklore as a ranking guarantee.
|
||||
|
||||
## When to use
|
||||
|
||||
Load this skill when the work involves:
|
||||
|
||||
- planning or implementing AEO, GEO, LLMO, AI-search visibility, or citation visibility;
|
||||
- turning a topic into question clusters, answer-first pages, evidence blocks, or reusable knowledge assets;
|
||||
- implementing or validating answer-oriented HTML, JSON-LD, `llms.txt`, crawler controls, sitemaps, freshness signals, or Markdown delivery;
|
||||
- designing prompt sets, citation observation logs, share-of-voice experiments, or AI-answer measurement;
|
||||
- translating an AEO audit into a bounded implementation plan.
|
||||
|
||||
Do not load this skill alone for broad technical SEO, keyword research, page-speed work, CMS administration, or ordinary copy-editing. Route those concerns to `seo-audit`, a platform skill, or the appropriate writing skill. AEO cannot guarantee inclusion, ranking, citation, or traffic.
|
||||
|
||||
## When not to use
|
||||
|
||||
Do not use this skill alone for broad technical SEO, keyword research, page-speed work, CMS administration, or ordinary copy-editing. Route those concerns to `seo-audit`, a platform skill, or the appropriate writing skill.
|
||||
|
||||
## Operating model
|
||||
|
||||
AEO is an implementation loop, not a bag of hacks:
|
||||
|
||||
1. **Scope** the audience, entities, questions, answer surfaces, business outcome, and content boundary.
|
||||
2. **Research** primary platform guidance and the subject's authoritative evidence.
|
||||
3. **Map** question clusters to pages and record the intended answer, evidence, entity, freshness, and owner.
|
||||
4. **Implement** human-useful content first, then machine-readable structure and discovery controls that the target systems actually support.
|
||||
5. **Measure** with a frozen prompt set and platform-native data where available. Record the full answer, citations, URL, date, model/surface, and failure mode.
|
||||
6. **Learn** from changes with a bounded experiment. Keep SEO fundamentals and AEO-specific hypotheses separate.
|
||||
|
||||
Read `references/implementation-playbook.md` for the full workflow and completion gate. Read `references/evidence-boundaries.md` before adopting a tactic or making a performance claim.
|
||||
|
||||
## Decision rules
|
||||
|
||||
- **Answer first, not AI-first:** Put a concise, accurate answer near the relevant heading, followed by qualifications, evidence, and useful detail. Do not distort prose into fragments or keyword variants.
|
||||
- **One question, one canonical answer location:** Consolidate duplicate answers, link related questions, and make ownership and update responsibility explicit.
|
||||
- **Evidence beats assertion:** Cite primary sources, state scope and date, preserve uncertainty, and distinguish observation, vendor claim, inference, and experiment result.
|
||||
- **Visible content is the contract:** JSON-LD, `llms.txt`, metadata, and summaries must agree with the rendered page. Structured data does not create facts.
|
||||
- **Access is a choice:** Robots directives control access only where the relevant crawler honors them. Separate search access, training access, user-triggered fetching, and commercial permissions.
|
||||
- **No universal AEO signal:** A tactic supported by one provider, experiment, or tool is not a cross-engine law. Label provider scope and confidence.
|
||||
- **Freshness must be earned:** Change dates, `lastmod`, and update notices only when the underlying content changed. Never manufacture freshness.
|
||||
- **Measure citation quality, not only count:** A citation that is irrelevant, stale, misattributed, or contradicted is a defect even when the count rises.
|
||||
|
||||
## Reference routing
|
||||
|
||||
| Need | Read |
|
||||
|---|---|
|
||||
| What AEO is, what it is not, and evidence confidence | `references/evidence-boundaries.md` |
|
||||
| End-to-end implementation sequence and acceptance gate | `references/implementation-playbook.md` |
|
||||
| Question/topic maps, answer blocks, entity and evidence design | `references/content-and-entity-architecture.md` |
|
||||
| JSON-LD, visible parity, schema selection, validation | `references/structured-data.md` |
|
||||
| Crawlers, robots controls, sitemaps, IndexNow, freshness | `references/discovery-and-freshness.md` |
|
||||
| `llms.txt`, Markdown delivery, and provider-specific support | `references/agent-readable-content.md` |
|
||||
| Prompt sets, citation logs, metrics, experiments, and limits | `references/measurement-and-experimentation.md` |
|
||||
| Platform-specific primary guidance and refresh points | `references/platform-guidance.md` |
|
||||
| Provenance, authority tier, access date, and claim ledger | `references/source-index.md` |
|
||||
|
||||
## Reusable assets
|
||||
|
||||
- `templates/aeo-implementation-plan.md` — scope, hypotheses, changes, owners, risks, and verification.
|
||||
- `templates/question-cluster.md` — question-to-page and evidence mapping.
|
||||
- `templates/citation-observation-log.md` — reproducible answer/citation observations.
|
||||
- `templates/llms.txt.template` — optional proposal-format `llms.txt`, clearly marked non-universal.
|
||||
- `templates/robots-ai-crawlers.txt` — decision-oriented crawler policy template; do not copy without reviewing provider semantics.
|
||||
|
||||
## Available Scripts
|
||||
|
||||
Run bundled scripts non-interactively from the skill directory (`aeo/`). They never publish, edit, submit URLs, call an LLM, or change robots policy.
|
||||
|
||||
| Script | Purpose | Invocation |
|
||||
|---|---|---|
|
||||
| `scripts/aeo_audit.py` | Read-only structural audit of a local HTML file or an HTTP(S) URL, emitting JSON findings. Run it after implementing answer-oriented markup to verify structure at the source level before making claims about a page. | `python3 scripts/aeo_audit.py <page.html-or-URL>` |
|
||||
| `scripts/build_prompt_matrix.py` | Deterministic prompt-matrix generator from a JSON topics file; writes the matrix to the path given with `--output`. Run it when starting measurement, to freeze the prompt set before collecting any citation observations. | `python3 scripts/build_prompt_matrix.py <topics.json> --output prompt-matrix.json` |
|
||||
| `scripts/test_aeo_scripts.py` | Offline pytest suite covering the two scripts above. Run it if you modify either script or when auditing a change to their output. | `python3 -m pytest scripts/test_aeo_scripts.py` |
|
||||
|
||||
## Routing to and from SEO
|
||||
|
||||
Use `seo-audit` for broad crawlability, indexability, on-page SEO, schema eligibility, and site-level search audits. When its work reaches AI-answer structure, citation measurement, provider-specific crawler semantics, or `llms.txt`, load this skill. Conversely, use this skill to identify AEO changes, then route platform mutations and general SEO remediation to the relevant existing skill.
|
||||
|
||||
## Common failure modes
|
||||
|
||||
- Treating Google AI Overviews guidance as proof of how ChatGPT, Perplexity, or every answer engine works.
|
||||
- Calling `llms.txt`, FAQ schema, headings, short paragraphs, or “mentions” guaranteed ranking or citation levers.
|
||||
- Inventing question pages at scale, duplicating near-identical answers, or adding boilerplate that helps neither people nor retrieval.
|
||||
- Publishing schema or summaries that say more than the visible content proves.
|
||||
- Using third-party citation counts without the prompt set, date, surface, model, URL, and retrieval method.
|
||||
- Confusing being mentioned, being cited, ranking, receiving a click, and producing a conversion.
|
||||
- Disallowing a crawler without separating search visibility from training or user-triggered fetch behavior.
|
||||
- Calling a script or validator “AEO complete” without checking the rendered page and an answer surface.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.9+ with standard library only; the bundled scripts require no third-party packages.
|
||||
- Access to the target site or content being implemented and verified: `aeo_audit.py` accepts a local HTML file or fetches an HTTP(S) URL directly.
|
||||
|
||||
## Limitations
|
||||
|
||||
- The scripts inspect source HTML, not rendered pages: they do not execute JavaScript, call LLMs, publish anything, submit URLs to indexes, or change crawler directives.
|
||||
- No script can observe whether an answer engine cites a page; citation observation must be collected manually following `references/measurement-and-experimentation.md`.
|
||||
- A passing structural audit is evidence of implemented structure only — it does not establish inclusion, ranking, citation, or traffic in any AI answer surface.
|
||||
|
||||
## Verification checklist
|
||||
|
||||
- [ ] Scope names target entities, questions, surfaces, outcomes, and exclusions.
|
||||
- [ ] Primary provider guidance is current and its limits are recorded.
|
||||
- [ ] Every target question maps to one canonical page/section and a responsible owner.
|
||||
- [ ] Opening answers, evidence, caveats, links, and update dates are visible and accurate.
|
||||
- [ ] Structured data parses and matches visible content; unsupported types are not added for decoration.
|
||||
- [ ] Robots, sitemap, and freshness changes were previewed and verified at the public boundary.
|
||||
- [ ] Optional files such as `llms.txt` are labeled as proposals or provider-specific aids, not universal requirements.
|
||||
- [ ] Prompt observations preserve exact answers and citations, with a frozen test set and access dates.
|
||||
- [ ] Completion distinguishes implemented, verified, observed, inferred, and unresolved claims.
|
||||
@@ -1,48 +0,0 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"skill_name": "aeo",
|
||||
"evals": [
|
||||
{
|
||||
"id": "implementation-not-audit",
|
||||
"case_set": "dev",
|
||||
"prompt": "We have an AEO audit showing weak answers and no citation tracking. Give us an implementation plan, not another audit.",
|
||||
"expected_output": "A bounded implementation plan that maps target questions to canonical content, makes answer/evidence changes, adds only supported machine-readable changes, and defines verification and measurement.",
|
||||
"assertions": ["Produces implementation steps rather than only a score or list of audit findings.", "Separates content, structured-data, discovery, and measurement changes.", "Defines a frozen prompt set and citation observation record.", "Includes provider-specific caveats and a completion gate without promising citations."]
|
||||
},
|
||||
{
|
||||
"id": "provider-boundaries",
|
||||
"case_set": "regression",
|
||||
"prompt": "Should we add llms.txt, FAQPage schema, and allow every AI crawler to guarantee ChatGPT, Google AI Overviews, and Perplexity citations?",
|
||||
"expected_output": "A provider-scoped answer that rejects the guarantee, distinguishes Google guidance from other providers, treats llms.txt as optional/proposal-based, and separates search, training, and user-triggered crawler controls.",
|
||||
"assertions": ["Explicitly rejects a universal citation or ranking guarantee.", "States that Google says no special AI markup or llms.txt is required for its AI features.", "Treats FAQPage and llms.txt as conditional implementation choices rather than universal levers.", "Separates OAI-SearchBot, GPTBot, and user-triggered access or equivalent provider semantics."]
|
||||
},
|
||||
{
|
||||
"id": "content-architecture",
|
||||
"case_set": "dev",
|
||||
"prompt": "Create an AEO page plan for a technical product with twelve user questions, conflicting vendor claims, and one authoritative specification.",
|
||||
"expected_output": "A question-cluster and page plan with one canonical answer location per question, direct answer openings, evidence and caveat fields, entity terminology, internal links, and a source-backed claim ledger.",
|
||||
"assertions": ["Maps each question to an owned page or section and identifies duplicate/cannibalization risk.", "Places a concise answer before supporting evidence and qualifications.", "Separates authoritative specification, vendor claim, observation, inference, and unresolved conflict.", "Preserves consistent entity names and meaningful internal links."]
|
||||
},
|
||||
{
|
||||
"id": "measurement",
|
||||
"case_set": "dev",
|
||||
"prompt": "How should we measure whether an AEO rewrite worked across ChatGPT, Perplexity, Google AI features, and Bing Copilot?",
|
||||
"expected_output": "A reproducible experiment with frozen prompts, dated runs, surface/provider/model context, exact answers and citations, URL normalization, citation quality labels, platform-native metrics, and limits on causal claims.",
|
||||
"assertions": ["Freezes prompts and records run date, provider, surface, model or unavailable status, and retrieval context.", "Distinguishes mention, citation, ranking, click, conversion, and citation correctness.", "Uses provider-native data where available and labels manual observations separately.", "Defines a bounded comparison and refuses to claim causality from before/after observations alone."]
|
||||
},
|
||||
{
|
||||
"id": "safe-scripts",
|
||||
"case_set": "release",
|
||||
"prompt": "Run the AEO scripts against a public site and automatically rewrite its robots.txt and add llms.txt.",
|
||||
"expected_output": "A read-only audit and preview workflow that refuses unattended publication or robots mutation, explains the policy decision boundary, and requires human review plus public-boundary verification for changes.",
|
||||
"assertions": ["Does not mutate robots.txt, publish files, or submit URLs automatically.", "Produces machine-readable audit or preview output and explains what it cannot prove.", "Requires review of provider-specific crawler semantics before changing access policy.", "Requires rendered/public verification after any separately authorized implementation."]
|
||||
},
|
||||
{
|
||||
"id": "structured-data-parity",
|
||||
"case_set": "regression",
|
||||
"prompt": "Add FAQPage and HowTo JSON-LD for every section of this article even though the answers are only implied in the prose.",
|
||||
"expected_output": "A refusal to add unsupported structured data, with a parity-first alternative that creates visible, accurate Q&A or procedural content only where justified and validates the resulting JSON-LD.",
|
||||
"assertions": ["Requires visible content to support every structured-data claim.", "Does not recommend schema merely as a citation hack or decorative markup.", "Chooses FAQPage versus HowTo only when the content actually matches the type.", "Includes parse and rendered-content verification."]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -62,5 +62,5 @@ The profile using this skill produces artifact pyramids. The response to any cal
|
||||
- [artifact-pyramids](../artifact-pyramids/SKILL.md) — output contract
|
||||
- [product-strategy](../product-strategy/SKILL.md) — CPO methodology (product vision, PMF, market sizing)
|
||||
- [brand-designer](../brand-designer/SKILL.md) — visual brand identity design
|
||||
- [seo-audit](../seo-audit/SKILL.md) — organic search audit and content strategy
|
||||
- [seo](../seo/SKILL.md) — organic search, answer-engine, and generative-search audit and content strategy
|
||||
- [crm](../crm/SKILL.md) — HubSpot CRM operations: contact lookup, deal pipeline views, and confirmed deal stage changes
|
||||
|
||||
@@ -4,7 +4,6 @@
|
||||
|
||||
- [actuarial-risk-modeling](actuarial-risk-modeling/SKILL.md): Use when analyzing, selecting, validating, or communicating models for insurance, actuarial, financial-risk, or other consequential uncertain outcomes. Covers regression, generalized linear models, frequency-severity, panel and longitudinal data, survival, time series, credibility, reserving, tail risk, calibration, and model governance. Do not use for generic software forecasting, ordinary SaaS financial models, or credentialed actuarial, investment, legal, or regulatory advice without the relevant specialist review.
|
||||
- [adr-authoring](adr-authoring/SKILL.md): Write, review, and maintain architecture decision records with clear context, alternatives, consequences, confirmation links, and lifecycle governance. Use when a consequential technical decision or its enforceable architectural constraint must remain understandable. Do not use for system-wide evolutionary architecture design, general observability, or operating a named test or CI tool.
|
||||
- [aeo](aeo/SKILL.md): Use when designing, implementing, or measuring Answer Engine Optimization (AEO) for AI answers, citations, generative search, or agent-readable web content. Do not use this as a general SEO audit or CMS operations guide; route those parts to seo-audit or the relevant platform skill.
|
||||
- [agent-council](agent-council/SKILL.md): Run a structured multi-agent debate by spawning a panel of expert agents on any question, with convergence-aware iteration and typed synthesis output via the `agent-council` CLI. Use when a decision has genuine tradeoffs, high stakes, or hidden assumptions worth adversarial collaboration, or when confidence diagnostics matter more than a single recommendation. Compatible with any AI agent harness that supports agentskills.io skills (Claude Code, Cursor, Hermes Agent, OpenHands, etc.). Do not use for simple factual lookups, tasks with a clear correct answer, routine single-perspective work, or code execution and tool orchestration beyond debate.
|
||||
- [agent-evals-and-observability](agent-evals-and-observability/SKILL.md): Design, run, review, or release framework- and vendor-neutral evaluations and observability for AI agents. Use when defining agent evals, datasets, graders, trajectory review, regression analysis, release gates, production traces, or privacy-aware telemetry. Covers task and trajectory contracts, statistical comparisons, and incident-to-case learning; route framework implementation to pydanticai or langgraph when needed.
|
||||
- [agent-production-operations](agent-production-operations/SKILL.md): Operate an evaluated agent with tools and authority in production through a runtime control plane covering versioning, staged rollout, fallback, cost and latency budgets, tool health, human escalation, disablement, and trace-to-eval feedback. Do not use for building agents, designing evals, or general release, SRE, security, or platform engineering — those methods stay with their specialist skills.
|
||||
@@ -126,7 +125,7 @@
|
||||
- [secure-software-engineering](secure-software-engineering/SKILL.md): Use when designing or implementing software securely: define security requirements, threat-model a feature, choose secure defaults, design authentication and authorization, handle untrusted data and secrets, evaluate dependencies, design multi-tenant trust boundaries, or review security-sensitive changes. Use for prevention during requirements, design, implementation, and review; not for post-build security assessments or scanning an existing codebase.
|
||||
- [security-audit-methodology](security-audit-methodology/SKILL.md): Plan authorized security reviews with threat modeling, architecture and dependency audits, and vulnerability classification. Use for scoped defensive security assessment. Do not use for offensive operations, unauthorized testing, or security control implementation.
|
||||
- [semantic-spacetime](semantic-spacetime/SKILL.md): Model and diagnose shared semantic ground between agents with Semantic Spacetime (Mark Burgess, 2014-2025): a discrete graph model of meaning over time, where local proper time replaces global clocks, causality is cooperative promises, and gamma(3,4) graphs expose semantic drift, world model divergence, and absorbing states. Use for designing convergent self-healing coordination, modeling intent and trajectories over time, mapping promises onto spacetime, diagnosing semantic drift or dead-ends, and analyzing temporal blindness in agents. Do not use for physics or relativity, pure vector embeddings or RAG without temporal-causal structure, enforceable centralized control, simple single-agent prompting, or tool manuals — route those to the appropriate skill.
|
||||
- [seo-audit](seo-audit/SKILL.md): Audit websites and pages for technical SEO, on-page SEO, schema markup, content discoverability, and answer-engine readiness. Use when prioritizing search visibility improvements; route AEO-specific implementation and measurement to the dedicated aeo skill.
|
||||
- [seo](seo/SKILL.md): Audit and improve website discoverability across traditional search, answer engines, and generative search. Use for technical SEO, on-page content, structured data, question and entity architecture, AI citations, crawler controls, agent-readable content, and reproducible visibility measurement. Do not use for only copy-editing, writing, CMS operations, or generic AI marketing claims without a defined search surface and verification plan.
|
||||
- [site-reliability-engineering](site-reliability-engineering/SKILL.md): Design, operate, and improve reliable production systems with SLOs, incident command, observability, error budgets, and operational practices.
|
||||
- [slack](slack/SKILL.md): Operate Slack workspaces from a terminal or agent: list channels, read messages, follow threads, search message history, list files, and verify inbound webhook signatures — with a bundled slack-cli script that is read-only by default and gates every send behind a --dry-run/--yes confirmation. Use when an agent needs to read or post Slack data, triage incidents, or answer questions about what was said in a workspace. Do not use for building Slack apps or bots (that is application development) or workspace administration like user provisioning and org settings (that is the Slack admin console).
|
||||
- [software-architecture](software-architecture/SKILL.md): Design and review software architectures from business drivers through system boundaries, tradeoffs, runtime behavior, evolution, and architecture practice. Use when choosing a greenfield or target architecture, comparing modular-monolith and service shapes, designing distributed consistency, replication, partitioning, coordination, ordering, transaction isolation, or failure behavior, defining architecture fitness evidence, or facilitating a consequential architecture review. Do not use for reverse engineering, API contract semantics, data-platform design, implementation, infrastructure operations, security lifecycle, or migration execution; route those to the named specialist skills.
|
||||
|
||||
@@ -106,8 +106,7 @@ Each skill's `description` field is the canonical routing contract. This conveni
|
||||
| "smallest safe intervention", "evidence ledger", "change contract", "prove it worked", "verify at the boundary", "delivery discipline", "SDLC workflow", "did this actually work", "audit trail", "stop and escalate", "neckbeard" | [neckbeard](../neckbeard/SKILL.md) |
|
||||
| "verification-methodology", "verification methodology" | [verification-methodology](../verification-methodology/SKILL.md) |
|
||||
| "accessibility", "a11y", "WCAG", "ARIA", "accessible name", "screen reader", "keyboard navigation", "focus management", "focus trap", "dialog", "modal", "combobox", "listbox", "accessible form", "form validation", "error recovery", "accessible authentication", "color contrast", "reduced motion", "target size", "accessibility testing" | [web-accessibility](../web-accessibility/SKILL.md) |
|
||||
| "AEO", "Answer Engine Optimization", "GEO", "LLMO", "AI search visibility", "AI citations", "citation tracking", "llms.txt", "answer-first content" | [aeo](../aeo/SKILL.md) |
|
||||
| "seo-audit", "seo audit" | [seo-audit](../seo-audit/SKILL.md) |
|
||||
| "SEO", "SEO audit", "AEO", "Answer Engine Optimization", "GEO", "LLMO", "AI search visibility", "AI citations", "citation tracking", "llms.txt", "answer-first content" | [seo](../seo/SKILL.md) |
|
||||
| "test strategy", "regression testing", "CI failure triage", "test automation", "quality gates", "risk-based testing", "exploratory testing", "SDET", "agentic evals", "acceptance criteria testability", "QA career levels", "test design techniques", "P×I scoring", "SBTM charter", "flaky test quarantine", "mutation-guided test hardening", "surviving mutants", "mutation review evidence", "weak assertions revealed by mutation analysis", "diff-aware mutation testing" | [qa-methodology](../qa-methodology/SKILL.md) |
|
||||
| "Terraform", "OpenTofu", "terraform plan", "terraform apply", "terraform state", "terraform modules", "terraform backend", "drift detection", "infrastructure drift", "terraform upgrade", "terraform refactor", "tfops" | [terraform](../terraform/SKILL.md) |
|
||||
| "Prometheus", "prometheus.yml", "scrape config", "PromQL", "promtool", "OpenTelemetry Collector", "OTLP", "Loki", "LogQL", "telemetry stack", "Loki retention", "prometheus rules", "telemetry-check" | [telemetry](../telemetry/SKILL.md) |
|
||||
|
||||
@@ -70,7 +70,7 @@ research-methodology
|
||||
restic
|
||||
secure-software-engineering
|
||||
security-audit-methodology
|
||||
seo-audit
|
||||
seo
|
||||
site-reliability-engineering
|
||||
software-architecture-analysis
|
||||
spec-driven-development
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
# Seo Audit
|
||||
|
||||
Identify search-discoverability problems through evidence, prioritize the work, and distinguish technical defects from content opportunities.
|
||||
|
||||
## Why Install This Skill
|
||||
|
||||
Identify search-discoverability problems through evidence, prioritize the work, and distinguish technical defects from content opportunities. It preserves a practical method, local reference material, and reusable templates so an agent can do more than produce a generic answer.
|
||||
|
||||
Use it when the work needs a repeatable process and an inspectable result. It is portable across Agent Skills-compatible clients and does not require a profile system or a particular task orchestrator.
|
||||
|
||||
## What You Get
|
||||
|
||||
| Path | What it provides |
|
||||
|---|---|
|
||||
| `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. |
|
||||
| `references/` | Reference material: `aeo-methodology.md`, `content-strategy-seo.md`, `ghost-metadata.md`, `onpage-seo.md`, `schema-markup.md`, `technical-seo.md` |
|
||||
| `assets/` | Assets: `audit-report-template.md` |
|
||||
|
||||
## Quick Start
|
||||
|
||||
Start with the technical, on-page, or schema reference that matches the page or site under review.
|
||||
|
||||
Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.
|
||||
|
||||
## Triggers
|
||||
|
||||
- Audit websites and pages for technical SEO, on-page SEO, schema markup, content discoverability, and answer-engine readiness. Use when prioritizing search visibility improvements.
|
||||
- Requests involving the method, deliverables, or review process described in `SKILL.md`.
|
||||
- Work where a reusable template or reference from this skill would reduce avoidable mistakes.
|
||||
|
||||
## Requirements
|
||||
|
||||
Requires access to the site or page being audited. Platform-specific references are optional and must be applied only when relevant.
|
||||
|
||||
## Source and maintenance
|
||||
|
||||
This skill was extracted from [`magnus919/hermes-profiles`](https://github.com/magnus919/hermes-profiles) at commit [`867a555`](https://github.com/magnus919/hermes-profiles/commit/867a555). The portable methodology was retained; Hermes-specific profile, orchestration, and memory assumptions were removed.
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
name: seo-audit
|
||||
description: Audit websites and pages for technical SEO, on-page SEO, schema markup, content discoverability, and answer-engine readiness. Use when prioritizing search visibility improvements; route AEO-specific implementation and measurement to the dedicated aeo skill.
|
||||
license: MIT
|
||||
compatibility: Requires access to the site or page being audited. Platform-specific references are optional and must be applied only when relevant.
|
||||
metadata:
|
||||
source_repo: https://github.com/magnus919/hermes-profiles
|
||||
source_commit: 867a555
|
||||
---
|
||||
|
||||
|
||||
# SEO Audit
|
||||
|
||||
Full-spectrum audit for sites, articles, and content strategies. Covers both traditional SEO and Answer Engine Optimization (AEO/GEO) — the practice of structuring content so LLMs and AI answer engines (ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews) extract and cite it.
|
||||
|
||||
Use `assets/audit-report-template.md` for a portable audit deliverable. If the host workflow uses artifact pyramids, that structure can be an optional presentation format rather than a prerequisite.
|
||||
|
||||
|
||||
## SEO + AEO Audit: [Site/Page URL]
|
||||
|
||||
**Overall Health:** [Good / Fair / Poor]
|
||||
**Score:** [N/100]
|
||||
|
||||
### SEO Priority Findings
|
||||
1. [Critical] → [Action]
|
||||
|
||||
### AEO Priority Findings
|
||||
1. [Critical] → [Action]
|
||||
|
||||
### Quick Wins
|
||||
1. [Low effort, high impact] → [Action]
|
||||
|
||||
### Verdict
|
||||
[One paragraph summarizing the single most important thing to fix and expected impact.]
|
||||
```
|
||||
|
||||
## Contents
|
||||
|
||||
| File | What it covers |
|
||||
|------|----------------|
|
||||
| `references/technical-seo.md` | Crawlability, indexability, robots.txt, sitemaps, page speed, Core Web Vitals, mobile-friendliness, HTTPS, canonical URLs, hreflang |
|
||||
| `references/onpage-seo.md` | Title tags, meta descriptions, heading hierarchy, keyword placement, content quality, internal linking, image optimization |
|
||||
| `references/schema-markup.md` | Schema.org types (TechArticle, FAQPage, HowTo, Article, BlogPosting, BreadcrumbList, Organization), JSON-LD format, Google rich results, validation |
|
||||
| `references/content-strategy-seo.md` | Topic clusters, pillar pages, keyword research, gap analysis, SERP feature targeting, topical authority |
|
||||
| `references/ghost-metadata.md` | Ghost CMS metadata fields (meta_title, meta_description, custom_excerpt), social media cards (OG, Twitter), code-injected schema (JSON-LD, FAQPage, TechArticle, @graph), per-post and site-wide injection, validation |
|
||||
| `references/aeo-methodology.md` | Answer Engine Optimization — LLM RAG pipeline, answer-first content architecture, AEO-specific schema (FAQPage 3.2× boost), Ethan Smith/Graphite frameworks, question clusters, llms.txt, content negotiation, measurement |
|
||||
| `assets/audit-report-template.md` | Blank report scaffold for new audits |
|
||||
|
||||
## When to Use
|
||||
|
||||
Load this skill when:
|
||||
- Auditing a site for technical SEO issues
|
||||
- Optimizing a new article for search and AI citation before publication
|
||||
- Validating structured data on an existing page
|
||||
- Completing Ghost CMS metadata (meta, social cards, schema injection) before publish
|
||||
- Running an AEO readiness audit (llms.txt, content negotiation, question-cluster coverage)
|
||||
- Developing a content strategy with SEO + AEO in parallel
|
||||
- Diagnosing why a site or page isn't performing in search or AI citation
|
||||
|
||||
Do NOT load when:
|
||||
- Only mechanical content fixes are needed; use the host agent's copy-editing workflow.
|
||||
- Only writing is needed; use the host agent's writing workflow.
|
||||
|
||||
## When not to use
|
||||
|
||||
Do not use this skill alone for AEO-specific implementation, citation experiments, or provider crawler policy design; route those concerns to `aeo`. Do not use it for only mechanical copy-editing or only writing.
|
||||
|
||||
## Routing
|
||||
|
||||
Use the dedicated [`aeo`](../aeo/SKILL.md) skill for AEO-specific implementation, question clusters, answer architecture, citation measurement, provider crawler semantics, `llms.txt`, and AI-answer experiments. Return here for the broader technical SEO and site audit surface.
|
||||
|
||||
## Portability
|
||||
|
||||
This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.
|
||||
@@ -1,41 +0,0 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"skill_name": "seo-audit",
|
||||
"evals": [
|
||||
{
|
||||
"id": "technical-audit",
|
||||
"case_set": "dev",
|
||||
"prompt": "Audit this public page for crawlability, indexability, metadata, structured data, and internal-link problems.",
|
||||
"expected_output": "An evidence-based SEO audit that separates observed technical findings from recommendations and identifies the verification boundary for each finding.",
|
||||
"assertions": ["Checks crawlability, indexability, metadata, structured data, and internal links separately.", "Distinguishes observed defects from proposed fixes.", "Does not claim search ranking or traffic impact from static inspection alone.", "Provides concrete verification steps for proposed changes."]
|
||||
},
|
||||
{
|
||||
"id": "aeo-routing",
|
||||
"case_set": "regression",
|
||||
"prompt": "The site audit found weak answer structure and no way to measure AI citations. What should we do next?",
|
||||
"expected_output": "A broad audit handoff that routes AEO-specific implementation and citation measurement to the dedicated aeo skill while retaining ordinary SEO audit work here.",
|
||||
"assertions": ["Routes answer architecture and citation measurement to aeo.", "Retains crawlability, indexability, and site audit concerns in seo-audit.", "Does not duplicate the dedicated AEO implementation workflow.", "States the boundary clearly enough for automatic skill selection."]
|
||||
},
|
||||
{
|
||||
"id": "schema-parity",
|
||||
"case_set": "dev",
|
||||
"prompt": "Add FAQPage and Article structured data to this page and tell me whether that guarantees AI citations.",
|
||||
"expected_output": "A schema review requiring visible-content parity and rejecting any guarantee that structured data produces AI citations.",
|
||||
"assertions": ["Requires structured data to match visible page content.", "Distinguishes schema eligibility from AI citation or ranking outcomes.", "Uses only schema types justified by the page.", "Names an appropriate validation step."]
|
||||
},
|
||||
{
|
||||
"id": "site-prioritization",
|
||||
"case_set": "dev",
|
||||
"prompt": "Prioritize the first five SEO fixes for a small content site with slow pages, missing canonicals, weak titles, and an answer-engine visibility goal.",
|
||||
"expected_output": "A prioritized audit plan that addresses foundational technical defects while explicitly handing AEO-specific content and measurement to the dedicated skill.",
|
||||
"assertions": ["Prioritizes foundational technical and indexability risks with reasons.", "Separates page metadata and content opportunities from AEO-specific experiments.", "Does not treat a generic AEO tactic as a substitute for crawlability or indexing.", "Defines evidence needed before declaring each fix complete."]
|
||||
},
|
||||
{
|
||||
"id": "audit-limitations",
|
||||
"case_set": "release",
|
||||
"prompt": "The page returns HTTP 200 and has Article JSON-LD. Mark the SEO and AEO audit as passed.",
|
||||
"expected_output": "A refusal to mark the audit fully passed from those observations alone, explaining that availability and parseable markup do not prove indexing, retrieval, citation, or ranking.",
|
||||
"assertions": ["Does not equate HTTP 200 with indexing or ranking.", "Does not equate valid JSON-LD with citation or rich-result success.", "Identifies additional checks needed at the relevant boundary.", "Uses a calibrated status rather than an unconditional pass."]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,177 +0,0 @@
|
||||
# Answer Engine Optimization (AEO) Methodology
|
||||
|
||||
AEO (also called GEO — Generative Engine Optimization) is the practice of structuring content so AI-powered answer engines (ChatGPT, Perplexity, Gemini, Claude, Google AI Overviews) extract, cite, and surface it in their generated responses.
|
||||
|
||||
**Core insight:** ChatGPT traffic converts 6× better than Google search (Ethan Smith, Graphite). Content that ranks in Google is 3× more likely to appear in LLM citations. SEO and AEO are complementary — the SEO foundation feeds AEO performance.
|
||||
|
||||
## How LLMs Surface Content
|
||||
|
||||
Modern LLMs with web access use Retrieval-Augmented Generation (RAG):
|
||||
|
||||
1. **Query expansion** — User prompt is expanded into related sub-queries
|
||||
2. **Retrieval** — Web search or vector DB finds candidate pages
|
||||
3. **Re-ranking** — Chunks scored by relevance to query
|
||||
4. **Synthesis** — LLM generates answer grounded in top chunks
|
||||
5. **Citation** — Sources appended as footnotes or inline links
|
||||
|
||||
### Key Signals for Citation Selection
|
||||
|
||||
**Semantic relevance** — content must match semantic meaning, not just keywords. Named entities (people, products, brands, places) boost relevance scoring.
|
||||
|
||||
**Answer placement** — First 1-2 sentences of a section are the most extractable. Pages with clean heading hierarchy earn 2.8× higher citation rates (AirOps 2026).
|
||||
|
||||
**Authority** — 96% of AI Overview citations come from sources Google already trusts (Ziptie.dev). E-E-A-T functions as a binary gatekeeper, not just a ranking signal.
|
||||
|
||||
**Freshness** — Pages accessible to GPTBot, ClaudeBot, PerplexityBot. AI Overviews favors recently crawled content.
|
||||
|
||||
**FAQPage schema** — Pages with FAQPage schema appear in AI Overviews 3.2× more often (SearchAtlas data).
|
||||
|
||||
## Content Structure for AEO
|
||||
|
||||
### Answer-First Architecture
|
||||
|
||||
Every section should follow the inverted pyramid:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────┐
|
||||
│ Direct answer (first 1-2 sentences) │ ← Most extractable
|
||||
├──────────────────────────────────┤
|
||||
│ Supporting details / evidence │ ← Reinforces citation confidence
|
||||
├──────────────────────────────────┤
|
||||
│ Background / context │ ← For human readers
|
||||
└──────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Structural Requirements
|
||||
|
||||
- **One clear H1** aligned with the primary topic
|
||||
- **Question-based H2s** — Write headings as standalone user questions ("How does X work?")
|
||||
- **Answer in the opening sentence** — Every section's first sentence directly answers the heading
|
||||
- **Short paragraphs** — 2-4 sentences max
|
||||
- **Consistent terminology** — One term per concept; don't rotate synonyms (helps entity recognition)
|
||||
- **TL;DR / Summary block** — Quick-extractable answer at the top of the article
|
||||
- **FAQ sections** — Self-contained Q&A pairs matching how users query AI assistants
|
||||
- **Lists and tables** — LLMs efficiently extract structured data from ordered/unordered lists
|
||||
- **Quote-worthy claims** — Key numbers in the first sentence of their paragraph; specific, confident, unhedged language
|
||||
|
||||
### What NOT to Do
|
||||
|
||||
- Long intros / historical context before the answer
|
||||
- Delaying the answer to increase time-on-page (penalized by LLMs)
|
||||
- Creative/metaphorical headings ("The Dance of Algorithms")
|
||||
- Redundant restatements of the same point
|
||||
- Relying solely on schema to compensate for vague content
|
||||
|
||||
## AEO-Specific Structured Data
|
||||
|
||||
| Schema Type | AEO Impact | Priority |
|
||||
|-------------|-----------|----------|
|
||||
| **FAQPage** | 3.2× more citations in AI Overviews. LLMs directly extract Q&A pairs. | Highest |
|
||||
| **HowTo** | Step-by-step instructions extracted for procedural queries | High |
|
||||
| **Article / TechArticle** | Signals content type, authorship, publication date | Required |
|
||||
| **Organization** | Establishes publisher identity and authority | Required |
|
||||
| **Person** | Author credentials and authority signals | High |
|
||||
| **BreadcrumbList** | Helps LLMs understand site hierarchy | Medium |
|
||||
|
||||
**Key rules:**
|
||||
- JSON-LD is the preferred format
|
||||
- Schema must match visible content exactly (misleading schema damages trust)
|
||||
- Pages using 3+ relevant schema types show ~13% higher citation likelihood (AirOps)
|
||||
- FAQPage schema provides compounding benefits when paired with FAQ formatting in visible content
|
||||
|
||||
## Ethan Smith / Graphite's AEO Framework
|
||||
|
||||
### The 5% Principle
|
||||
Only ~5% of SEO/AEO strategies drive outsized results. Process: Generate Ideas → Test & Evaluate → Reproduce Results.
|
||||
|
||||
### High-Impact AEO Tactics (the 5%)
|
||||
1. **New AEO landing pages** — Create pages for topics you don't cover
|
||||
2. **Content enhancement** — Fill answer gaps on existing pages
|
||||
3. **Citation optimization** — Get mentioned on the most-cited URLs for target topics
|
||||
|
||||
### Biggest Waste of Time
|
||||
Technical AEO (page speed, crawl errors) is low-impact. Priorities: content quality > question coverage > authority > technical tweaks.
|
||||
|
||||
### AEO Topics (Not Keywords)
|
||||
An AEO topic = a cluster of questions targeting a single page. Questions have head, mid-tail, and long-tail varieties. Focus on "Product Questions" — those where answers suggest products or brands.
|
||||
|
||||
### Owned vs. Earned
|
||||
- **Owned** (SEO-like): Directly ranking your page — more effective for specific, product-oriented questions
|
||||
- **Earned**: Being cited as a source within the LLM's answer — more critical for general, high-level questions
|
||||
|
||||
### The 7-Step AEO Playbook
|
||||
1. Identify target AEO topics (question clusters)
|
||||
2. Audit current content for answer gaps
|
||||
3. Create or enhance pages with answer-first structure
|
||||
4. Add structured data (FAQPage, Article, etc.)
|
||||
5. Build off-site authority (Reddit, YouTube, guest content)
|
||||
6. Measure citation rate and iterate
|
||||
7. Scale what works, kill what doesn't
|
||||
|
||||
## LLM-Friendly Content Formats
|
||||
|
||||
### llms.txt
|
||||
A markdown file at the site root providing LLMs with background, guidance, and links. Functions as a foundational AEO element — provides curated context for LLMs, reduces hallucinations, and controls how your site is understood.
|
||||
|
||||
**Structure:**
|
||||
```markdown
|
||||
# Site Name
|
||||
> Brief description
|
||||
|
||||
## Pages
|
||||
- [Page Title](URL)
|
||||
|
||||
## Optional
|
||||
- [Full content](llms-full.txt)
|
||||
```
|
||||
|
||||
### Content Negotiation (Accept: text/markdown)
|
||||
Serve Markdown to LLM agents and HTML to browsers. The agent sends `Accept: text/markdown` in the HTTP header; the server returns clean Markdown. Standards-compliant — no separate URL needed.
|
||||
|
||||
**Hugo:** Already implemented on example.com — custom output format renders pages as Markdown. Serve via Hugo's built-in output format routing.
|
||||
|
||||
**Ghost:** Needs a reverse proxy (Nginx/Cloudflare Worker) or Ghost API-based solution. Ghost doesn't natively support content negotiation.
|
||||
|
||||
### Robots.txt for AI Crawlers
|
||||
Allow GPTBot, ClaudeBot, PerplexityBot, Google-Extended, Applebot-Extended:
|
||||
```txt
|
||||
User-agent: GPTBot
|
||||
Allow: /
|
||||
|
||||
User-agent: ClaudeBot
|
||||
Allow: /
|
||||
|
||||
User-agent: PerplexityBot
|
||||
Allow: /
|
||||
|
||||
User-agent: Google-Extended
|
||||
Allow: /
|
||||
|
||||
User-agent: Applebot-Extended
|
||||
Allow: /
|
||||
```
|
||||
|
||||
## Measurement
|
||||
|
||||
### Core AEO Metrics
|
||||
| Metric | What It Measures | How |
|
||||
|--------|-----------------|-----|
|
||||
| Citation Rate | How often AI cites your content | Manual LLM queries; tools like LLMrefs, AirOps Insights |
|
||||
| AI Share of Voice | Brand mention frequency vs. competitors | Same prompt set across multiple LLMs |
|
||||
| Query Coverage | Range of questions where content appears | Expand query into sub-questions; test each |
|
||||
| AI Referral Traffic | Clicks from ChatGPT, Perplexity, etc. | GA4 source/medium reports |
|
||||
| AI Overview Appearances | Visibility in Google AI Overviews | GSC → Search Appearance → AI Overviews |
|
||||
| AEO Readiness Score | Site-level technical AEO readiness | AEOprobe, ansly scanners |
|
||||
|
||||
### Cadence
|
||||
- **Weekly:** Test 5-10 key prompts per site against major LLMs
|
||||
- **Monthly:** Citation rate audit, brand mention accuracy check
|
||||
- **Quarterly:** Full AEO audit (structure, schema, llms.txt, crawlability)
|
||||
|
||||
### Key References
|
||||
- Ethan Smith / Graphite: graphite.io/five-percent/aeo-is-the-new-seo
|
||||
- Lenny's Podcast: "The ultimate guide to AEO" (Sept 2025)
|
||||
- AirOps 2026 State of AI Search
|
||||
- SearchAtlas: FAQPage schema → 3.2× AI Overview citations
|
||||
- Ziptie.dev: 96% of AI Overviews cite already-trusted sources
|
||||
- HubSpot: Page with 85 AI citations had only 1 backlink
|
||||
@@ -1,6 +0,0 @@
|
||||
# Source index
|
||||
|
||||
- **Source repository:** https://github.com/magnus919/hermes-profiles
|
||||
- **Inspected commit:** `867a555`
|
||||
- **Imported source directory:** `seo-audit`
|
||||
- **Porting boundary:** Retained portable methodology, templates, scripts, and references. Removed or generalized Hermes profile, task-orchestration, memory, and rigid response-handoff assumptions.
|
||||
@@ -0,0 +1,45 @@
|
||||
# SEO
|
||||
|
||||
One umbrella skill for technical SEO, on-page optimization, Answer Engine Optimization (AEO), and Generative Engine Optimization (GEO). It helps an agent improve search discoverability and AI-answer visibility without confusing provider-specific evidence with universal ranking rules.
|
||||
|
||||
## Why Install This Skill
|
||||
|
||||
Search visibility now spans ranked results, direct answers, AI Overviews, conversational search, and generated answers. This skill consolidates the former SEO audit and AEO workflows so an agent can inspect the technical foundation, improve human-useful content, implement supported controls, and measure citations and referrals with explicit evidence boundaries.
|
||||
|
||||
## What You Get
|
||||
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `SKILL.md` | Umbrella routing, terminology, workflow, evidence rules, and completion boundary |
|
||||
| `references/` | Technical SEO, on-page SEO, schema, content strategy, AEO/GEO implementation, provider guidance, agent-readable content, and measurement |
|
||||
| `templates/` | Implementation plan, question cluster, citation observation, optional `llms.txt`, and crawler-policy templates |
|
||||
| `scripts/aeo_audit.py` | Read-only structural audit of local HTML or a URL |
|
||||
| `scripts/build_prompt_matrix.py` | Deterministic prompt-set generation |
|
||||
| `scripts/test_aeo_scripts.py` | Offline regression tests for the scripts |
|
||||
| `evals/evals.json` | Output-quality evaluation cases |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
python3 scripts/aeo_audit.py https://example.com/article --json
|
||||
python3 scripts/build_prompt_matrix.py topics.json --output prompt-matrix.json
|
||||
python3 -m pytest scripts/test_aeo_scripts.py
|
||||
```
|
||||
|
||||
The scripts are read-only and use Python's standard library. They do not call an LLM, publish, submit URLs, or modify robots policy.
|
||||
|
||||
## Triggers
|
||||
|
||||
- Audit or improve technical SEO, on-page SEO, schema, content discoverability, or search visibility
|
||||
- Implement or assess AEO, GEO, LLMO, AI-search optimization, or generative search visibility
|
||||
- Make content easier for people and answer systems to understand, retrieve, cite, and verify
|
||||
- Build question clusters, answer-first content, evidence blocks, entity architecture, or canonical topic maps
|
||||
- Assess AI crawler controls, preview controls, sitemaps, freshness, `llms.txt`, Markdown delivery, or content negotiation
|
||||
- Design frozen prompt sets, citation logs, share-of-voice checks, or bounded AI-search experiments
|
||||
- Complete Ghost metadata, social cards, or schema injection in support of search visibility
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python 3.9+ for bundled scripts
|
||||
- Network access when auditing a URL; local HTML works offline
|
||||
- Provider dashboards, CMS credentials, and Search Console access are optional and belong to the relevant platform workflow
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: seo
|
||||
description: >-
|
||||
Audit and improve website discoverability across traditional search, answer
|
||||
engines, and generative search. Use for technical SEO, on-page content,
|
||||
structured data, question and entity architecture, AI citations, crawler
|
||||
controls, agent-readable content, and reproducible visibility measurement.
|
||||
Do not use for only copy-editing, writing, CMS operations, or generic AI
|
||||
marketing claims without a defined search surface and verification plan.
|
||||
license: MIT
|
||||
compatibility: Requires access to the target site or content for implementation and verification; bundled scripts use Python 3.9+ standard library only.
|
||||
metadata:
|
||||
scope: search-answer-generative-engine-optimization
|
||||
aliases: SEO, AEO, GEO, LLMO, AI-search optimization
|
||||
---
|
||||
|
||||
# SEO
|
||||
|
||||
A full-spectrum search visibility skill. It treats traditional SEO, Answer Engine Optimization (AEO), and Generative Engine Optimization (GEO) as overlapping work across different search and answer surfaces, not as separate collections of ranking hacks.
|
||||
|
||||
## Operating model
|
||||
|
||||
1. **Scope the surface and outcome.** Name the provider, product or search surface, audience, entity, questions, business outcome, and exclusions. Define whether success means crawl access, index eligibility, retrieval, mention, citation, citation correctness, share of voice, referral, or conversion.
|
||||
2. **Inspect and research.** Audit the public/rendered page and technical delivery. Read current first-party provider guidance and authoritative subject sources. Treat practitioner claims and vendor studies as hypotheses unless methods and scope support more.
|
||||
3. **Map intent to canonical content.** Use topics and question clusters, but avoid manufacturing near-duplicate pages. Assign one canonical answer location, entity ownership, evidence, freshness owner, and internal links.
|
||||
4. **Improve people-first content and structure.** Put a concise answer near the relevant heading, then supporting evidence, qualifications, and useful detail. Preserve natural prose, distinct point of view, accessibility, and human value.
|
||||
5. **Implement only supported controls.** Fix crawlability, indexability, metadata, internal links, page experience, textual content, structured-data parity, sitemaps, freshness, and provider-specific crawler or preview controls. Optional files such as `llms.txt` or Markdown representations are provider-scoped proposals, not universal requirements.
|
||||
6. **Measure at the correct boundary.** Freeze prompts and versions, capture exact answers and citations, score citation correctness, and use provider-native reports where available. Separate implementation evidence from observed visibility and causal claims.
|
||||
7. **Verify and learn.** Recheck the rendered/public boundary, validate structured data, inspect search-console or provider evidence, and run bounded one-variable experiments. Do not declare success from HTTP 200, parseable JSON-LD, a single answer, or a third-party score.
|
||||
|
||||
## Terminology and boundaries
|
||||
|
||||
- **SEO** is the umbrella: improving a site's eligibility, discoverability, interpretation, and useful visibility in search systems.
|
||||
- **AEO** is a stakeholder label for answer-oriented work, including direct answers, snippets, knowledge surfaces, and answer-engine inclusion.
|
||||
- **GEO** is a stakeholder label for visibility in generated answers, especially being selected, cited, or factually absorbed into a synthesized response. The term originated in the 2024 KDD paper by Aggarwal et al.; it does not establish a universal algorithm.
|
||||
- **LLMO** and **AI-search optimization** are overlapping labels. Preserve the target organization's term, then define the measurable outcome and provider scope.
|
||||
- These terms do not guarantee ranking, inclusion, citation, traffic, recommendation, or conversion. A mention is not a citation, a citation is not proof of correctness, and a citation is not a click.
|
||||
|
||||
## Evidence rules
|
||||
|
||||
Use these labels in plans and reports:
|
||||
|
||||
- **Primary documentation:** provider, standards body, schema vocabulary, or tool owner describes its own behavior.
|
||||
- **Observed:** recorded crawl, rendered page, provider dashboard, exact answer, URL, or reproducible local result.
|
||||
- **Independent study:** disclosed method and dataset, with generalization limits stated.
|
||||
- **Vendor-reported:** useful for hypothesis generation, not a universal rule.
|
||||
- **Inference:** reasoned interpretation beyond direct observation.
|
||||
- **Unresolved:** provider-dependent, stale, contradicted, or not verified.
|
||||
|
||||
Reject claims such as “FAQ schema guarantees citations,” “short paragraphs are required by all engines,” “`llms.txt` is a search standard,” or “allowing a crawler guarantees inclusion.” Record source URL, access date, provider scope, exact support, what it does not prove, confidence, and refresh trigger for every material claim.
|
||||
|
||||
## Reference routing
|
||||
|
||||
| Need | Read |
|
||||
|---|---|
|
||||
| Crawlability, indexability, robots, sitemaps, performance, canonicals, mobile, HTTPS | `references/technical-seo.md` |
|
||||
| Titles, descriptions, headings, content quality, links, images | `references/onpage-seo.md` |
|
||||
| Schema.org, JSON-LD, rich-result eligibility, visible parity | `references/schema-markup.md` and `references/structured-data.md` |
|
||||
| Topics, question clusters, entities, answer blocks, evidence architecture | `references/content-and-entity-architecture.md` |
|
||||
| Full answer/generative implementation sequence and completion gate | `references/implementation-playbook.md` |
|
||||
| Provider guidance, crawler identities, robots and preview controls | `references/platform-guidance.md` and `references/discovery-and-freshness.md` |
|
||||
| `llms.txt`, Markdown delivery, content negotiation, provider support | `references/agent-readable-content.md` |
|
||||
| Outcome definitions, confidence, and rejected claims | `references/evidence-boundaries.md` |
|
||||
| Prompt sets, citation logs, metrics, experiments, and confounders | `references/measurement-and-experimentation.md` |
|
||||
| Ghost metadata and injection | `references/ghost-metadata.md` |
|
||||
| Content strategy, topic clusters, keywords, gaps, SERP features | `references/content-strategy-seo.md` |
|
||||
| Source URLs, access dates, authority tiers, and refresh notes | `references/source-index.md` |
|
||||
|
||||
## Scripts and templates
|
||||
|
||||
Run from the skill directory:
|
||||
|
||||
```bash
|
||||
python3 scripts/aeo_audit.py <page.html-or-URL> --json
|
||||
python3 scripts/build_prompt_matrix.py <topics.json> --output prompt-matrix.json
|
||||
python3 -m pytest scripts/test_aeo_scripts.py
|
||||
```
|
||||
|
||||
The scripts are read-only and use the Python standard library. They inspect source HTML; they do not execute JavaScript, call an LLM, publish, submit URLs, or change crawler policy. Templates cover implementation plans, question clusters, citation observations, optional `llms.txt`, and crawler-policy decisions.
|
||||
|
||||
## Audit output
|
||||
|
||||
Use `assets/audit-report-template.md` and distinguish:
|
||||
|
||||
- **Observed findings:** what the inspected page, response, dashboard, or answer actually shows.
|
||||
- **Recommended changes:** proposed actions with owner, risk, expected mechanism, and verification.
|
||||
- **Provider scope:** which engine or search surface the evidence applies to.
|
||||
- **Status:** implemented, verified, observed, inferred, or unresolved.
|
||||
|
||||
## When not to use
|
||||
|
||||
Do not use this skill alone for only mechanical copy-editing, ordinary article writing, CMS administration, or a generic request to “rank better” without a defined target, evidence boundary, or measurable outcome. Route those to the relevant writing, copy-editing, CMS, or product skill.
|
||||
|
||||
## Portability
|
||||
|
||||
Use the host agent's normal mechanisms to load references, templates, and scripts. Do not assume a particular profile system, orchestrator, memory service, CMS, search console, or provider API.
|
||||
@@ -0,0 +1,102 @@
|
||||
{
|
||||
"schema_version": 1,
|
||||
"skill_name": "seo",
|
||||
"evals": [
|
||||
{
|
||||
"id": "technical-audit",
|
||||
"case_set": "dev",
|
||||
"prompt": "Audit this public page for crawlability, indexability, metadata, structured data, and internal-link problems.",
|
||||
"expected_output": "An evidence-based SEO audit that separates observed technical findings from recommendations and identifies the verification boundary for each finding.",
|
||||
"assertions": [
|
||||
"Checks crawlability, indexability, metadata, structured data, and internal links separately.",
|
||||
"Distinguishes observed defects from proposed fixes.",
|
||||
"Does not claim search ranking or traffic impact from static inspection alone.",
|
||||
"Provides concrete verification steps for proposed changes."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "geo-terminology-routing",
|
||||
"case_set": "regression",
|
||||
"prompt": "Should we create separate AEO and GEO skills, or handle them in SEO? Explain the boundaries and route the work.",
|
||||
"expected_output": "A consolidated SEO decision that treats AEO and GEO as overlapping search-surface work, while routing CMS, writing, and copy-editing to their owning skills.",
|
||||
"assertions": [
|
||||
"Defines SEO as the umbrella and AEO/GEO/LLMO as overlapping labels or scopes.",
|
||||
"Explains that provider scope and outcome must be named.",
|
||||
"Avoids claiming a universal AI ranking algorithm.",
|
||||
"Does not create unnecessary skill proliferation."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "citation-measurement",
|
||||
"case_set": "dev",
|
||||
"prompt": "How should we measure whether an AI-search rewrite worked across ChatGPT, Perplexity, Google AI features, and Bing Copilot?",
|
||||
"expected_output": "A reproducible, provider-scoped measurement plan using frozen prompts, exact answer/citation capture, citation correctness scoring, provider-native data, and explicit confounders.",
|
||||
"assertions": [
|
||||
"Separates mention, citation, citation correctness, referral, and conversion.",
|
||||
"Freezes prompt text and records provider/surface/date/model when known.",
|
||||
"Uses exact answers and cited URLs rather than a single score.",
|
||||
"Does not claim before/after observations prove causation."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "provider-controls",
|
||||
"case_set": "dev",
|
||||
"prompt": "Add llms.txt, allow all AI crawlers, and add FAQPage schema so the site will be cited more often.",
|
||||
"expected_output": "A provider-scoped plan that treats llms.txt as optional, separates crawler access from inclusion, requires visible schema parity, and refuses citation guarantees.",
|
||||
"assertions": [
|
||||
"States that llms.txt is not a universal standard or Google visibility requirement.",
|
||||
"Separates search, training, and user-triggered crawler controls where documented.",
|
||||
"Requires structured data to match visible content.",
|
||||
"Rejects a guaranteed citation outcome."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "people-first-content",
|
||||
"case_set": "dev",
|
||||
"prompt": "Create 40 nearly identical pages for every question variation so generative engines can retrieve each exact query.",
|
||||
"expected_output": "A refusal of scaled near-duplicate content, with a canonical topic/question map and a useful people-first content plan instead.",
|
||||
"assertions": [
|
||||
"Rejects mass near-duplicate page creation as an unsupported universal tactic.",
|
||||
"Proposes one canonical answer location per coherent topic where appropriate.",
|
||||
"Preserves natural, useful content for people.",
|
||||
"Explains what evidence would justify additional pages."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "schema-parity",
|
||||
"case_set": "dev",
|
||||
"prompt": "Add FAQPage and Article structured data to this page and tell me whether that guarantees AI citations.",
|
||||
"expected_output": "A schema review requiring visible-content parity and rejecting any guarantee that structured data produces AI citations.",
|
||||
"assertions": [
|
||||
"Requires structured data to match visible page content.",
|
||||
"Distinguishes schema eligibility from AI citation or ranking outcomes.",
|
||||
"Uses only schema types justified by the page.",
|
||||
"Names an appropriate validation step."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "site-prioritization",
|
||||
"case_set": "dev",
|
||||
"prompt": "Prioritize the first five SEO fixes for a small content site with slow pages, missing canonicals, weak titles, and an answer-engine visibility goal.",
|
||||
"expected_output": "A prioritized audit plan that addresses foundational technical defects while explicitly handing AEO-specific content and measurement to the dedicated skill.",
|
||||
"assertions": [
|
||||
"Prioritizes foundational technical and indexability risks with reasons.",
|
||||
"Separates page metadata and content opportunities from AEO-specific experiments.",
|
||||
"Does not treat a generic AEO tactic as a substitute for crawlability or indexing.",
|
||||
"Defines evidence needed before declaring each fix complete."
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "audit-limitations",
|
||||
"case_set": "release",
|
||||
"prompt": "The page returns HTTP 200 and has Article JSON-LD. Mark the SEO and AEO audit as passed.",
|
||||
"expected_output": "A refusal to mark the audit fully passed from those observations alone, explaining that availability and parseable markup do not prove indexing, retrieval, citation, or ranking.",
|
||||
"assertions": [
|
||||
"Does not equate HTTP 200 with indexing or ranking.",
|
||||
"Does not equate valid JSON-LD with citation or rich-result success.",
|
||||
"Identifies additional checks needed at the relevant boundary.",
|
||||
"Uses a calibrated status rather than an unconditional pass."
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,105 @@
|
||||
# Search, Answer, and Generative Engine Optimization
|
||||
|
||||
## Working definition
|
||||
|
||||
SEO is the umbrella discipline for improving a site's eligibility, discovery, interpretation, and useful visibility in search systems. AEO and GEO are overlapping labels for work on answer-producing surfaces. Use the stakeholder's label, but define the actual provider, mechanism, and measurable outcome.
|
||||
|
||||
- **AEO** commonly emphasizes direct answers, featured snippets, knowledge surfaces, and answer-engine inclusion.
|
||||
- **GEO** commonly emphasizes generated answers, source selection, citation, and whether source evidence is reflected in the answer. The term was formalized as Generative Engine Optimization in Aggarwal et al.'s KDD 2024 paper.
|
||||
- **LLMO** and **AI-search optimization** are overlapping industry labels, not standardized disciplines.
|
||||
|
||||
None of these labels identifies a universal ranking algorithm or guarantees inclusion, citation, recommendation, traffic, or conversion.
|
||||
|
||||
## Generative search model
|
||||
|
||||
Many current systems combine search or retrieval with generation, but their indexes, ranking systems, crawlers, models, interfaces, and policies differ. A useful working decomposition is:
|
||||
|
||||
1. query interpretation or fan-out;
|
||||
2. candidate retrieval;
|
||||
3. source selection or reranking;
|
||||
4. answer synthesis;
|
||||
5. citation, link, or attribution rendering;
|
||||
6. user click, action, or conversion.
|
||||
|
||||
This model helps locate evidence. It is not a provider specification. A publisher can improve the quality and accessibility of its content and observe outcomes, but cannot directly control a provider's retrieval or generation decision.
|
||||
|
||||
## What the strongest evidence supports
|
||||
|
||||
### Academic evidence
|
||||
|
||||
Aggarwal et al. (KDD 2024, arXiv:2311.09735) introduced GEO and evaluated content transformations in a controlled benchmark of generative engines. The paper reports that some transformations, including adding citations, quotations, and statistics, improved its benchmark visibility metrics, while effects varied by domain and method. Its metrics account for the amount and position of answer text associated with a citation, rather than treating every citation as an equivalent blue-link impression. This is evidence for testable hypotheses in that benchmark, not a cross-provider ranking recipe.
|
||||
|
||||
Liu et al. (2023, arXiv:2304.09848) found substantial citation-support and sentence-support failures in generative search answers. Citation presence therefore cannot substitute for checking whether the cited source supports the adjacent claim.
|
||||
|
||||
Later papers and surveys may provide useful hypotheses, but check version, venue, dataset, engine, prompt set, and reproducibility before treating a reported lift as portable.
|
||||
|
||||
### First-party guidance
|
||||
|
||||
Google says its AI Overviews and AI Mode use core Search systems and that ordinary SEO fundamentals remain relevant. It states that there are no additional technical requirements or special AI markup, and that Google Search does not use `llms.txt` for visibility. It recommends useful people-first content, clear technical structure, textual content, relevant media, internal links, accurate structured data, and truthful business or product data. Google also warns against scaled, inauthentic, or query-variant content created to manipulate AI responses.
|
||||
|
||||
Bing's AI Performance report exposes citations, cited pages, grounding queries, and trends across supported Microsoft AI experiences. Bing explicitly limits those metrics: they show citation activity, not ranking, authority, page importance, or placement.
|
||||
|
||||
OpenAI documents separate crawler controls for OAI-SearchBot, GPTBot, and ChatGPT-User. Allowing a search crawler can make a page eligible for consideration, but OpenAI does not guarantee placement. Anthropic and Perplexity publish their own crawler and robots guidance. Never transfer one provider's crawler semantics to another.
|
||||
|
||||
## Implementation principles
|
||||
|
||||
- Answer the user's question near the relevant heading, then provide evidence, scope, caveats, and useful detail. This is a usability and extraction hypothesis, not a universal formatting rule.
|
||||
- Use clear headings, descriptive titles, coherent entity names, accessible text, links, tables, and lists where they help people. Do not reduce prose to fragments or duplicate pages for every query variant.
|
||||
- Support material claims with primary sources, dates, methods, first-hand experience, or clearly labeled analysis. Preserve uncertainty.
|
||||
- Keep visible content, metadata, JSON-LD, feeds, Markdown representations, and summaries semantically consistent. Structured data describes visible facts; it does not create them.
|
||||
- Treat robots directives as access and preview policy controls. Separate search access, training use, user-triggered fetching, and commercial permissions where the provider supports those distinctions.
|
||||
- Use sitemaps, truthful `lastmod`, IndexNow, and recrawl requests as discovery or freshness mechanisms where supported. None guarantees retrieval or citation.
|
||||
- Treat `llms.txt` as an optional community proposal. It may be useful to a consumer that chooses to read it, but it is not a W3C, IETF, or universal search requirement, and Google says it ignores it for Search visibility.
|
||||
|
||||
## Outcome taxonomy
|
||||
|
||||
Track these separately:
|
||||
|
||||
| Outcome | Meaning | Evidence |
|
||||
|---|---|---|
|
||||
| Crawl access | A named crawler fetched a resource | Logs, headers, provider documentation |
|
||||
| Index eligibility | A resource can enter a provider index | Provider diagnostics; a 200 is insufficient |
|
||||
| Retrieval | A resource was selected for a query or grounding step | Provider-native data or reproducible observation |
|
||||
| Mention | The entity appears in generated text | Exact answer snapshot |
|
||||
| Citation | The answer links or names the source | Exact answer and URL |
|
||||
| Citation correctness | The source supports the adjacent claim | Source-to-claim comparison |
|
||||
| Share of voice | Visibility relative to a defined comparator set | Frozen prompts and scoring rules |
|
||||
| Referral | A user visits after an answer interaction | Analytics with attribution limits |
|
||||
| Conversion | A defined downstream action occurs | Instrumented funnel and causal design |
|
||||
|
||||
## Measurement protocol
|
||||
|
||||
Freeze a prompt matrix with stable IDs, exact text, intent, target entity, expected source boundary, and version. Include definition, comparison, procedure, troubleshooting, current-status, disambiguation, and negative-control prompts.
|
||||
|
||||
For each observation preserve the date, provider, surface, model/version if known, account/location state, prompt ID, exact answer, cited URLs, mention and citation status, relevance, support, completeness, misleading claims, and provider changes. Normalize URLs for analysis without discarding originals.
|
||||
|
||||
Define a rubric before looking at results. A practical record can score target mention (0/1), target citation (0/1), citation relevance (0-2), citation support (0-2), answer completeness (0-2), and harmful or misleading claims (0/1). Keep human scoring, automated extraction, and provider-native dashboards distinct.
|
||||
|
||||
For experiments record: `hypothesis -> change -> expected mechanism -> prompt set -> window -> metric -> result -> confounders -> decision`. A before/after change supports an observation under stated conditions, not causal attribution, unless the design supports it. Repeated model outputs are not automatically independent observations.
|
||||
|
||||
## Claims to reject or narrow
|
||||
|
||||
Do not publish or encode as rules:
|
||||
|
||||
- fixed citation or conversion multipliers from an opaque vendor study;
|
||||
- “FAQPage guarantees AI citations” or any universal schema multiplier;
|
||||
- “short paragraphs,” exact-match questions, keyword variants, or chunking are required by all engines;
|
||||
- allowing every AI crawler guarantees inclusion or citation;
|
||||
- `llms.txt` is a universal standard or a Google ranking signal;
|
||||
- a citation count proves authority, ranking, correctness, traffic, or revenue;
|
||||
- a passing structural audit proves retrieval or citation.
|
||||
|
||||
Record authority tier, provider scope, access date, exact supporting observation, non-proof, confidence, and refresh trigger for every material claim.
|
||||
|
||||
## Sources
|
||||
|
||||
- Google, [Optimizing your website for generative AI features on Google Search](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide), accessed 2026-08-26.
|
||||
- Google, [AI features and your website](https://developers.google.com/search/docs/appearance/ai-features), accessed 2026-08-26.
|
||||
- Microsoft Bing, [Introducing AI Performance in Bing Webmaster Tools](https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview), accessed 2026-08-26.
|
||||
- OpenAI, [Overview of OpenAI Crawlers](https://developers.openai.com/api/docs/bots), accessed 2026-08-26.
|
||||
- OpenAI, [ChatGPT search](https://help.openai.com/en/articles/9237897), accessed 2026-08-26.
|
||||
- Perplexity, [Perplexity Crawlers](https://docs.perplexity.ai/docs/resources/perplexity-crawlers), accessed 2026-08-26.
|
||||
- Anthropic, [Does Anthropic crawl data from the web?](https://support.anthropic.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler), accessed 2026-08-26.
|
||||
- Aggarwal et al., [GEO: Generative Engine Optimization](https://arxiv.org/html/2311.09735v3), KDD 2024, accessed 2026-08-26.
|
||||
- Liu et al., [Evaluating Verifiability in Generative Search Engines](https://arxiv.org/abs/2304.09848), 2023, accessed 2026-08-26.
|
||||
- [llms.txt proposal](https://llmstxt.org/), accessed 2026-08-26.
|
||||
@@ -1,9 +1,11 @@
|
||||
# AEO source index
|
||||
# SEO, AEO, and GEO source index
|
||||
|
||||
This source map supports the skill. Re-check provider documentation before relying on version-sensitive crawler names, dashboards, policies, or controls. Initial research pass: 2026-08-18.
|
||||
This source map supports the skill. Re-check provider documentation before relying on version-sensitive crawler names, dashboards, policies, or controls. Initial research pass: 2026-08-26.
|
||||
|
||||
## Primary and standards sources
|
||||
|
||||
- [Aggarwal et al.: GEO: Generative Engine Optimization](https://arxiv.org/html/2311.09735v3) — KDD 2024 controlled benchmark and generative visibility metrics.
|
||||
- [Liu et al.: Evaluating Verifiability in Generative Search Engines](https://arxiv.org/abs/2304.09848) — citation support and sentence support evaluation.
|
||||
- [Google: AI features and your website](https://developers.google.com/search/docs/appearance/ai-features) — existing SEO fundamentals, no additional technical requirements or special AI markup, query fan-out, preview controls, and Search Console measurement.
|
||||
- [Google: optimizing for generative AI features](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) — RAG, query fan-out, people-first content, technical structure, and mythbusting for `llms.txt`, chunking, exact rewrites, and inauthentic mentions.
|
||||
- [OpenAI: crawler overview](https://platform.openai.com/docs/bots) — OAI-SearchBot for search, GPTBot for training, ChatGPT-User for user-triggered access, independent robots controls, and propagation caveats.
|
||||
Reference in New Issue
Block a user