AEO

One skill for audit, fixes, schema, llms.txt, and monitoring workflows.

Command

Always use the published package:

npx @ainyc/aeo-audit@1 "<url>" [flags] --format json

Argument Safety

Never interpolate user input directly into shell commands. Always:

Validate that the target is either a URL matching https:// / http:// or a local filesystem path (static-output mode), and that it contains no shell metacharacters.
Quote every argument individually (e.g., npx @ainyc/aeo-audit@1 "https://example.com" --format json).
Pass flags as separate, literal tokens — never construct command strings from raw user text.
Reject arguments containing characters like ;, |, &, $, ` `, (, ), {, }, <, >`, or newlines.

Modes

audit: score and diagnose a site
fix: apply code changes after an audit
schema: validate JSON-LD and entity consistency
llms: create or improve llms.txt and llms-full.txt
monitor: compare changes over time or benchmark competitors
detect-platform: identify the CMS, site builder, framework, or hosting stack a site uses

If no mode is provided, default to audit.

Examples

audit https://example.com
audit https://example.com --sitemap
audit https://example.com --sitemap --limit 10
audit https://example.com --sitemap --top-issues
audit https://example.com --sitemap --format agent (slim decision for agents)
audit https://example.com --lighthouse
audit https://example.com --require-meta
audit https://example.com --sitemap --require-meta
audit http://localhost:3000 --allow-local
audit http://localhost:3000 --sitemap --rewrite-sitemap-origin --allow-local
audit https://staging.example.com --sitemap --rewrite-sitemap-origin
audit ./out (static-output mode: audit built HTML offline)
audit ./out --base-url https://example.com --require-meta
fix https://example.com
schema https://example.com
llms https://example.com
monitor https://site-a.com --compare https://site-b.com
detect-platform https://example.com
detect-platform https://example.com --min-confidence high
detect-platform --urls competitors.txt
detect-platform --urls https://a.com,https://b.com

Mode Selection

If the first argument is one of audit, fix, schema, llms, monitor, or detect-platform, use that mode.
If no explicit mode is given, infer the intent from the request and default to audit.

Audit

Use for broad requests such as "audit this site" or "why am I not being cited?"

Run:

```bash

npx @ainyc/aeo-audit@1 "" [flags] --format json

