Sitedex Audit Fix

sitedex-audit-fix

> A Claude Code skill that raises any website's SiteDex AI-readiness score in a single PR — distilled from 3 PRs and 3 paid re-audits on 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:

# 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)

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:

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

# 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.

# 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).

# 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

1. 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 — D3's DNS-based AI agent registry. Score: 34 → 51+ (in progress to 75+) across 3 PRs (#89, #90, #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 ("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 — the audit this skill targets
• llms.txt — the proposed standard for AI-readable site indexing
• WebMCP — the WebMCP discovery manifest spec
• Content-Signal — Cloudflare's AI-usage signaling proposal
• Anthropic on 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
• Source: mayank-d3/sitedex-audit-fix
• License: MIT
• Homepage: https://sitedex.dev

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