# Sitedex Audit Fix > | - **Type:** Skill - **Install:** `agentstack add skill-mayank-d3-sitedex-audit-fix-sitedex-audit-fix` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [mayank-d3](https://agentstack.voostack.com/s/mayank-d3) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [mayank-d3](https://github.com/mayank-d3) - **Source:** https://github.com/mayank-d3/sitedex-audit-fix - **Website:** https://sitedex.dev ## Install ```sh agentstack add skill-mayank-d3-sitedex-audit-fix-sitedex-audit-fix ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ```bash 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 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 | `sitemap_lastmod_present` — **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 meta_description_present.** 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?" 3. 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](https://github.com/mayank-d3) - **Source:** [mayank-d3/sitedex-audit-fix](https://github.com/mayank-d3/sitedex-audit-fix) - **License:** MIT - **Homepage:** https://sitedex.dev Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-mayank-d3-sitedex-audit-fix-sitedex-audit-fix - Seller: https://agentstack.voostack.com/s/mayank-d3 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.