Sitedex Audit Fix

SiteDex Audit Fix — one-PR playbook for any website

> Pull the live audit FIRST. SiteDex's rubric changes — never trust this skill's hardcoded check list.

Decision rule — load this skill when…

The user asks to "improve / raise / fix" a SiteDex score, OR mentions any of: AI-readiness, agent-discoverability, llms.txt, robots.txt AI bots, sitemap lastmod, WebMCP, Content-Signal, MCP card, markdown negotiation, server-rendered content, agent-card.json, well-known/agentroot.json.

Skip if the user is asking about Google SEO, Core Web Vitals, or generic SEO best practices — that's a different audit.

Before anything — pull the live audit

DOMAIN=
bash scripts/audit-status.sh $DOMAIN

This prints: composite score, protocol score, content score, every passing check, every failing check with weight, and the audit ID. Everything below is calibrated against that output. If a check appears in the audit that this skill doesn't recognize, see [references/discovery.md](references/discovery.md) — there's a flow to handle that.

The 1-PR ordering (highest leverage first)

This is the order we wished we'd shipped in. We did it in 3 PRs across 3 round-trip audits, paying 3 credits. You can do it in one if you follow this.

Tier 0 — Platform-level gates (do FIRST, may need DevOps)

Some fixes need platform/DNS access. Identify them up front so you can request the changes in parallel with code work. See [platforms/](platforms/) for per-platform guidance (Vercel today, others to be added). Common ones:

• Apex vs www canonical — SiteDex audits the bare apex. If apex 307s to www, the meta-description check fails because the redirect body has no meta tags. Fix: make apex primary, www → apex.
• No CDN proxy in front of Vercel/Netlify/CF Pages — Vercel shows "Proxy Detected" warning. Doesn't break the score but degrades bot-detection.

If you don't have access, skip these and note them as user-action-required. They're worth ~+2 protocol each (~+0.6 composite).

Tier 1 — Static files at the apex (90% of protocol score)

Copy from templates/ to the site's web-root public directory. Each template has placeholders to fill (project name, domain, contacts). Files:

| Template | Path on site | Check it satisfies | |---|---|---| | templates/robots.txt | /robots.txt | robots_ai_bots, content_signal_policy (Content-Signal directive INSIDE robots.txt — NOT a separate JSON file) | | templates/llms.txt | /llms.txt | llms_txt_root | | templates/humans.txt | /humans.txt | humans_txt | | templates/SKILL.md | /SKILL.md + /.agents/skills//SKILL.md (mirror) | skill_md_publication | | templates/openapi.yaml | /openapi.yaml AND /.well-known/openapi.yaml | openapi_spec | | templates/well-known-mcp.json | /.well-known/mcp.json | mcp_card | | templates/well-known-webmcp.json | /.well-known/webmcp.json | webmcp_widget (TOP-LEVEL tools: [] array per wellknownmcp.org schema, NOT api/mcp/skills keys) | | templates/well-known-content-signal.json | /.well-known/content-signal.json | NOTE: this file does NOT satisfy the Content-Signal check — that's in robots.txt. The file is for completeness. | | templates/well-known-security.txt | /.well-known/security.txt | security_txt (RFC 9116) | | templates/well-known-agent-card.json | /.well-known/agent-card.json | agent_card (A2A discovery) | | templates/well-known-agentroot.json | /.well-known/agentroot.json (or your site's manifest) | manifest_published | | templates/agents-skills-index.json | /.agents/skills/index.json | Backs the webmcp.json skills key — without this, the URL 404s |

Run after copying:

bash scripts/verify-deploy.sh https://

Tier 2 — Dynamic routes (server-rendered SEO + markdown negotiation)

If your site is a SPA on Vercel/Netlify/CF Pages, the static-first rule on those platforms can break dynamic routes silently. The Vercel-static-first gotcha is the highest-impact mistake. See [references/gotchas.md](references/gotchas.md) §1.

You need:

• A server function (Hono, Express, edge function, whatever) handling / and detail routes
• Accept: text/markdown negotiation on at least / (homepage)
• Per-route OG/Twitter/JSON-LD meta injection — pulling page-specific data into the ``
• Vary: Accept header on every markdown-negotiable route (prevents CDN caching wrong content-type)

Tier 3 — Sitemap quality

| Issue | Check | Fix | |---|---|---| | ` missing from some URLs | sitemaplastmodpresent — **binary on 100% coverage, partial = fail** | Add to every entry. Use real timestamps where you have them, deploy date as fallback. | | Date.toString() produces invalid lastmod | (silent — passes presence check but degrades freshness signal) | Use .toISOString().slice(0, 10) — never .toString()` |

Run bash scripts/sitemap-coverage.sh https:// to measure. Target: 100%.

Tier 4 — Homepage meta tags

In your HTML shell (index.html):

• `` — first 250 chars matter, front-load the value prop
• Full OpenGraph stack (og:type, og:site_name, og:title, og:description, og:url, og:image)
• Twitter card stack (twitter:card, twitter:title, twitter:description, twitter:image)
• `` pointing to the apex
• ``
• JSON-LD Organization + WebSite (with SearchAction if site has search)

