The Website Specification — Agent Skill

A single source of truth for what a good website does. Ten categories, 128 topics, every item tagged with a status (required, recommended, optional, avoid). This skill bundles all 128 topic pages as local Markdown so the agent can answer offline, plus optional MCP / HTTP routes for the freshest data.

Upstream: <https://specification.website> · Repo: <https://github.com/jdevalk/specification.website>

When to use this skill

Invoke it whenever the user:

• Asks "what should my site have", "is X required", "audit this URL", "what does the spec say about Y".
• Asks about HTML foundations, SEO, accessibility (WCAG), HTTP security headers, well-known URIs (/.well-known/*), agent/AI readiness (llms.txt, MCP, robots.txt, structured data), Core Web Vitals, privacy/consent, error/offline pages, i18n/hreflang.
• Reviews a real site and wants to cite primary standards (WHATWG, W3C, IETF, IANA, WCAG, schema.org) rather than vendor blog posts.
• Needs a tickable checklist of required + recommended items.
• Wants a machine-readable contract for a platform-agnostic audit.

Do not invoke for: writing application logic, choosing a JS framework, generic programming questions unrelated to web platform features.

File layout

specification-website/
├── SKILL.md                      ← this file (overview, routing, statuses, workflows)
├── references/
│   ├── checklist.md              ← full required/recommended/avoid checklist (tickable)
│   ├── topics-index.md           ← every topic with category + status + summary
│   ├── categories/
│   │   ├── foundations.md        ← per-category index, topics grouped by status
│   │   ├── seo.md
│   │   ├── accessibility.md
│   │   ├── security.md
│   │   ├── well-known.md
│   │   ├── agent-readiness.md
│   │   ├── performance.md
│   │   ├── privacy.md
│   │   ├── resilience.md
│   │   └── i18n.md
│   ├── topics/<category>/<slug>.md   ← all 128 full spec pages, with frontmatter
│   ├── llms-index.txt            ← the upstream llms.txt index
│   ├── llms-full.txt             ← every topic concatenated, ~9k lines
│   └── mcp-and-fetch.md          ← how to query the live MCP server / HTTP endpoints

Reading order for an agent:

1. Read references/topics-index.md to locate relevant slugs.
2. Read references/topics/<category>/<slug>.md for each — full body + cited sources.
3. For a broad audit, read references/checklist.md (or one category index) and walk through it.
4. If the user needs the latest version of a topic, follow references/mcp-and-fetch.md to fetch live.

The ten categories

| Slug | Title | Topics | What it covers | |---|---|---|---| | foundations | Foundations | 14 | HTML, head, and document basics every page needs. | | seo | SEO | 13 | Search visibility — robots.txt, sitemaps, canonicals, structured data. | | accessibility | Accessibility | 20 | WCAG-aligned rules so people of all abilities can use the site. | | security | Security | 12 | Headers, transport, and policies that keep visitors safe. | | well-known | Well-Known URIs | 9 | Standard, agreed-upon paths under /.well-known/. | | agent-readiness | Agent Readiness | 18 | Things that make a site legible to AI agents and crawlers. | | performance | Performance | 19 | Core Web Vitals, caching, images, fonts, network behaviour. | | privacy | Privacy | 6 | Consent, signals, and respecting visitor choice. | | resilience | Resilience | 5 | Graceful failure — error pages, offline, redirects. | | i18n | Internationalisation | 12 | Language, locale, direction, and translated content. |

Total: 128 topics.

The status contract

Every topic carries one of four statuses. Never silently upgrade recommended to required.

• required — the platform contract breaks, or a clear class of users is harmed, without it. Lead with these when recommending fixes. Examples: <title>, <meta charset>, HTTPS, image alt, a real 404.
• recommended — a modern site should do it. Examples: CSP, HSTS, structured data, Open Graph, llms.txt.
• optional — depends on context. Examples: image sitemaps, OpenID Configuration, IDN support.
• avoid — outdated, harmful, or superseded. Flag if a site does one. Examples: soft-404, empty links/buttons.

The bar for required is "the platform breaks", not "we strongly suggest".

Cardinal rules (mirroring the upstream contract)

1. Cite primary sources. Every topic has 2–4 sources in its frontmatter (WHATWG, W3C, IETF RFCs, IANA, WCAG, schema.org). Quote those, not the spec page itself.
2. Stay platform-agnostic. Describe outcomes, not implementations. "Set Content-Security-Policy" is in scope. "Add this to next.config.mjs" is not.
3. Be honest about status. Don't promote recommended to required for emphasis.
4. British English in the spec text ("colour", "behaviour", "internationalisation").
5. Section structure. Each topic has: ## What it is, ## Why it matters, ## How to implement, ## Common mistakes, ## Verification (last two optional).

Common workflows

1. "Audit this URL."

1. Read references/checklist.md — start with the Required section.
2. For each item the user (or fetched HTML) is missing, open references/topics/<category>/<slug>.md, quote the cited sources, and propose the fix.
3. For deeper audits, also walk the Recommended section, then category-specific extras (e.g. agent readiness for AI-facing sites, performance for slow sites).
4. If the URL is reachable, fetch it (curl / browser) and check the actual response headers, HTML, robots.txt, sitemap.xml, and /.well-known/* paths against the relevant topics.

2. "Is X required?"

1. grep for the topic slug or title under references/topics/.
2. Read the frontmatter status: field. Report it as-is.
3. Quote the cited sources from frontmatter (WHATWG / W3C / IETF / WCAG ...).

3. "What's required for agent readiness?"

1. Read references/categories/agent-readiness.md — topics are pre-sorted by status.
2. Open each required topic for the rationale and sources.

4. "Why does the spec say X?"

Open references/topics/<category>/<slug>.md, read the body, then quote the sources: block from the frontmatter (primary standards).

5. "Give me the checklist."

Hand the user references/checklist.md verbatim, or filter to one category by reading references/categories/<slug>.md.

6. Fresh data needed (spec changed, source URL dead, new topic)

Follow references/mcp-and-fetch.md. Live MCP endpoint: https://mcp.specification.website/mcp. Per-topic Markdown: https://specification.website/spec/<category>/<slug>.md. Bundled corpus: https://specification.website/llms-full.txt.

Topic frontmatter — what each field means

Every references/topics/<category>/<slug>.md starts with YAML frontmatter:

yaml
---
title: "Human-readable title"
slug: kebab-slug
category: one-of-the-ten
summary: "One-sentence summary used in indexes."
status: required | recommended | optional | avoid
order: 70                       # sort order within the category
appliesTo: [all]                # or e.g. [public-pages], [admin]
relatedSlugs: [other, slugs]
updated: "ISO-8601 timestamp"
sources:
  - title: "RFC 6596 — The Canonical Link Relation"
    url: "https://www.rfc-editor.org/rfc/rfc6596"
    publisher: "IETF"
---

When citing in answers, prefer sources[].url over the spec page's own URL. The spec is a synthesis; the standards are authoritative.

Quick examples

• "Do I need <meta charset>?" → references/topics/foundations/meta-charset.md → status required, cite WHATWG HTML.
• "What goes in /.well-known/security.txt?" → references/topics/well-known/ + references/topics/security/security-txt.md → RFC 9116.
• "How do I make my site AI-agent-friendly?" → references/categories/agent-readiness.md → walk llms.txt, llms-full.txt, robots-for-ai-crawlers, structured data, stable URLs, MCP discovery.
• "What's wrong with empty <a> tags?" → references/topics/accessibility/empty-links-buttons.md → status avoid.
• "Is hreflang required for translated sites?" → references/topics/i18n/hreflang.md.

Licence and attribution

• Spec content (all references/topics/**, references/llms*.txt, references/checklist.md, references/categories/**, references/topics-index.md): © Joost de Valk, licensed CC BY 4.0. Source: <https://github.com/jdevalk/specification.website>.
• Skill packaging files (this SKILL.md, references/mcp-and-fetch.md): MIT.

When citing, use the topic's canonical URL https://specification.website/spec/<category>/<slug>/ and its updated frontmatter field as the "as-of" date. The spec evolves — re-fetch via MCP or HTTP if a topic is more than a few weeks stale.