--- name: docs-auditor description: > Audits any developer documentation site across 33 checks in 7 categories and produces a scored report (out of 100) with Pass / Warn / Fail status per check. Use this skill whenever a user provides a docs URL and asks to audit it, review it, score it, check its quality, or evaluate it for AI discoverability, SEO, structure, content, or completeness. Also trigger when the user says "run a docs audit", "audit these docs", "check this documentation", "how good are the docs for X", or pastes a docs URL with any evaluative intent. Always use this skill — do not attempt a freeform docs review without following this structured workflow. --- # 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) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 1.1 | `llms.txt` present at root domain | File fetched successfully with content | File exists but empty or malformed | 404 / not found | | 1.2 | `llms-full.txt` present | File fetched successfully | File exists but sparse | 404 / not found | | 1.3 | Docs pages listed in `llms.txt` | Links to doc pages found inside llms.txt | Some pages listed but incomplete | llms.txt absent or no doc links | | 1.4 | AI bots allowed in `robots.txt` | GPTBot, ClaudeBot, or similar explicitly allowed OR no disallow rules for them | Bots not mentioned (ambiguous) | Bots explicitly disallowed | | 1.5 | Docs pages in `sitemap.xml` | Sitemap found and contains doc page URLs | Sitemap exists but sparse / partial | Sitemap missing or 404 | ### Category 2 — Structure & Navigation (6 checks) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 2.1 | Introduction / overview page exists with real content | Page exists with substantive product description (>200 words) | Page exists but thin / vague | No intro page found | | 2.2 | Quickstart / Getting Started with actionable steps | Step-by-step guide gets user to working state | Page exists but steps are vague or incomplete | No quickstart found | | 2.3 | API Reference / Reference section present | Dedicated API reference section with endpoints or methods | Some reference content but not organized as API ref | No reference section found | | 2.4 | Sidebar / navigation menu present | Sidebar with categorized links visible in HTML | Sidebar present but flat / uncategorized | No sidebar detected | | 2.5 | Breadcrumb navigation present | Breadcrumb trail visible on sampled pages | Present on some pages but not all | No breadcrumbs found | | 2.6 | Search functionality present | Search input detected in HTML | Search linked externally but not on-page | No search found | ### Category 3 — Content Completeness (6 checks) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 3.1 | Use cases / tutorials / examples section present | Dedicated section with at least 2 full tutorial pages | Section exists but only 1 page or very thin | No use cases / tutorials found | | 3.2 | Code examples present | Code blocks found on multiple sampled pages | Code present on 1 page only | No code examples found | | 3.3 | Multiple language examples (Python, JS, cURL, etc.) | 2+ languages shown in code examples | Only 1 language shown | No code examples at all | | 3.4 | Changelog / Release notes present | Changelog page exists with actual entries | Page exists but empty or placeholder | No changelog found | | 3.5 | FAQ / Troubleshooting section present | Dedicated FAQ or troubleshooting page with real Q&As | FAQ mentioned but minimal | No FAQ or troubleshooting found | | 3.6 | Error messages / status codes documented | Error codes or status codes listed anywhere in docs | Brief mentions only | No error documentation found | ### Category 4 — Content Quality (3 checks) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 4.1 | Intro page explains what the product is and who it's for | Clear product description + target audience stated | Product described but audience vague | Generic/marketing intro with no substance | | 4.2 | Quickstart gets user to a working state | End-to-end steps from zero to working output | Steps present but incomplete or missing key detail | Quickstart too vague to follow | | 4.3 | Sampled pages have sufficient depth (not stubs) | All sampled pages have real content (>150 words, structured) | Mix of full pages and stubs | Majority of sampled pages are stubs | ### Category 5 — Technical SEO & Crawlability (5 checks) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 5.1 | HTTPS enforced | All fetched URLs use HTTPS | Mixed HTTP/HTTPS | HTTP only | | 5.2 | Meta titles present on docs pages | `` tag found on all sampled pages | Present on some pages | Missing on most pages | | 5.3 | Meta descriptions present on docs pages | `meta-description` found on all sampled pages | Present on some pages | Missing on most pages | | 5.4 | Canonical URLs present and correct | Canonical tag present and points to the correct domain | Canonical present but points to wrong/preview domain | No canonical tags found | | 5.5 | No noindex directives on docs pages | `meta-robots: index, follow` on all sampled pages | Mixed — some pages noindex | Most pages set to noindex | ### Category 6 — Internal Linking & Flow (4 checks) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 6.1 | Docs pages cross-link to each other | Internal links found in body content of sampled pages | Some pages cross-link but most don't | No internal links found in body | | 6.2 | Next / previous page navigation present | Prev/next nav links at bottom of sampled pages | Present on some pages | Not found | | 6.3 | Links to GitHub / source code | GitHub or source code link found in docs | Mentioned in text but not linked | No GitHub / source links found | | 6.4 | Community / support links present (Discord, Slack, Forum, Chat) | Direct links to community or support channel found | Mentioned but no direct link | No community or support references | ### Category 7 — Versioning & Maintenance (4 checks) | # | Check | Pass | Warn | Fail | |---|-------|------|------|------| | 7.1 | Version indicator visible (v1.2, "latest", badge) | Version badge or label visible on sampled pages | Version mentioned in text but no badge | No versioning signals found | | 7.2 | Last updated / freshness signal on pages | "Last updated" date or similar visible | Changelog exists as proxy signal | No freshness signals found anywhere | | 7.3 | Install commands include version pinning | Install commands show pinned versions (e.g. `pip install foo==1.2`) | Install commands present but unpinned | No install commands found | | 7.4 | Deprecation notices present (if multi-version) | Deprecation banners or notices visible | Changelog mentions deprecations | No deprecation notices (only fail if multi-version product) | --- ## 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).