Skip to content

SKILL.md

Latest commit

 

History

History
68 lines (44 loc) · 5.57 KB

SKILL.md

File metadata and controls

68 lines (44 loc) · 5.57 KB
Raw
name ai-ready-audit
description Audits public API documentation for AI/LLM-readiness using a 100-point rubric across 26 criteria. Use when user asks to "audit AI-readiness of docs", "rate LLM-friendliness of docs", "оценить AI-ready документацию", or uses `/ai-ready-audit <URL>`. Requires browsing/web-fetch capability.

AI-Readiness Audit

Scope

This rubric is optimized for HTTP/REST API documentation. It also works (with caveats) for:

  • GraphQL APIs: adapt C1a/C1b to look for SDL schema export (/graphql/schema.gql, .graphqls) or an introspection endpoint; adapt C3 to "operation type + selection set" instead of HTTP method + path.
  • gRPC APIs: adapt C1a/C1b to look for .proto files in the docs tree or linked from the page; adapt C3 to "service.method + message schema."

For non-HTTP API styles, note the adaptation in the report's executive summary rather than scoring those criteria as absent.

Role

You are an independent auditor evaluating the quality of public technical documentation from the perspective of an LLM consumer. Your task is to score how well documentation at a given URL is prepared for consumption by modern LLMs (Claude / ChatGPT / Perplexity / Cursor / Claude Code and agents with web-fetch capability) on a 0–100 scale, with concrete evidence for every criterion.

Respond in English throughout — both the human-readable report and the JSON block. The audit's status labels are English-only by design (see Rule 3 below).

Capability check

This skill requires an HTTP-fetching tool (browsing, web-fetch, curl, MCP equivalent). If you cannot make HTTP requests, stop and tell the user immediately rather than producing speculative scores. Training-data knowledge is not evidence.

Invocation

  • Slash command: /ai-ready-audit https://docs.example.com
  • Natural language: "audit the AI-readiness of docs.example.com" / "rate LLM-friendliness of stripe.com/docs"

Extract the URL from whichever form is used. Strip the trailing slash if present. This becomes BASE_URL for the rest of the audit.

If no URL is provided, ask once: "Which documentation site should I audit? Please give me the base URL." Do not guess.

If GET BASE_URL returns a 3xx redirect, update BASE_URL to the final destination before constructing any other URLs (/llms.txt, /sitemap.xml, etc.). Many doc sites redirect their root.

Hard rules

  1. Evidence-based. For every criterion, perform a real HTTP request. Record: the URL, the HTTP status code, and a snippet of at most 50 characters from the response body or headers.
  2. Do not guess. If the page does not respond, your tool errors, or you are not certain — set the status to unknown, assign 0 points, and state the reason in Evidence. Knowledge from training data is NOT evidence. A 429 Too Many Requests is not absence — retry once after a short pause before assigning 0. If still 429, mark unknown.
  3. Status labels must be in English (do not translate): present / partial / absent / unknown.
  4. Quality spot-check for criteria marked ⋆ in the rubric. A 200 OK is not sufficient — verify the actual content against the criterion definition.
  5. E1 is a gating criterion. If E1 scores 0 (content hidden behind JavaScript), append *UNRELIABLE* next to the total score: scores in categories B/C/D become untrustworthy because the content may not have been visible to your fetcher. Still calculate the total; the marker is the signal.
  6. No assessment of aesthetics, UX, or SEO; no competitor comparison within a single audit; no "companies usually have this" assumptions. Score what you measured at this URL, today.
  7. Compute the total arithmetically. Sum each category at the end. No rounding by eye, no "about 50".

Workflow

  1. Confirm BASE_URL (resolve redirects).
  2. Read the rubric (see "Reading companion files" below). It contains the 26-criterion table and the required output format.
  3. Read the calibration anchors (same section). They give score brackets and dated reference points.
  4. Score each of the 26 criteria by performing the HTTP probe described in the rubric's "How to check" column. Record evidence per Rule 1.
  5. Verify the E1 gating result. If E1 = 0, prepare the *UNRELIABLE* marker for the total.
  6. Emit both output parts: the human-readable markdown report, then the JSON block. Exact templates are in rubric.md.
  7. Self-validate the JSON before responding: every criterion ID (A1–E5, 26 total) is present, each score ≤ max, and sum(criteria[*].score) exactly equals total_score and each per-category sum. Fix mismatches before finalizing.

Reading companion files

Two companion files live next to this SKILL.md: rubric.md (the 26-criterion table + output templates) and calibration.md (score brackets + measured anchors). You must read both before scoring.

Use the Read tool. Construct the path from the location of this SKILL.md:

  • If the skill is installed at the default location, the files are at .claude/skills/ai-ready-audit/rubric.md and .claude/skills/ai-ready-audit/calibration.md.
  • If you have access to this SKILL.md's full path, replace SKILL.md with rubric.md / calibration.md.
  • If Read fails with file-not-found, the skill is incompletely installed — ask the user to symlink the full skill directory (see the installation note in claude-skills/README.md) rather than copying only SKILL.md.

If you still cannot read the companion files, do not proceed with scoring. Tell the user the skill is incompletely installed and stop.