specification.website

AI agents can query The Website Specification through three separate channels: an open, read-only MCP server at https://mcp.specification.website/mcp (HTTP transport, no authentication), a published Agent Skill that teaches compatible agents when and how to use the spec, and per-page Markdown served via /llms.txt or an Accept: text/markdown request header on any spec URL. All three are documented on the site itself, so the fastest path is to pick the channel your agent already supports rather than building a custom integration.

The three access channels

The MCP server is described as "open" and "read-only, no auth" — the site does not state rate limits, quotas, or uptime guarantees, so treat those as unknown rather than assuming they are unlimited.

Connecting an agent over MCP

The site publishes the exact client configuration, so no discovery step is needed:

{
  "mcpServers": {
    "specification-website": {
      "transport": "http",
      "url": "https://mcp.specification.website/mcp"
    }
  }
}

Input: the JSON block above, placed in your MCP client's server configuration. Action: the client opens an HTTP transport connection to that URL. Expected result: the agent can query the spec's topics through MCP tools without supplying credentials.

If your client expects a different config key or a command-based transport, the site's "Connect MCP" link is the authoritative source — the snippet above is the only form given in the page evidence.

Using the Agent Skill

The site also publishes an Agent Skill, described as teaching "any compatible agent when and how to use it." This matters because an MCP connection alone tells the agent how to fetch spec content but not when it is relevant. The skill supplies that judgement layer.

Practical implication: if your agent framework supports skills, load the Agent Skill alongside the MCP connection rather than relying on the MCP server alone. If your framework has no skill mechanism, the MCP server and the Markdown endpoints still work — you just lose the routing guidance.

Fetching spec pages as Markdown

For agents that do not speak MCP, every spec URL can return Markdown instead of HTML:

• /llms.txt — a published index of the spec in the llms.txt convention.
• Accept: text/markdown — send this header on any spec URL to get that page as Markdown.

Input: an HTTP GET to a spec URL, with Accept: text/markdown set. Action: the server negotiates content type and returns Markdown. Expected result: clean Markdown for that single topic, suitable for chunking into a retrieval index or feeding directly into a context window.

This is the lowest-friction option: no client library, no protocol handshake, just an HTTP request with a header.

What the agent can actually retrieve

The spec covers 173 topics across ten categories, all mapped to external standards (WHATWG, W3C, IETF RFCs, WCAG, MDN). The categories are:

• Foundations — 20 topics (HTML, head, document basics)
• SEO — 14 topics (robots.txt, sitemaps, canonicals, structured data)
• Accessibility — 30 topics (WCAG-aligned rules)
• Security — 20 topics (headers, transport, policies)
• Well-Known URIs — 13 topics (standard paths under /.well-known/)
• Agent Readiness — 22 topics (legibility to AI agents and crawlers)
• Performance — 26 topics (Core Web Vitals, caching, images, fonts, network)
• Privacy — 7 topics (consent, signals, visitor choice)
• Resilience — 8 topics (error pages, offline, redirects)
• Internationalisation — 13 topics (language, localisation)

Each topic is structured as a yes/no checklist item, which makes the output easy for an agent to act on: the agent can retrieve a topic, evaluate the target site against it, and report a pass/fail plus the linked standard.

Choosing between the channels

• Agent already supports MCP → connect the MCP server; add the Agent Skill if your framework loads skills.
• Agent is a plain HTTP client or a RAG pipeline → use /llms.txt to enumerate pages, then Accept: text/markdown per page.
• You want the agent to audit a site → the spec's own "How to use this site" flow is audit → learn → improve, with each item as a yes/no check. Point the agent at the relevant category rather than the whole 173-topic set to keep context manageable.

Common sticking points

• Assuming the MCP server is the only route. It is not — the Markdown endpoints exist precisely so agents without MCP support can still read the spec.
• Skipping the Agent Skill. Without it, a compatible agent may have access to the spec but no trigger telling it to consult the spec during a task.
• Treating the spec as opinion. Every topic links back to a source standard, so when an agent reports a failure, the citation is the thing to check — not the spec page alone.
• Expecting pricing or account details. The page evidence shows no pricing signals and no payment platforms; the MCP server is stated as no-auth, but nothing on the page addresses commercial terms or limits.

