# Sitedex Audit Fix > Claude Code skill that raises any website's SiteDex AI-readiness score in a single PR. Distilled from 3 PRs and 3 re-audits on agentroot.io. - **Type:** MCP server - **Install:** `agentstack add mcp-mayank-d3-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 mcp-mayank-d3-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 > A Claude Code skill that raises any website's [SiteDex](https://sitedex.dev) AI-readiness score in a single PR — distilled from 3 PRs and 3 paid re-audits on [agentroot.io](https://agentroot.io) (34 → 60+). If you've ever opened your SiteDex audit and seen a wall of failing checks, you know the pain: ship a fix, pay $5 to re-audit, find out something didn't land the way you thought, iterate. This skill bottles up every dead end so the next site can skip them. ## What it does When you invoke it, Claude will: 1. Pull your site's **live audit JSON** from `api.sitedex.dev` (no auth needed) 2. Diff against a catalog of 16+ protocol checks and 15+ content questions, with per-check fix recipes 3. Walk you through an ordered 1-PR playbook (Tier 0 platform gates → static files → dynamic routes → sitemap → meta tags → content → re-audit) 4. Generate every static file SiteDex looks for (`robots.txt`, `llms.txt`, `humans.txt`, `SKILL.md`, OpenAPI spec, and 5 `.well-known/*` files) from templated placeholders 5. Verify the deployment with curl checks for every SEO surface 6. Log audits over time so you see score trajectory It's **platform-agnostic** (Vercel guidance shipped today; Netlify/Cloudflare Pages/Amplify follow the same principles) and **version-agnostic** (queries SiteDex live rather than hardcoding the rubric — when SiteDex adds new checks, the skill walks you through discovery instead of falling over). ## Why a skill, not a script? Because raising a SiteDex score is 30% running curl and 70% understanding why a specific check is failing. The skill packages the reasoning alongside the automation — when something goes sideways, Claude has the gotchas catalogue, the per-check recipes, and the discovery flow inline. ## Installation ### Option A — Claude Code skill (recommended) Clone into your Claude skills directory: ```bash # Project-level (per-repo, gitignored) mkdir -p .claude/skills git clone https://github.com/mayank-d3/sitedex-audit-fix.git .claude/skills/sitedex-audit-fix # OR user-level (available across all your projects) mkdir -p ~/.claude/skills git clone https://github.com/mayank-d3/sitedex-audit-fix.git ~/.claude/skills/sitedex-audit-fix ``` Restart your Claude Code session. The skill auto-discovers and shows up in your skill list as `sitedex-audit-fix`. ### Option B — Git submodule (for monorepos) ```bash git submodule add https://github.com/mayank-d3/sitedex-audit-fix.git .claude/skills/sitedex-audit-fix git commit -m "add sitedex-audit-fix skill" ``` ### Option C — Run scripts directly (no Claude Code required) Every shell script in `scripts/` works standalone: ```bash git clone https://github.com/mayank-d3/sitedex-audit-fix.git cd sitedex-audit-fix chmod +x scripts/*.sh # Pull your site's current audit bash scripts/audit-status.sh yoursite.com # Verify your deployment passes the checks bash scripts/verify-deploy.sh https://yoursite.com # Check sitemap lastmod coverage bash scripts/sitemap-coverage.sh https://yoursite.com ``` ## Usage ### From inside Claude Code Once installed, invoke directly: ``` /sitedex-audit-fix ``` Or just say in chat: > Raise the SiteDex score for example.com Claude will load the skill, pull the live audit, and walk you through the playbook. ### From the command line ```bash # 1. Discover what's failing on your site bash scripts/audit-status.sh yoursite.com ``` Output: composite score, protocol/content breakdown, every failing check with its fix recipe, every unanswered buyer question with the suggested page to write. ```bash # 2. After making fixes and deploying, verify bash scripts/verify-deploy.sh https://yoursite.com ``` Output: pass/fail for ~25 SEO surfaces. Catches the most common silent bugs (Vercel static-first, missing `Vary: Accept`, malformed sitemap dates, apex 307 redirects). ```bash # 3. Track score history over time bash scripts/log-audit.sh yoursite.com "post deploy of PR #42" ``` Appends timestamp + score + audit id + deploy SHA to `${CLAUDE_PLUGIN_DATA:-.claude-data}/sitedex-audit-fix/.log`. ## Project structure ``` sitedex-audit-fix/ ├── SKILL.md ← Claude entry point (loaded when skill triggers) ├── config.json ← per-site cache (placeholders, platform, etc.) │ ├── references/ ← detailed reading, loaded on demand │ ├── gotchas.md ← THE highest-signal file — 17 dead ends with detection + fix │ ├── protocol-checks.md ← per-check fix recipes │ ├── audit-anatomy.md ← scoring math, weights, formula, API endpoints │ ├── content-questions.md ← buyer-question playbook with H2/H3 keyword guidance │ └── discovery.md ← version-drift flow when SiteDex adds new checks │ ├── platforms/ ← platform-specific deployment │ ├── platform-agnostic.md ← universal principles (Netlify/CF Pages/Amplify/custom) │ └── vercel.md ← Vercel deep-dive (static-first, apex flip, middleware) │ ├── scripts/ ← executable shell scripts (no dependencies beyond curl/python3) │ ├── audit-status.sh ← pull live audit + per-check breakdown │ ├── verify-deploy.sh ← post-deploy curl check of every SEO surface │ ├── sitemap-coverage.sh ← measure coverage % + detect Date.toString() bug │ └── log-audit.sh ← append per-site score history │ └── templates/ ← copy-paste with {{PLACEHOLDER}} markers ├── robots.txt ← with Content-Signal directive INSIDE (not a JSON file) ├── llms.txt ├── humans.txt ├── SKILL.md ← template for sites publishing their own SKILL.md ├── openapi.yaml ← OpenAPI 3 starter ├── index-html-head.html ← full OG/Twitter/JSON-LD/canonical meta block ├── agents-skills-index.json ← skills directory listing └── well-known-* ← mcp.json, webmcp.json, content-signal.json, security.txt, agent-card.json ``` ## The 1-PR playbook (TL;DR) Open `SKILL.md` for the full version. In short: | Tier | What | Effort | |---|---|---| | **0** | **Platform gates** — apex/www canonical flip, CDN proxy decisions (needs DevOps perms) | Minutes (if perms) | | **1** | **Static files** at the apex — drop the 10 templates into your `public/` dir, fill placeholders | 30 minutes | | **2** | **Dynamic routes** — `Accept: text/markdown` negotiation on `/`, per-route SEO injection, `Vary: Accept` headers | 1–2 hours | | **3** | **Sitemap quality** — `` on EVERY URL (100% coverage required), use `.toISOString().slice(0,10)` not `.toString()` | 30 minutes | | **4** | **Homepage meta tags** — paste `templates/index-html-head.html` into your `index.html` (or app shell), fill placeholders | 15 minutes | | **5** | **Content pages** (the big lever — 70% of total composite) — answer SiteDex's buyer questions with H2/H3 that mirror their keywords | 3–5 hours | | **6** | **Re-audit** — pay 1 credit ≈ $5 (or wait ~24h for cron). Log result. | 5 minutes | ## Gotchas you'll want to avoid 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 from CDN before your `/` handler runs. Your markdown-negotiation code is dead. Fix: rename to `dist/app.html`. 2. **Content-Signal lives in `robots.txt`, NOT a JSON file.** The audit ignores `.well-known/content-signal.json`. The directive must be inside the `User-agent: *` block of robots.txt. 3. **WebMCP wants `tools: []` at the top level** of `webmcp.json` per the wellknownmcp.org schema. `api`/`mcp`/`skills` keys without a top-level `tools` array = check fails. 4. **Apex 307 redirects break `meta_description_present`.** SiteDex audits the bare apex and does NOT follow cross-host redirects. The redirect body has no meta tags. 5. **`Date.toString()` produces invalid sitemap `` values.** They pass binary presence checks but corrupt freshness signals downstream. Use `.toISOString().slice(0,10)`. ## How the version-agnostic discovery works SiteDex's rubric changes over time. This skill never hardcodes the check list. Each run: 1. `scripts/audit-status.sh` fetches `https://api.sitedex.dev/v1/sites//report` — the authoritative live check list 2. For each failing check, Claude looks it up in [references/protocol-checks.md](references/protocol-checks.md) 3. If a check appears that the catalog doesn't recognize, the skill falls back to: - The SiteDex hosted MCP (`mcp.sitedex.dev/mcp` — 5 read-only tools, no auth) - `https://sitedex.dev/openapi.json` (schema definitions) - Prompting the user for a screenshot or doc link 4. New entries get added to the catalog so future runs handle them See [references/discovery.md](references/discovery.md) for the full flow. ## Use cases - **Pre-launch audit** — run this BEFORE submitting a new site to SiteDex so the first score is high - **Score-recovery** — sites that lost score after a redesign / migration - **AI-readiness compliance** — corporate sites that need to publish robots.txt + content-signal as part of an AI usage policy - **MCP/A2A server publishing** — sites exposing programmatic surfaces that want AI agents to discover them ## Tested on - [agentroot.io](https://agentroot.io) — D3's DNS-based AI agent registry. Score: 34 → 51+ (in progress to 75+) across 3 PRs ([#89](https://github.com/d3-inc/agentroot/pull/89), [#90](https://github.com/d3-inc/agentroot/pull/90), [#91](https://github.com/d3-inc/agentroot/pull/91)). Most gotchas in `references/gotchas.md` were discovered the hard way during this work. Used the skill on your site? PR a one-liner to this README. Always interested in patterns specific to a particular platform or framework. ## Contributing If your site hit a SiteDex check this skill doesn't cover, or a fix that worked when ours didn't: 1. Add the check to [references/protocol-checks.md](references/protocol-checks.md) (or content question to [references/content-questions.md](references/content-questions.md)) 2. Add the gotcha to [references/gotchas.md](references/gotchas.md) if it bit you 3. Open a PR For platform-specific guidance (Netlify, Cloudflare Pages, AWS Amplify, etc.), add a new file under `platforms/` following the same shape as `platforms/vercel.md`. ## Credits Built on principles from [@trq212](https://x.com/trq212) ("Lessons from Building Claude Code: Tips for Making Skills") — folder-not-file, progressive disclosure, gotchas-section-is-highest-signal, code-as-tools. ## License MIT — see [LICENSE](LICENSE). ## See also - [SiteDex](https://sitedex.dev) — the audit this skill targets - [llms.txt](https://llmstxt.org) — the proposed standard for AI-readable site indexing - [WebMCP](https://wellknownmcp.org) — the WebMCP discovery manifest spec - [Content-Signal](https://blog.cloudflare.com/ai-search/) — Cloudflare's AI-usage signaling proposal - [Anthropic on Skills](https://www.anthropic.com/news/agent-skills) — the skill abstraction Claude Code is built on ## Source & license This open-source MCP server 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/mcp-mayank-d3-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%.