---
name: tcsenpai/specification-website
source: https://app.decimal.ai/s/tcsenpai-specification-website@1/SKILL.md
source_sha256: 1a7d78e55ff7
---

# 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.