Docs Auditor

Docs Auditor Skill

Audits a developer documentation site across 33 checks in 7 categories. Given a docs URL, fetch all required pages, evaluate every check, and render a visual scored report.

---

Step 0a — Unlock Derived URLs via Targeted Search (CRITICAL, do this first)

Before fetching any derived URLs, run a single web_search that includes the exact file paths you need. This is required because web_fetch only allows fetching URLs that were user-provided or appeared in prior search/fetch results — the tool cannot fetch derived paths on its own, even if the root domain is known.

Given a docs URL like https://docs.example.com/, construct and run this search:

docs.example.com/llms.txt docs.example.com/robots.txt docs.example.com/sitemap.xml example.com/llms.txt example.com/robots.txt example.com/sitemap.xml

Include both the subdomain and the root domain variants in the same query — these files may be hosted on either. This single search surfaces the exact file URLs in results, making them immediately fetchable. If a file doesn't appear in results at all, that is itself strong evidence it doesn't exist — mark the relevant checks as fail without needing to attempt a fetch.

Do this search silently as an internal setup step. Do not narrate it to the user.

---

Step 0b — URL Expansion (CRITICAL)

When the user provides a base docs URL (e.g. https://docs.example.com/), you MUST immediately treat ALL of the following derived URLs as user-provided and fetch them without asking for permission. This is the core mechanic that makes the audit work.

Given base URL https://docs.example.com/, fetch ALL of these in your first round:

{base}/robots.txt
{base}/sitemap.xml
{base}/llms.txt
{base}/llms-full.txt

Also try the root domain variants if the docs are on a subdomain:

https://{root-domain}/robots.txt
https://{root-domain}/llms.txt
https://{root-domain}/llms-full.txt
https://{root-domain}/sitemap.xml

Then fetch the main docs page itself, plus these standard sub-pages (adjust slugs based on what you find in the sidebar/nav):

{base}/                          ← landing / intro page
{base}/quickstart  (or /getting-started, /get-started)
{base}/changelog   (or /releases, /release-notes)
{base}/api         (or /api-reference, /reference)
{base}/faq         (or /troubleshooting, /help)
{base}/[one use-case or tutorial page]
{base}/[one deep settings or config page]

Fetch 6–8 pages minimum. More is better. Do NOT ask the user for more URLs — derive them.

---

Step 1 — Run All 33 Checks

After fetching, evaluate every check below. Use the fetched HTML/markdown content as evidence. Mark each check as pass, warn, or fail using the criteria defined per check.

Category 1 — AI & LLM Discoverability (5 checks)

Category 2 — Structure & Navigation (6 checks)

Category 3 — Content Completeness (6 checks)

Category 4 — Content Quality (3 checks)

Category 5 — Technical SEO & Crawlability (5 checks)

Category 6 — Internal Linking & Flow (4 checks)

Category 7 — Versioning & Maintenance (4 checks)

---

Step 2 — Score Calculation

Score each category out of its max points. Each check is worth equal points within its category. Each category is weighted equally (each = 100/7 ≈ 14.3 points max).

Within each category:

• Pass = full points
• Warn = half points
• Fail = 0 points

Final score = sum across all 7 categories, rounded to nearest integer out of 100.

---

Step 3 — Render the Report

Generate a standalone HTML report file:

• Use the HTML/CSS/JS template in references/widget-template.md as the design reference.
• Write the completed report to a file named {domain}-docs-audit.html in the current working

directory (e.g. supabase-docs-audit.html).

• The report must include:

1. Score hero — large score out of 100, domain name, pass/warn/fail summary counts 2. Legend — green dot = Pass, amber dot = Warn, red dot = Fail 3. Category sections — one block per category with:

• Category name and score (e.g. "3/5")
• Pill badges: "X pass", "X warn", "X fail"
• Each check row with icon (✓ / ! / ✗), label, and a short evidence note
• Substitute all audit data (score, counts, category scores, check statuses, evidence notes)

directly into the template — do not leave any placeholder values unfilled.

• The file must be fully self-contained (no external dependencies) so it opens correctly in

any browser without a server.

---

Step 4 — After the Report

After rendering, provide a short text summary (3–5 sentences) covering:

• The 1–2 strongest categories
• The biggest gaps / quick wins
• Any critical issues (e.g. broken canonical, noindex on docs, AI bots blocked)

Offer to go deeper on any category or create a prioritized action plan.

---

Notes for Edge Cases

• Subdomain docs (e.g. docs.stripe.com): always also check root domain (stripe.com) for

robots.txt, llms.txt, and sitemap.xml — they are often hosted at root.

• Docs behind auth: if pages return 401/403, mark relevant checks as warn with note

"Could not verify — page requires authentication."

• JS-rendered docs: if fetched HTML is sparse (< 200 chars of text), note that the docs

may be JS-rendered and some checks may be inconclusive.

• check 7.4 (deprecation): only fail this if evidence suggests the product has multiple

versions. If it's clearly v1 only, mark as N/A (counts as pass for scoring).

Docs Auditor

Audits any developer documentation site across 33 checks in 7 categories and produces an interactive scored report out of 100, rendered inline in Claude.

<p align="center"> <a href="../../assets/docs-auditor-gif.gif"> <img src="../../assets/docs-auditor-gif.gif" width="100%" alt="Docs Auditor in action" /> </a> </p>

---

What this skill does

Most documentation quality checks are manual and inconsistent. This skill automates a full audit by fetching the live site, sampling key pages, and evaluating 33 specific signals across structure, content, SEO, AI discoverability, and maintenance hygiene.

The output is a visual widget rendered directly in Claude: a color-coded score circle, per-category breakdowns, and a pass/warn/fail badge on every individual check with a short evidence note explaining the finding. No spreadsheets, no copy-pasting URLs, no manual checklist.

Built for:

• Developer marketing and DevRel teams evaluating their own docs before a launch or redesign
• GEO practitioners checking whether docs are structured for AI discoverability (llms.txt, sitemap, bot access)
• Technical writers running a structured gap analysis before a content audit
• Agencies and consultants producing a scored deliverable for a client docs review

---

Installation

Claude Code (Recommended)

Clone the repo — the skill activates automatically when you open it in Claude Code:

git clone https://github.com/Infrasity-Labs/dev-gtm-claude-skills.git
cd dev-gtm-claude-skills
claude

Then trigger it with:

/dev-gtm docs-audit https://docs.stripe.com

Or just describe what you want — Claude activates the skill automatically when you provide a docs URL with audit intent.

Claude Web (Free / Pro)

1. Go to [Settings → Capabilities](https://claude.ai/settings/capabilities) and enable Code execution and file creation 2. Go to [Customize → Skills](https://claude.ai/customize/skills) 3. Click + → Create skill → Upload a skill 4. Zip this skill folder and upload it:

cd dev-gtm-claude-skills/skills
zip -r docs-auditor.zip docs-auditor/

Upload docs-auditor.zip and toggle it on.

---

How to use

Drop a docs URL in any message:

Audit the docs at https://docs.stripe.com

How good are the docs for https://docs.example.com?

/dev-gtm docs-audit https://docs.example.com

<p align="center"> <img src="../../assets/docs-auditor-trigger.gif" width="100%" alt="Triggering the audit with a URL" /> </p>

The skill picks up any phrasing that includes a docs URL and an audit intent. All required files (robots.txt, sitemap.xml, llms.txt, etc.) and page samples are fetched automatically.

---

What gets checked

The audit runs 33 checks grouped into 7 categories. Each check is evaluated against the live site and marked pass, warn, or fail.

---

<p align="center"> <a href="../../assets/docs-auditor-gif.gif"> <img src="../../assets/docs-auditor-gif.gif" width="100%" alt="Example audit report widget" /> </a> </p>

---

How the fetch works

The skill performs a structured multi-step fetch before evaluating any checks:

1. Runs a targeted web search to surface robots.txt, sitemap.xml, llms.txt, and llms-full.txt for both the docs subdomain and root domain 2. Fetches each of those files directly 3. Fetches the docs homepage plus 6–8 sampled pages: quickstart, changelog, API reference, an error codes or FAQ page, and one or two deeper guide pages 4. Evaluates all 33 checks against the fetched content

The skill handles common edge cases: JS-rendered pages (flagged as inconclusive rather than failed), subdomain vs root domain file hosting, auth-gated pages (marked warn with a note), and single-version products (check 7.4 deprecation notices marked N/A rather than fail).

---

Limitations

• Pages behind authentication cannot be fetched. Affected checks are marked warn with a note.
• Heavily JS-rendered docs may return sparse HTML. The skill flags this and marks affected checks as inconclusive rather than failed.
• The audit samples 6–8 pages. It is not a full crawl — checks reflect the sampled content, not every page on the site.
• robots.txt AI bot policy is evaluated based on what can be fetched. If the file is not surfaced in search results, the check is marked warn rather than assumed pass or fail.

---

File structure

docs-auditor/
├── SKILL.md                        # Skill instructions Claude follows
├── README.md                       # This file
├── references/
│   ├── widget-template.md          # HTML/CSS template for the report widget
│   ├── fetch-strategy.md           # Which URLs to fetch and what to extract
│   └── scoring.md                  # Point values per check and grade bands
└── tests/
    └── test-cases.json             # 5 test cases for validation

Fetch Strategy

URL derivation rules

When the user gives https://docs.example.com/, derive and fetch ALL of these:

Round 1 — Infrastructure files (fetch first, in parallel)

https://docs.example.com/robots.txt
https://docs.example.com/sitemap.xml
https://docs.example.com/llms.txt
https://docs.example.com/llms-full.txt
https://example.com/robots.txt          ← root domain fallback
https://example.com/llms.txt            ← root domain fallback
https://example.com/sitemap.xml         ← root domain fallback

Round 2 — Core pages (fetch these regardless)

https://docs.example.com/               ← homepage / intro
https://docs.example.com/quickstart     ← try: /quickstart, /getting-started, /get-started, /start
https://docs.example.com/changelog      ← try: /changelog, /releases, /release-notes, /whats-new

Round 3 — Probe pages (try common slugs, use what works)

API Reference:    /api, /api-reference, /reference, /api-docs
FAQ/Support:      /faq, /troubleshooting, /help, /support
Tutorials:        /tutorials, /guides, /examples, /use-cases
Install/Setup:    /installation, /setup, /configuration, /config

Round 4 — Sidebar links (pick 2–3 from the nav you found in Round 2)

Pick one deep settings page and one use-case/tutorial page from the sidebar links you discovered. These are for depth-checking (check 4.3).

---

What to extract from each file type

robots.txt

• Is Disallow: / present? → everything blocked
• Are AI bots mentioned? Look for: GPTBot, ClaudeBot, anthropic-ai, PerplexityBot, Googlebot-Extended, ChatGPT-User, cohere-ai, CCBot
• Is there a Sitemap: directive?

sitemap.xml

• Does it exist?
• Does it list doc page URLs?
• How many URLs? (rough count is fine)

llms.txt

• Does it exist and have content?
• Does it link to doc pages?
• Does it reference llms-full.txt?

llms-full.txt

• Does it exist?
• Is it non-empty?

HTML pages

• <title> tag
• meta name="description" content
• link rel="canonical" href — check if it matches the actual domain
• meta name="robots" — check for noindex
• Sidebar HTML — look for <nav>, <aside>, or elements with class names like sidebar, nav-menu
• Breadcrumbs — look for <nav aria-label="breadcrumb"> or class breadcrumb
• Search — look for <input type="search"> or role="search" or class search
• Prev/next links — look for rel="prev" / rel="next" or text "Previous" / "Next" near bottom
• Code blocks — <code>, <pre>, language labels like python, javascript, curl
• Cross-links — <a href="..."> pointing to other pages within the same domain
• GitHub links — links containing github.com
• Community links — links containing discord, slack, forum, community, reddit
• Version signals — text matching patterns like v\d+\.\d+, "latest", version badge elements
• Last updated — text matching "last updated", "updated on", date stamps near top/bottom of page
• Install commands — pip install, npm install, yarn add, brew install, cargo add

---

Handling fetch failures

---

Minimum fetch requirement

You must fetch at least 6 pages before generating the report. If fewer than 6 pages are accessible, note it in the report summary. Never generate the report after fetching only 1–2 pages.

Scoring Reference

Category weights

Each of the 7 categories contributes equally to the final 100-point score.

Grade bands

Score circle color

• 80–100 → #639922 (green)
• 60–79 → #BA7517 (amber)
• 0–59 → #E24B4A (red)

Category score display

Show as fraction of checks passed, e.g. "4/5" or "3/6". Warn counts as 0.5 for display: "3.5/6" is fine, or round to nearest integer.

Docs Audit Report — Widget Template

Use this template when rendering the audit report via show_widget. Copy the structure and substitute real audit data. Always call read_me with ["mockup", "data_viz"] first.

---

Score color rules

---

Full HTML template

<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
.wrap { padding: 1.5rem 0; }
.score-hero { display: flex; align-items: center; gap: 24px; padding: 1.25rem 1.5rem; background: var(--color-background-secondary); border-radius: var(--border-radius-lg); margin-bottom: 1.5rem; }
.score-circle { width: 80px; height: 80px; border-radius: 50%; border: 3px solid {SCORE_COLOR}; display: flex; flex-direction: column; align-items: center; justify-content: center; flex-shrink: 0; }
.score-num { font-size: 26px; font-weight: 500; color: var(--color-text-primary); line-height: 1; }
.score-denom { font-size: 12px; color: var(--color-text-secondary); }
.score-meta { flex: 1; }
.score-title { font-size: 17px; font-weight: 500; color: var(--color-text-primary); margin-bottom: 4px; }
.score-sub { font-size: 13px; color: var(--color-text-secondary); line-height: 1.6; }
.legend { display: flex; gap: 16px; margin-bottom: 1.25rem; flex-wrap: wrap; }
.leg { display: flex; align-items: center; gap: 6px; font-size: 12px; color: var(--color-text-secondary); }
.dot { width: 10px; height: 10px; border-radius: 50%; }
.dot-pass { background: #639922; }
.dot-warn { background: #BA7517; }
.dot-fail { background: #E24B4A; }
.category { margin-bottom: 1.25rem; border: 0.5px solid var(--color-border-tertiary); border-radius: var(--border-radius-lg); overflow: hidden; }
.cat-header { display: flex; align-items: center; justify-content: space-between; padding: 0.75rem 1rem; background: var(--color-background-secondary); }
.cat-left { display: flex; align-items: center; gap: 10px; }
.cat-name { font-size: 14px; font-weight: 500; color: var(--color-text-primary); }
.cat-score { font-size: 12px; color: var(--color-text-secondary); }
.cat-pills { display: flex; gap: 6px; flex-wrap: wrap; }
.pill { font-size: 11px; padding: 2px 8px; border-radius: 99px; font-weight: 500; }
.pill-pass { background: #EAF3DE; color: #27500A; }
.pill-warn { background: #FAEEDA; color: #633806; }
.pill-fail { background: #FCEBEB; color: #791F1F; }
.checks { padding: 0; }
.check-row { display: flex; align-items: flex-start; gap: 10px; padding: 0.6rem 1rem; border-top: 0.5px solid var(--color-border-tertiary); }
.check-icon { flex-shrink: 0; width: 18px; height: 18px; border-radius: 50%; display: flex; align-items: center; justify-content: center; margin-top: 1px; font-size: 10px; font-weight: 700; }
.icon-pass { background: #EAF3DE; color: #3B6D11; }
.icon-warn { background: #FAEEDA; color: #854F0B; }
.icon-fail { background: #FCEBEB; color: #A32D2D; }
.check-text { flex: 1; }
.check-label { font-size: 13px; color: var(--color-text-primary); line-height: 1.4; }
.check-note { font-size: 12px; color: var(--color-text-secondary); margin-top: 2px; line-height: 1.4; }
</style>

<div class="wrap">
  <h2 class="sr-only">Docs audit report for {DOMAIN}</h2>

  <div class="score-hero">
    <div class="score-circle">
      <span class="score-num">{SCORE}</span>
      <span class="score-denom">/100</span>
    </div>
    <div class="score-meta">
      <div class="score-title">{DOMAIN} — {SITE_TITLE}</div>
      <div class="score-sub">
        {PASS_COUNT} pass &nbsp;·&nbsp; {WARN_COUNT} warn &nbsp;·&nbsp; {FAIL_COUNT} fail &nbsp;·&nbsp; 33 total checks<br>
        Strongest: {STRONGEST_CATEGORY} &nbsp;·&nbsp; Weakest: {WEAKEST_CATEGORY}
      </div>
    </div>
  </div>

  <div class="legend">
    <span class="leg"><span class="dot dot-pass"></span>Pass</span>
    <span class="leg"><span class="dot dot-warn"></span>Warn</span>
    <span class="leg"><span class="dot dot-fail"></span>Fail</span>
  </div>

  <div id="cats"></div>
</div>

<script>
const categories = [
  {
    name: "1. AI & LLM Discoverability",
    score: "X/5",
    checks: [
      { status: "pass|warn|fail", label: "llms.txt present at root domain", note: "Evidence note here" },
      { status: "pass|warn|fail", label: "llms-full.txt present", note: "Evidence note here" },
      { status: "pass|warn|fail", label: "Docs pages listed in llms.txt", note: "Evidence note here" },
      { status: "pass|warn|fail", label: "AI bots allowed in robots.txt", note: "Evidence note here" },
      { status: "pass|warn|fail", label: "Docs pages in sitemap.xml", note: "Evidence note here" },
    ]
  },
  {
    name: "2. Structure & Navigation",
    score: "X/6",
    checks: [
      { status: "pass|warn|fail", label: "Introduction / overview page with real content", note: "" },
      { status: "pass|warn|fail", label: "Quickstart / Getting Started with actionable steps", note: "" },
      { status: "pass|warn|fail", label: "API Reference / Reference section present", note: "" },
      { status: "pass|warn|fail", label: "Sidebar / navigation menu present", note: "" },
      { status: "pass|warn|fail", label: "Breadcrumb navigation present", note: "" },
      { status: "pass|warn|fail", label: "Search functionality present", note: "" },
    ]
  },
  {
    name: "3. Content Completeness",
    score: "X/6",
    checks: [
      { status: "pass|warn|fail", label: "Use cases / tutorials / examples section present", note: "" },
      { status: "pass|warn|fail", label: "Code examples present", note: "" },
      { status: "pass|warn|fail", label: "Multiple language examples (Python, JS, cURL, etc.)", note: "" },
      { status: "pass|warn|fail", label: "Changelog / Release notes present", note: "" },
      { status: "pass|warn|fail", label: "FAQ / Troubleshooting section present", note: "" },
      { status: "pass|warn|fail", label: "Error messages / status codes documented", note: "" },
    ]
  },
  {
    name: "4. Content Quality",
    score: "X/3",
    checks: [
      { status: "pass|warn|fail", label: "Intro page explains what the product is and who it's for", note: "" },
      { status: "pass|warn|fail", label: "Quickstart gets user to a working state", note: "" },
      { status: "pass|warn|fail", label: "Sampled pages have sufficient depth (not stubs)", note: "" },
    ]
  },
  {
    name: "5. Technical SEO & Crawlability",
    score: "X/5",
    checks: [
      { status: "pass|warn|fail", label: "HTTPS enforced", note: "" },
      { status: "pass|warn|fail", label: "Meta titles present on docs pages", note: "" },
      { status: "pass|warn|fail", label: "Meta descriptions present on docs pages", note: "" },
      { status: "pass|warn|fail", label: "Canonical URLs present and correct", note: "" },
      { status: "pass|warn|fail", label: "No noindex directives on docs pages", note: "" },
    ]
  },
  {
    name: "6. Internal Linking & Flow",
    score: "X/4",
    checks: [
      { status: "pass|warn|fail", label: "Docs pages cross-link to each other", note: "" },
      { status: "pass|warn|fail", label: "Next / previous page navigation present", note: "" },
      { status: "pass|warn|fail", label: "Links to GitHub / source code", note: "" },
      { status: "pass|warn|fail", label: "Community / support links present", note: "" },
    ]
  },
  {
    name: "7. Versioning & Maintenance",
    score: "X/4",
    checks: [
      { status: "pass|warn|fail", label: "Version indicator visible", note: "" },
      { status: "pass|warn|fail", label: "Last updated / freshness signal on pages", note: "" },
      { status: "pass|warn|fail", label: "Install commands include version pinning", note: "" },
      { status: "pass|warn|fail", label: "Deprecation notices present (if multi-version)", note: "" },
    ]
  }
];

const iconMap = { pass: "✓", warn: "!", fail: "✗" };
const iconClass = { pass: "icon-pass", warn: "icon-warn", fail: "icon-fail" };
const pillClass = { pass: "pill-pass", warn: "pill-warn", fail: "pill-fail" };
const container = document.getElementById("cats");

categories.forEach(cat => {
  const passCount = cat.checks.filter(c => c.status === "pass").length;
  const warnCount = cat.checks.filter(c => c.status === "warn").length;
  const failCount = cat.checks.filter(c => c.status === "fail").length;
  const el = document.createElement("div");
  el.className = "category";
  const checksHTML = cat.checks.map(c => `
    <div class="check-row">
      <div class="check-icon ${iconClass[c.status]}">${iconMap[c.status]}</div>
      <div class="check-text">
        <div class="check-label">${c.label}</div>
        <div class="check-note">${c.note}</div>
      </div>
    </div>
  `).join("");
  const pillsHTML = [
    passCount ? `<span class="pill pill-pass">${passCount} pass</span>` : "",
    warnCount ? `<span class="pill pill-warn">${warnCount} warn</span>` : "",
    failCount ? `<span class="pill pill-fail">${failCount} fail</span>` : "",
  ].join("");
  el.innerHTML = `
    <div class="cat-header">
      <div class="cat-left">
        <span class="cat-name">${cat.name}</span>
        <span class="cat-score">${cat.score}</span>
      </div>
      <div class="cat-pills">${pillsHTML}</div>
    </div>
    <div class="checks">${checksHTML}</div>
  `;
  container.appendChild(el);
});
</script>

---

Scoring helper

Category max points = 100 / 7 = 14.286

Points per check (within category):
  pass = (category_max / num_checks_in_category)
  warn = (category_max / num_checks_in_category) / 2
  fail = 0

Final score = round(sum of all category points)

Example: Category 1 has 5 checks → each check worth 14.286/5 = 2.857 pts. 3 pass + 1 warn + 1 fail = (3 × 2.857) + (1 × 1.429) + 0 = 9.999 ≈ 10 pts for that category.