Website Specification Review: A Modern Web Checklist

A new resource called The Website Specification is making rounds on Hacker News: a structured checklist of everything a modern website should include. From required HTML tags to optional features like /.well-known/change-password and color scheme hints, it aims to be a one-stop reference for building robust, future-proof sites. The community response has been mixed—appreciation for its comprehensiveness, skepticism about its more speculative sections, especially the "Agent Readiness" category aimed at AI agents. After decades of building websites, I find this spec both useful and imperfect. Here's what you need to know.

What Is The Website Specification?

The Website Specification is an openly editable document hosted on GitHub that categorizes website requirements into five levels: Required, Strongly Recommended, Recommended, Suggested, and Optional. It covers everything from basic HTML structure (doctype, title tag, meta viewport) to advanced topics like security headers, performance budgets, and—most controversially—"Agent Readiness" (tags and endpoints designed for AI crawlers and agents).

The authors balance formal standards (like requiring the <title> element per the HTML spec) with modern best practices (like enforcing HTTPS and setting a color scheme meta tag). The result is a pragmatic but opinionated guide that even seasoned developers admit teaches them something new. One commenter noted: "As someone who's been making websites for 30 years, it's amazing to still be picking up some of the basics."

Sections like /.well-known/ resources are particularly well-received—many developers didn't know about standard endpoints for change passwords, security.txt, or DMARC reporting. The spec documents these clearly, making it easy to audit your own site.

HN Community Debate: Agent Readiness and Other Concerns

With 60 points and 15 comments, the HN thread shows a split between admiration and wariness about its "Agent Readiness" content. The top comment captures the sentiment perfectly:

"Agent Readiness" will likely age as well as "Web 4.0 Blockchain Integration" has. [...] requiring special allowances from sites undermines the whole point, and such things will only end up used by bad actors to mismatch what agents see to what humans see, and so will be intentionally ignored.

AI agents are still an emerging, undefined space, and adding site-level hooks for them feels premature. Another commenter pointed out that the spec mixes genuine requirements (like title tag) with opinionated recommendations (like HTTPS), which can confuse beginners: "It looks like there are some features noted as 'required' that are actually required by the spec, and others that are required by opinion."

Others simply found it useful: "This is pretty cool, didn't even know of half the options under well-known urls." The discussion also highlighted gaps—big sites don't even implement /.well-known/change-password—showing the gap between ideal and reality.

Web Development Checklist: Use It as a Reference, Not a Rulebook

I find The Website Specification valuable as a checklist, not a strict standard. The web evolves fast, and having a curated list of what matters today is useful—but any such list is a snapshot, not permanent truth. The "Agent Readiness" section is a prime example: it's built on speculation about how AI agents will interact with sites, and history shows that premature standardization often backfires (remember <blink> or <marquee>?). For now, deprioritize those items unless you have clear use cases.

The strength lies in the boring, proven stuff: proper doctype, viewport meta tag, canonical URLs, security headers, robots.txt, sitemap.xml, and standard /.well-known/ paths. These are well-documented, widely supported, and directly improve discoverability, security, and user experience. The spec's organization makes it easy to run through your site and catch missing pieces.

Beginners could easily mistake opinion for law. The spec marks HTTPS as "Required," and while I strongly agree with the recommendation, it's not a formal requirement of the web platform. A clearer distinction between "required by the HTML spec" and "strongly recommended by this spec" would help.

Applying the Website Specification to Your Site

If you maintain a public website, use The Website Specification effectively:

1. Audit your site against Required and Strongly Recommended levels. These cover semantic HTML, accessibility basics, HTTPS, SEO meta tags, and essential /.well-known/ endpoints. For example, add robots.txt and a sitemap.xml if you haven't.

2. Implement the most useful /.well-known/ URIs. The spec lists change-password, security.txt, and dnt-policy.txt. Start with change-password—it's simple and helps users reset passwords via password managers:

<!-- In /.well-known/change-password -->
<!DOCTYPE html>
<html>
<head>
  <title>Redirecting...</title>
  <meta http-equiv="refresh" content="0; url=/account/change-password">
</head>
</html>

3. Add security headers like Content-Security-Policy, X-Content-Type-Options, and Referrer-Policy. The spec's security section is a great starting point—but tailor it to your site's needs. For reference, see MDN's CSP guide and web.dev's security headers guide.

4. Skip the Agent Readiness section for now. Focus on making your site work well for humans and traditional search engines. When agents become reliable, you can revisit.

5. Use the spec as a reference, not a rulebook. Cross-reference with MDN Web Docs or actual W3C specs to understand why something is recommended.

Final Takeaway: Website Specification as a Resource

The Website Specification is a solid resource to keep in your bookmarks. Run through it quarterly to catch new best practices. If you're building internal tools or prototypes, you can safely ignore most of it (aside from basic HTML structure and HTTPS). The real value is in the well-known URIs and security headers; the agent stuff is noise. Use it, but don't worship it.