If you're new to Ahrefs and want to run your first SEO audit, the fastest path is: open Site Explorer, enter your target URL, review the Overview for a health snapshot, then dig into Organic Keywords, Top Pages, and Site Audit to find specific problems. From there, build a short prioritized to-do list instead of trying to fix everything at once.

This tutorial walks through that workflow using a realistic starting scenario, explains what the numbers mean, and shows how to turn findings into actions.

Before You Start: Pick a Narrow Scope

A common beginner mistake is auditing an entire large website on day one. The reports become overwhelming, and you can't tell which issues matter.

Instead, choose one of these starting points:

• A single important page (your homepage or a key product/service page)
• A small site (under ~50 pages, e.g., a personal blog or small business site)
• One section of a bigger site (e.g., /blog/)

For this tutorial, assume you're auditing a small business site with about 30 pages. The same steps scale up later.

You'll need an Ahrefs account to follow along. Ahrefs offers paid plans, and pricing and feature limits change over time, so check the current Pricing page for what's included in each tier before committing.

Step 1: Enter Your Target in Site Explorer

Site Explorer is Ahrefs' core tool for analyzing any website or URL.

1. Open Site Explorer from the top navigation.
2. In the search box, paste your domain (e.g., example.com).
3. Choose the Exact URL or Domain mode depending on scope. For a full-site view, use Domain or Prefix; for a single page, use Exact URL.
4. Press Enter.

You'll land on the Overview report. Don't try to absorb everything — focus on four numbers first.

Reading the Overview Snapshot

Important caveat: Ahrefs' traffic and keyword numbers are estimates based on its own data. They won't match Google Search Console or your analytics exactly. Treat them as directional, not absolute.

Step 2: See What You Already Rank For

Go to Organic Keywords in the left sidebar. This shows queries where your site appears in search results.

Sort by Traffic (descending) to see which pages bring the most estimated visitors. Then look for:

• Keywords ranking in positions 4–15 — these are often the easiest wins. A small content or on-page improvement can push them onto page one.
• Keywords with high volume but low position — potential opportunities if the topic is relevant.
• Irrelevant keywords — if you rank for something off-topic, it may signal thin or mismatched content.

Write down 5–10 of the position 4–15 keywords. These become your first optimization targets.

Step 3: Find Your Best and Weakest Pages

Open Top Pages. This ranks your URLs by estimated organic traffic.

Look for two things:

1. Your top performers — understand what topics and formats work. Can you create more content like this?
2. Pages with traffic but poor rankings — these may need on-page fixes (title, headings, internal links).

If a page gets zero traffic and targets a topic you care about, it's a candidate for a rewrite or consolidation.

Step 4: Run a Technical Site Audit

Now move to Site Audit. This crawls your site and flags technical and on-page issues.

1. Click Site Audit → New project.
2. Enter your domain and set crawl settings (default is usually fine for a small site).
3. Start the crawl and wait for it to finish.

Once complete, you'll see a Health Score and a list of issues grouped by category.

Which Issues to Fix First

Not all issues are equal. Prioritize in this order:

Ignore low-impact warnings (like minor meta description length) until the big items are handled.

Step 5: Turn Findings Into a To-Do List

You now have raw data. Convert it into a short, actionable list. Example:

1. Fix 3 broken links found in Site Audit.
2. Rewrite title tags on 5 pages with duplicate titles.
3. Improve 4 pages ranking in positions 6–12 by adding missing subtopics and internal links.
4. Remove or update 2 thin pages with no traffic.

Keep the list to 5–10 items max for your first audit. Finishing a short list beats starting a long one.

Common Beginner Mistakes

• Chasing every red flag. Site Audit flags many minor issues. Fix what affects rankings and users first.
• Trusting estimates as exact numbers. Ahrefs data is modeled, not measured from your analytics.
• Auditing a huge site too early. Start small to learn the interface.
• Ignoring search intent. A page can be technically perfect but still fail if it doesn't match what searchers want.
• Forgetting to re-crawl. After fixes, run Site Audit again to confirm improvements.

Where to Go Next

Once your first audit is done:

• Compare with competitors using Site Explorer's Competing Domains and Content Gap reports.
• Track keyword rankings over time with Rank Tracker.
• Explore backlink opportunities in the Backlinks and Link Intersect reports.
• Set up recurring Site Audit crawls so new issues surface automatically.