See templates/index-html-head.html for the full snippet.

Tier 5 — Content (70% of total composite — the big lever for scores above ~60)

This is where most of the remaining score lives once protocol is maxed out. SiteDex asks ~15 "buyer questions" per audit and uses an LLM judge to grade your content. Categories: pricing/limits, security, integration, operations, technical.

The trick — semantic search over your H2/H3. SiteDex's judge searches your indexed pages for chunks that answer each question. The H2 and H3 headings should mirror the buyer question's exact keywords. Generic headings get rejected.

See [references/content-questions.md](references/content-questions.md) for:

• The 15 standard buyer questions (best-effort list — pulled from prior audits)
• Example H2/H3 phrasings that pass
• How to map your existing docs to these questions
• A discovery flow for new questions SiteDex adds

Tier 6 — Re-audit and iterate

After all changes deploy:

1. bash scripts/audit-status.sh (free — uses public API, shows current cached audit)
2. To force a fresh audit: sign in at app.sitedex.dev and click Re-audit (1 credit ≈ $5). Or wait ~24h for the daily cron.
3. Compare new score to baseline. If gaps remain, query the audit JSON for the failing check names and check [references/protocol-checks.md](references/protocol-checks.md) for fixes.

Gotchas summary — read this before touching anything

The full list is in [references/gotchas.md](references/gotchas.md). Top 5 by damage caused:

1. Vercel static-first wins over rewrites. If dist/index.html exists, Vercel serves it before checking the / rewrite. Your Accept: text/markdown handler on / never runs. Rename to dist/app.html and point the SPA fallback at the new name. Verify with curl -I -H 'Accept: text/markdown' https://site/ — should be text/markdown, not text/html.
2. Content-Signal lives in robots.txt, NOT a JSON file. The Content-Signal: ai-train=yes, search=yes, ai-input=yes directive belongs INSIDE the User-agent: * block of robots.txt. A .well-known/content-signal.json file is ignored by the audit. (Cloudflare convention.)
3. WebMCP wants tools: [] at top level. Per wellknownmcp.org schema. If your webmcp.json has api/mcp/skills keys but no top-level tools array, the check fails.
4. Apex 307 redirects break metadescriptionpresent. SiteDex audits the apex URL directly and does NOT follow cross-host redirects. If apex 307s to www, the redirect HTML has no meta tags, check fails.
5. Date.toString() produces invalid sitemap lastmod values. They pass binary presence checks but corrupt freshness signals downstream. Use .toISOString().slice(0, 10).

Version-agnostic discovery flow

SiteDex's checks change over time. This skill doesn't hardcode them. The flow:

1. Always start by pulling https://api.sitedex.dev/v1/sites//report — that's the authoritative current check list.
2. If a check appears that isn't in [references/protocol-checks.md](references/protocol-checks.md):

• Try sitedex_search MCP tool for the check name
• Read https://sitedex.dev/docs and /openapi.json (the schema)
• If still unknown, prompt the user: "SiteDex flagged a check I don't recognize — ``. Can you screenshot the audit detail or paste the SiteDex doc link?"

1. After resolving, update references/protocol-checks.md with the new entry so future runs handle it.

See [references/discovery.md](references/discovery.md) for the full flow.

Memory — track audit history per site

This skill maintains an append-only log per site in ${CLAUDE_PLUGIN_DATA:-.claude-data}/sitedex-audit-fix/.log. Each run appends: timestamp, score, failing checks, what was attempted, deploy SHA. Run bash scripts/log-audit.sh after each audit to record. Useful for showing score trajectory over time.

What this skill does NOT do

• It does NOT push code or open PRs — you do that
• It does NOT pay for SiteDex audits (1 credit ≈ $5 — user's account)
• It does NOT do general SEO / Core Web Vitals / accessibility work — that's a different audit
• It does NOT migrate a SPA to SSR — too invasive; the skill flags it as deferred

Files in this skill

• SKILL.md (this file) — overview + 1-PR playbook
• references/audit-anatomy.md — scoring math, weights, composite formula
• references/protocol-checks.md — per-check fix recipes (loaded as needed)
• references/content-questions.md — buyer-question playbook
• references/gotchas.md — full failure catalog from agentroot.io
• references/discovery.md — version-drift flow + screenshot/doc prompting
• platforms/vercel.md — Vercel-specific fixes (apex flip, static-first rename)
• platforms/platform-agnostic.md — generic principles for Netlify/CF Pages/anything
• scripts/audit-status.sh — pull current audit (no auth, free)
• scripts/verify-deploy.sh — curl every SEO surface post-deploy
• scripts/sitemap-coverage.sh — measure lastmod coverage %
• scripts/log-audit.sh — append result to per-site history log
• templates/* — copy-paste templates for every static file SiteDex checks

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mayank-d3
• Source: mayank-d3/sitedex-audit-fix
• License: MIT
• Homepage: https://sitedex.dev

Install and usage instructions live in the source repository linked above.