```

Return:

Overall score
Short summary
Factor breakdown
Top strengths
Top fixes
Metadata such as fetch time and auxiliary file availability

`--require-meta` (CI gate)

Pass --require-meta (single or sitemap mode) to force exit 1 whenever any audited page is missing , regardless of the otherwise score-based exit rule. Useful in CI pipelines that need to block deploys on a missing meta description even on otherwise-healthy sites.

Sitemap Mode

Use --sitemap to audit all pages discovered from the site's sitemap:

npx @ainyc/aeo-audit@1 "<url>" --sitemap --format json
npx @ainyc/aeo-audit@1 "<url>" --sitemap https://example.com/sitemap.xml --format json
npx @ainyc/aeo-audit@1 "<url>" --sitemap --limit 10 --format json
npx @ainyc/aeo-audit@1 "<url>" --sitemap --top-issues --format json

Flags:

--sitemap [url] — auto-discover the sitemap (tries /sitemap.xml, then /sitemap-index.xml, then Sitemap: directives in /robots.txt) or provide an explicit URL
--limit — cap pages audited (default 200, sorted by sitemap priority)
--top-issues — skip per-page output, show only cross-cutting patterns and critical defects
--rewrite-sitemap-origin — rewrite every 's origin to the target URL's origin (preserving path/query) before crawling. Use when the sitemap hardcodes the prod/canonical domain but you want to audit a staging host or local dev server.
--require-meta — force exit 1 if any audited page is missing , regardless of overall score (useful as a CI gate)
--include-geo / --include-agent-skills — honored per page in sitemap mode (adds the optional geographic-signals / agent-skill-exposure factors). --lighthouse is not available with --sitemap.

Pages are audited with bounded concurrency (5 in flight) to avoid hammering the target origin.

Returns:

Per-page scores
Critical defects — binary, one-line-fix structural defects (an
count other than one, a missing </code>, a missing meta description) surfaced <strong>regardless of how few pages they affect</strong>, with the offending pages named (homepage and high sitemap-<code>priority</code> pages first). These would otherwise be averaged into a passing factor score; the JSON field is <code>criticalDefects</code> and critical-severity ones are also promoted to the top of <code>prioritizedFixes</code>. Shown even with <code>--top-issues</code>.</li><li>Cross-cutting issues (factors failing across multiple pages), each with the best-scoring page (<code>bestScore</code>/<code>bestPageUrl</code>) and a <code>status</code>: <code>sitewide</code> (a real coverage gap) vs. <code>limited</code>/<code>opportunity</code> for page-specific factors (FAQ, definitions) that legitimately apply to only some page types</li><li>Aggregate score</li><li>Prioritized fixes (critical defects first, then site-wide gaps; page-specific <code>limited</code>/<code>opportunity</code> factors demoted below them, scoped to the page(s) that carry them)</li></ul><h4>Machine-readable output (for agents)</h4><p>Use <code>--format json</code> for the full report, or <strong><code>--format agent</code></strong> for just the decision: <code>{ schemaVersion, tool, mode, url, score, pass, criticalDefectCount, issues }</code>, where <code>issues</code> is the ranked <code>prioritizedFixes</code> and the per-factor/per-page detail is omitted. Prefer <code>--format agent</code> when you only need to decide and act. Key fields for acting on the result without parsing prose:</p><ul><li><code>schemaVersion</code> (on every audit report) versions the JSON shape independently of the package version — pin to it and treat a major bump as breaking; absence means a pre-2.0 report.</li><li><code>prioritizedFixes</code> is a ranked array of objects, each with a stable <code>id</code>, <code>kind</code>, optional <code>severity</code>, the complete <code>affectedPages</code> list (never truncated), <code>affectsHomepage</code>, <code>prevalencePct</code>, and a human <code>summary</code>. Cross-cutting fixes also carry <code>avgScore</code>, <code>bestScore</code>/<code>bestPageUrl</code>, and a <code>status</code> (<code>sitewide</code> | <code>limited</code> | <code>opportunity</code>) — treat <code>limited</code>/<code>opportunity</code> as page-specific tune-ups, not site-wide failures. It's the pre-computed to-do list — no need to re-rank factor scores yourself.</li><li>Stable identifiers everywhere — <code>criticalDefects[].id</code>, <code>prioritizedFixes[].id</code>, and every factor finding's <code>code</code> (e.g. <code>technical-seo.h1.multiple</code>) — let integrations key on codes rather than message strings.</li></ul><h4>Auxiliary File Diagnostics</h4><p>When the audit fetches <code>/llms.txt</code>, <code>/llms-full.txt</code>, <code>/robots.txt</code>, and <code>/sitemap.xml</code>, it probes once with <code>Accept: text/markdown</code> to detect a <strong>content-negotiation</strong> trap: file responds OK to a bare request but returns a non-2xx response when the client prefers markdown. This catches Astro / Vercel / Starlight setups that 307-redirect <code>.txt</code> → non-existent <code>.md</code> for markdown-accepting clients, making the file invisible to AI content-extraction tools even though the file exists. The diagnostic surfaces as a finding on the <strong>AI Access Files (llms.txt, sitemap)</strong> factor.</p><h3>Local Dev / Staging Targets</h3><p>By default the audit blocks any URL that resolves to a private, loopback, or link-local address (SSRF protection). When the user wants to audit <strong>their own</strong> dev or staging server, pass <code>--allow-local</code> (alias <code>--allow-private</code>):</p><pre><code>npx @ainyc/aeo-audit@1 "http://localhost:3000" --allow-local --format json npx @ainyc/aeo-audit@1 "http://10.0.5.20" --allow-private --format json </code></pre><ul><li>Pass the explicit <code>http://</code> scheme for local dev servers — a bare host defaults to <code>https://</code>.</li><li>The relaxation is scoped to the <strong>single host named on the CLI</strong>, evaluated per hop. A redirect or sitemap <code><loc></code> pointing at any other private host (e.g. <code>169.254.169.254</code>) stays blocked.</li><li>To audit a whole local site whose sitemap hardcodes the prod domain, combine with sitemap origin rewriting:</li></ul><pre><code>npx @ainyc/aeo-audit@1 "http://localhost:3000" --sitemap --rewrite-sitemap-origin --allow-local --format json </code></pre><h3>Static-Output Mode</h3><p>When the user wants to audit <strong>built HTML offline</strong> (CI on a <code>next export</code> / <code>dist</code> / <code>out</code> directory, or before deploying), pass a filesystem path instead of a URL:</p><pre><code># A directory of built HTML (aggregated like sitemap mode) npx @ainyc/aeo-audit@1 "./out" --base-url https://example.com --format json # A single built file npx @ainyc/aeo-audit@1 "./dist/index.html" --format json # Gate CI on missing meta descriptions across the build npx @ainyc/aeo-audit@1 "./out" --require-meta --format json </code></pre><ul><li>A <code>.html</code>/<code>.htm</code> file → single-page report; a directory → aggregated report (<code>--limit</code>, <code>--top-issues</code>, <code>--factors</code>, <code>--include-geo</code>, <code>--include-agent-skills</code>, <code>--require-meta</code> apply).</li><li><code>--base-url <url></code> maps files to page URLs (<code>out/about/index.html</code> → <code><base>/about/</code>; default <code>https://localhost</code>). <code>index.html</code> collapses to its directory URL; other files drop the <code>.html</code> extension.</li><li><code>llms.txt</code>, <code>llms-full.txt</code>, <code>robots.txt</code>, and <code>sitemap.xml</code> are read from the directory root when present.</li><li><strong>Partial coverage:</strong> server-only signals (redirects, <code>X-Robots-Tag</code>, <code>Last-Modified</code>, <code>Link</code> headers) aren't visible from static files. Recommend auditing the deployed URL for full coverage.</li></ul><h3>Lighthouse Mode</h3><p>Use <code>--lighthouse</code> when the user wants page speed, accessibility, or best-practices scoring alongside the AEO factors. It calls Google PageSpeed Insights (mobile strategy) and aggregates Performance + Accessibility + Best Practices into a single optional factor (weight 8).</p><pre><code>npx @ainyc/aeo-audit@1 "<url>" --lighthouse --format json PAGESPEED_API_KEY=xxx npx @ainyc/aeo-audit@1 "<url>" --lighthouse --format json </code></pre><p>Constraints:</p><ul><li>Single-URL only — cannot combine with <code>--sitemap</code> or <code>--detect-platform</code>. Each Lighthouse audit takes 15-30s, which would blow up sitemap runtime.</li><li>Optional <code>PAGESPEED_API_KEY</code> env var lifts anonymous PSI rate limits (25k/day unauthenticated).</li><li>On PSI failure (unreachable target, timeout, HTTP error) the factor scores 0 and surfaces a <code>timeout</code> or <code>unreachable</code> finding rather than throwing — the rest of the audit still runs.</li></ul><h3>Detect Platform Mode</h3><p>Use <code>--detect-platform</code> when the user wants to know what stack a site is built on (e.g., "is this WordPress?", "what framework does competitor X use?", "is this site custom-built?"). This is much faster than a full audit because it skips analyzer scoring.</p><pre><code>npx @ainyc/aeo-audit@1 "<url>" --detect-platform --format json npx @ainyc/aeo-audit@1 "<url>" --detect-platform --min-confidence high --format json </code></pre><p>Flags:</p><ul><li><code>--detect-platform</code> — switch to detection mode instead of auditing</li><li><code>--min-confidence <lvl></code> — filter to <code>low</code> (default), <code>medium</code>, or <code>high</code> confidence</li><li><code>--urls <src></code> — run on multiple URLs at once (file path, comma-separated list, or <code>-</code> for stdin)</li><li><code>--concurrency <n></code> — max in-flight fetches in batch mode (default 5)</li></ul><p>The report groups detections by category (CMS, site builder, e-commerce, framework, SSG, hosting), each with a confidence bucket, a 0–100 score, an optional version, and the signals that matched. When the report's <code>isCustom</code> flag is true, no CMS/site-builder/e-commerce platform was identified — the site is likely custom-built. Exit code is <code>0</code> when at least one platform is detected, <code>1</code> otherwise.</p><h4>Batch detection</h4><p>When the user wants to fingerprint many sites at once (competitor lists, customer cohorts), pass <code>--urls</code>:</p><pre><code>npx @ainyc/aeo-audit@1 --detect-platform --urls urls.txt --format json npx @ainyc/aeo-audit@1 --detect-platform --urls https://a.com,https://b.com --format json cat urls.txt | npx @ainyc/aeo-audit@1 --detect-platform --urls - --format json </code></pre><p>The batch report contains a <code>results</code> array; each entry has <code>status: 'success'</code> or <code>'error'</code>, plus the same shape as a single-URL report on success. Per-URL fetch errors do not abort the run. Exit code is <code>0</code> when at least one URL succeeded, <code>1</code> otherwise.</p><h2>Fix</h2><p>Use when the user wants code changes applied after the audit.</p><ol><li>Run:</li></ol><p> ```bash</p><p> npx @ainyc/aeo-audit@1 "<url>" [flags] --format json</p><p> ```</p><ol><li>Find factors scoring below 70 (lowest first).</li><li>Apply targeted fixes in the current codebase.</li><li>Prioritize:</li><ul><li>Structured data and schema completeness</li><li><code>llms.txt</code> and <code>llms-full.txt</code></li><li><code>robots.txt</code> crawler access</li><li>E-E-A-T signals</li><li>FAQ markup</li><li>freshness metadata</li><li>agent-readiness signals: per-page Markdown source endpoints, <code>robots.txt</code> <code>Content-Signal</code> directives, and A2A agent cards (aligned with specification.website)</li></ul><li>Re-run the audit and report the score delta.</li></ol><p>Rules:</p><ul><li>Always explain proposed changes and get user confirmation before editing files.</li><li>Do not remove existing schema or content unless the user asks.</li><li>Preserve existing code style and patterns.</li><li>If a fix is ambiguous or high-risk, explain the tradeoff before editing.</li></ul><h2>Schema</h2><p>Use when the request is specifically about JSON-LD or schema quality.</p><p>Validity issues like duplicate singleton <code>@type</code>s and JSON parse errors are <strong>per page</strong>, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests ("audit my schema", "are my FAQ blocks valid?"); use single-URL mode only when the user names one specific page.</p><p>Site-wide (default):</p><pre><code>npx @ainyc/aeo-audit@1 "<url>" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency </code></pre><p>Single page:</p><pre><code>npx @ainyc/aeo-audit@1 "<url>" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency </code></pre><p>Report:</p><ul><li>Schema types found</li><li>Property completeness by type</li><li>Missing recommended properties</li><li><strong>Validity errors</strong> (duplicate singleton <code>@type</code>s, JSON parse errors, empty <code><script></code> blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results</li><li>Entity consistency issues</li><li>In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates</li></ul><p>Provide corrected JSON-LD examples when useful.</p><p>Checklist:</p><ul><li><code>LocalBusiness</code>: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs</li><li><code>FAQPage</code>: mainEntity with at least 3 Q&A pairs (and only <strong>one</strong> <code>FAQPage</code> block per page — duplicates invalidate rich results)</li><li><code>HowTo</code>: name and at least 3 steps (singleton — only one per page)</li><li><code>Organization</code>: name, logo, contactPoint, sameAs, foundingDate, url, description</li><li>Singletons that must not repeat per page: <code>FAQPage</code>, <code>HowTo</code>, <code>Article</code>, <code>BlogPosting</code>, <code>NewsArticle</code>, <code>BreadcrumbList</code>, <code>Product</code>, <code>Recipe</code></li></ul><h2>llms.txt</h2><p>Use when the user wants <code>llms.txt</code> or <code>llms-full.txt</code> created or improved.</p><p>If a URL is provided:</p><ol><li>Run:</li></ol><p> ```bash</p><p> npx @ainyc/aeo-audit@1 "<url>" [flags] --format json --factors ai-access-files</p><p> ```</p><ol><li>Inspect existing AI-readable files if present.</li><li>Extract key content from the site.</li><li>Generate improved <code>llms.txt</code> and <code>llms-full.txt</code>.</li></ol><p>If no URL is provided:</p><ol><li>Inspect the current project.</li><li>Extract business name, services, FAQs, contact info, and metadata.</li><li>Generate both files from local sources.</li></ol><p>After generation:</p><ul><li>Add <code><link rel="alternate" type="text/markdown" href="/llms.txt"></code> when appropriate.</li><li>Expose per-page Markdown source endpoints (a <code>.md</code> URL or content negotiation) advertised via <code><link rel="alternate" type="text/markdown"></code> — a scored AI-readable signal.</li><li>Suggest adding the files to the sitemap.</li></ul><h2>Monitor</h2><p>Use when the user wants progress tracking or a competitor comparison.</p><p>Single URL:</p><ol><li>Run the audit.</li><li>Compare against prior results in <code>.aeo-audit-history/</code> if present.</li><li>Show overall and per-factor deltas.</li><li>Save the current result.</li></ol><p>Comparison mode:</p><ol><li>Parse <code>--compare <url2></code>.</li><li>Audit both URLs.</li><li>Show side-by-side factor deltas.</li><li>Highlight advantages, weaknesses, and priority gaps.</li></ol><h2>Behavior</h2><ul><li>If the task needs a deployed site and no URL is provided, ask for the URL.</li><li>If the task is diagnosis only, do not edit files.</li><li>If the task is a fix request, make edits and verify with a rerun when possible.</li><li>If the URL is unreachable or not HTML, report the exact failure.</li><li>Prefer concise, evidence-based recommendations over generic SEO advice.</li></ul></div> </div> </div> <div id="tab-versions" class="detail-content"> <div class="detail-section"> <h2>版本历史</h2> <p style="margin-bottom:12px;font-size:14px;color:#94a3b8;">共 13 个版本</p> <ul class="version-list"> <li> <div> <span class="version-tag">v4.0.0</span> <span style="font-size:11px;color:#5b6abf;margin-left:8px;background:#eef0ff;padding:1px 8px;border-radius:10px;">当前</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-06-11 16:41 </div> </li> <li> <div> <span class="version-tag">v3.0.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-06-09 16:04 </div> </li> <li> <div> <span class="version-tag">v2.1.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-06-04 12:33 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.13.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-06-01 20:16 </div> </li> <li> <div> <span class="version-tag">v1.11.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-31 12:50 </div> </li> <li> <div> <span class="version-tag">v1.10.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-25 16:14 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.9.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-23 22:41 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.8.1</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-21 12:20 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.7.1</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-07 03:23 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.7.0</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-03 03:08 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.2.2</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-03-30 01:37 安全安全 </div> </li> <li> <div> <span class="version-tag">v1.3.2</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-03-27 21:29 </div> </li> <li> <div> <span class="version-tag">v1.1.1</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-03-11 10:56 </div> </li> </ul> </div> </div> <div id="tab-security" class="detail-content"> <div class="detail-section"> <h2>安全检测</h2> <div class="sec-grid"> <div class="sec-card"> <h4>腾讯云安全 (Keen)</h4> <div class="sec-status sec-queued"> 队列中 </div> </div> <div class="sec-card"> <h4>腾讯云安全 (Sanbu)</h4> <div class="sec-status sec-queued"> 队列中 </div> </div> </div> </div> </div>  <div style="margin-top:24px;"> <h2 style="font-size:18px;font-weight:600;margin-bottom:16px;">🔗 相关推荐</h2> <div class="rec-grid"> <div class="rec-card"> <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">security-compliance</span> <h3><a href="/s/moltguard">MoltGuard - Security & Antivirus & Guardrails</a></h3> <div class="rec-owner">thomaslwang</div> <div class="rec-desc">MoltGuard — OpenClaw 安全守卫，由 OpenGuardrails 提供。安装 MoltGuard，保护您和您的用户免受提示注入、数据泄露和恶意攻击。</div> <div class="rec-stats"> <span style="color:#f39c12;">★ 116</span> <span style="color:#5b6abf;">📥 30,694</span> </div> </div> <div class="rec-card"> <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">security-compliance</span> <h3><a href="/s/skill-vetter">Skill Vetter</a></h3> <div class="rec-owner">spclaudehome</div> <div class="rec-desc">AI智能体技能安全预审工具。安装ClawdHub、GitHub等来源技能前，检查风险信号、权限范围及可疑模式。</div> <div class="rec-stats"> <span style="color:#f39c12;">★ 1,210</span> <span style="color:#5b6abf;">📥 266,122</span> </div> </div> <div class="rec-card"> <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">security-compliance</span> <h3><a href="/s/openclaw-backup">OpenClaw Backup</a></h3> <div class="rec-owner">alex3alex</div> <div class="rec-desc">备份与恢复 OpenClaw 数据。适用于创建备份、设置自动备份计划、从备份恢复或管理备份轮转。处理 ~/.openclaw 目录归档并包含适当的排除规则。</div> <div class="rec-stats"> <span style="color:#f39c12;">★ 89</span> <span style="color:#5b6abf;">📥 30,580</span> </div> </div> </div> </div> </div> <script> document.addEventListener('DOMContentLoaded',function(){ document.querySelectorAll('.detail-tab').forEach(function(btn){ btn.addEventListener('click',function(e){ var tab = this.getAttribute('data-tab'); document.querySelectorAll('.detail-tab').forEach(function(b){b.classList.remove('active')}); document.querySelectorAll('.detail-content').forEach(function(c){c.classList.remove('active')}); this.classList.add('active'); var el = document.getElementById('tab-'+tab); if(el) el.classList.add('active'); }); }); }); </script> <div class="footer"> <p>Skill工具集 © 2026</p> </div></body> </html>

Aeo

概述

AEO

Command

Argument Safety

Modes

Examples

Mode Selection

Audit

`--require-meta` (CI gate)

Sitemap Mode

Aeo

概述

AEO

Command

Argument Safety

Modes

Examples

Mode Selection

Audit

--require-meta (CI gate)

Sitemap Mode

`--require-meta` (CI gate)