Your first audit isn't about perfection — it's about building a repeatable habit: enter a target, read the key reports, pick the highest-impact fixes, and act. Do that once a month and your site's health compounds.

The Website Specification is a platform-agnostic, open specification of the technical features a good website should have. It is written for both humans and AI agents, published under the MIT licence, and organised as a checklist of 173 topics across ten categories — from /.well-known/security.txt to WCAG contrast. It is useful if you want a standards-based reference for auditing, learning, or improving a site regardless of what it is built with.

What it actually contains

The spec is a catalogue of technical requirements, not a tutorial series or a product. Each topic is a yes/no checklist item, and each item links back to its source standard — WHATWG, W3C, IETF RFCs, WCAG, MDN, and other bodies defining the modern web. The site states three principles it is built on:

• Standards, not opinions — every topic traces to a source standard.
• Platform agnostic — the spec applies whether you ship WordPress, Drupal, TYPO3, Next.js, Astro, Hugo, a Django app, or plain HTML. Implementation hints follow the spec, not the other way round.
• Built in the open — every page has an "Edit on GitHub" link, PRs are welcome, and sources are credited on every page.

The site reports 869 stars on GitHub and notes a full changelog, with recent additions including auth.md agent registration guidance, a page on status messages, and a page on /.well-known/gpc.json.

The ten categories

How to use it

The site describes a three-step loop:

1. Audit — run the checklist against your site, or let your agent do it. Each item is a yes/no.
2. Learn — open any item for what it is, why it matters, and how to implement it.
3. Improve — fix what is missing, then re-check.

There is also a "Get the checklist" entry point alongside the full topic browser.

Agent access

The whole spec is exposed for machine consumption:

• An open MCP server (read-only, no auth) at https://mcp.specification.website/mcp, configured over HTTP transport.
• A published Agent Skill that teaches a compatible agent when and how to use the spec.
• Per-page Markdown via /llms.txt and Accept: text/markdown on any spec URL.

Example MCP configuration as given on the site:

{
  "mcpServers": {
    "specification-website": {
      "transport": "http",
      "url": "https://mcp.specification.website/mcp"
    }
  }
}

When it fits your needs

Use it if you want a vendor-neutral, standards-linked checklist to audit a site or to brief an agent on web requirements. It suits teams working across multiple stacks, since the same spec applies to all of them. It is less suited to someone looking for framework-specific how-to guides or opinionated design advice — the site explicitly positions implementation hints as following the spec rather than leading it.

The Website Specification (specification.website) is built on three stated principles: it follows standards rather than opinions, it is platform-agnostic, and it is built in the open. Together these principles explain why the spec is structured as a set of yes/no checklist items that link back to authoritative sources, and why it applies the same way whether you ship WordPress, Drupal, TYPO3, Next.js, Astro, Hugo, a Django app, or plain HTML.

Principle 1: Standards, not opinions

Every topic in the spec links back to the source standard that defines it. The site names WHATWG, W3C, IETF RFCs, WCAG, MDN, and "the organisations defining the modern web" as the references behind its pages.

What this means in practice:

• Each item is framed as a yes/no check, so you can audit against it rather than debate it.
• The justification for an item comes from an external standard, not from the site's own preference.
• Sources are credited on every page.

For example, an accessibility item about contrast traces back to WCAG rather than to a design opinion, and a security header item traces back to the relevant IETF RFC or W3C document.

Principle 2: Platform agnostic

The spec describes technical features a website should have, independent of the tool used to build it. The site explicitly lists WordPress, Drupal, TYPO3, Next.js, Astro, Hugo, a Django app, and plain HTML as equally valid implementations.

The stated relationship between spec and implementation is one-directional: "Implementation hints follow it, not the other way round." In other words, the spec is not derived from what any particular CMS or framework happens to do by default — implementation guidance is written to serve the spec, not to describe one platform's behaviour.

This is what makes the checklist reusable across a portfolio of sites built on different stacks: the same yes/no items apply, and only the "how to implement" step changes.

Principle 3: Built in the open

The spec is published under an MIT licence and developed publicly. Two concrete signals support this:

• Every page has an "Edit on GitHub" link, and pull requests are welcome.
• Sources are credited on every page.

The site also reports a public change history, with a full changelog and dated additions — for example, additions on 30 September 2026 (auth.md agent registration guidance), 25 September 2026 (a page on status messages), and 24 September 2026 (a page on /.well-known/gpc.json). A visible changelog is consistent with the open-development principle: you can see what changed and when.

How the principles shape the spec's scope

The spec organises its 173 topics into ten categories, described as "mapped to widely-accepted standards":

The range — from /.well-known/security.txt to WCAG contrast — illustrates the standards-first approach: each category maps onto an existing body of standards (WHATWG/W3C for foundations, WCAG for accessibility, IETF RFCs for well-known URIs and security, Core Web Vitals for performance) rather than onto a vendor's feature set.

What the principles imply for you

• If you want a checklist you can defend to a client or reviewer, the standards-first principle means each item has an external citation you can follow.
• If you run multiple sites on different platforms, the platform-agnostic principle means one checklist covers all of them; only the fix differs.
• If you need to verify or challenge an item, the open-build principle gives you the page's edit link and credited sources.

The spec is also designed to be consumed by agents, not only humans: the whole spec is available as an open, read-only MCP server with no authentication, plus a published Agent Skill, per-page Markdown via /llms.txt, and Accept: text/markdown on any spec URL. That agent-readiness is itself an application of the same principles — a standard interface, no platform lock-in, and openly documented access.

The Website Specification (specification.website) organises its content into ten categories covering 173 topics in total. Each category maps to widely-accepted standards, and every topic links back to its source standard — WHATWG, W3C, IETF RFCs, WCAG, or MDN. The categories are: Foundations, SEO, Accessibility, Security, Well-Known URIs, Agent Readiness, Performance, Privacy, Resilience, and Internationalisation.

The ten categories at a glance

Accessibility (30) and Performance (26) are the largest categories; Privacy (7) and Resilience (8) are the smallest.

What each category actually contains

Foundations (20 topics)

The HTML, head, and document basics every page needs. This is the layer that everything else builds on — document structure, metadata, and the core markup decisions that apply regardless of platform.

SEO (14 topics)

Search visibility concerns: robots.txt, sitemaps, canonical URLs, and structured data. These are the signals that determine how search engines discover, index, and present your pages.

Accessibility (30 topics)

WCAG-aligned rules so people of all abilities can use the site. The excerpt specifically cites WCAG contrast as an example of the kind of detail covered here.

Security (20 topics)

Headers, transport, and policies that keep visitors safe. The excerpt names /.well-known/security.txt as one example topic in this area.

Well-Known URIs (13 topics)

Standard, agreed-upon paths under /.well-known/. These are the conventional locations that other systems and tools expect to find — for example /.well-known/security.txt and /.well-known/gpc.json (the latter added 24 September 2026).

Agent Readiness (22 topics)

Things that make a site legible to AI agents and crawlers. The spec itself practises what it preaches here: it publishes an open MCP server (read-only, no auth), an Agent Skill, per-page Markdown via /llms.txt, and supports Accept: text/markdown on any spec URL. Recent additions include auth.md agent registration guidance (30 September 2026).

Performance (26 topics)

Core Web Vitals, caching, images, fonts, and network behaviour. This is the second-largest category and covers the technical delivery side of a site.

Privacy (7 topics)

Consent, signals, and respecting visitor choice. The smallest category alongside Resilience.

Resilience (8 topics)

Graceful failure — error pages, offline behaviour, and redirects. What happens when things go wrong.

Internationalisation (13 topics)

Language, localisation, and related concerns for sites serving multiple languages or regions.

How the topics are structured

Each topic is a yes/no checklist item. For every item you get three things:

1. What it is — the feature or requirement in plain terms.
2. Why it matters — the rationale, linked to the source standard.
3. How to implement it — implementation hints that follow the spec rather than any particular platform.

The spec is explicitly platform-agnostic: whether you ship WordPress, Drupal, TYPO3, Next.js, Astro, Hugo, a Django app, or plain HTML, the spec stays the same and implementation hints follow it, not the other way round.

Where to start

If you want to work through the categories systematically, the spec's own three-step flow is:

1. Audit — run the checklist against your site, or let your agent do it. Each item is a yes/no.
2. Learn — open any item for what it is, why it matters, and how to implement it.
3. Improve — fix what's missing, then re-check.

The full topic list is browsable at specification.website, and the project is built in the open under an MIT licence with every page carrying an "Edit on GitHub" link.