v3.0.0 - Progressive disclosure for skills: SKILL.md + references/ (v3.0.0)

• all skills: Skills now use progressive disclosure: SKILL.md keeps the guide header, Section 0, and an index with a one-line "when to read" summary per section, and every other section moves to references/<slug>.md. A triggered skill loads about 50 lines instead of up to 1,370, in line with the Agent Skills 500-line guidance. Cross-section links are rewritten to the right reference file
• aws-spa-deploy, seo-llmo: "See above/below" pointers that now cross reference files are links, so they still work when a section is read on its own. Guide content is otherwise unchanged and the guides remain single files
• CLI: init --skills installs the whole skill, including references/, and swaps the generated files in only once every file is written, so a failed install never leaves a half-updated skill; other files in the skill folder are kept. The Done message reports failures, and the GitHub fallback prints build warnings
• CI: Fails on untracked files under skills/ (not only modified ones) and runs a new check:skills validator for line limits, broken links or anchors, and orphaned reference files

v2.1.0 - v2.1.0: Refresh all five guides for October 2026

aws-spa-deploy - Fixed a build cache that never worked (npm ci deletes node_modules), wrong CORS guidance for HTTP API, and stale SES/ACM/Free Tier costs; moved to Node.js 24 (CDK 2.224.0+), added the function URL 403 permission change, SESv2 contact-form handler, security headers, and corrected SES sandbox and production-access facts

google-analytics-4 - Fixed SPA advice that double-counted page views (history-based page views stay on even with send_page_view: false); conversions renamed to key events with current Admin paths; corrected internal traffic filter steps and added hostname filters; Consent Mode now covers Switzerland, basic vs advanced, and the June 2026 Google Ads change; removed false BigQuery backfill and attribution claims; added Google tag gateway and the GTM gtag.config change

seo-llmo - Rebuilt AI crawler guidance (GPTBot and ClaudeBot are training crawlers; AI search uses OAI-SearchBot, Claude-SearchBot and others; Google-Extended does not control AI Overviews); FAQ rich results retired and llms.txt not used by Google Search; A2A Agent Card v1.0, Agent Skills index v0.2.0, and MCP discovery via SEP-2127 Server Card and AI Catalog; ORA moved to ora.ai; "explicit absence" now declares missing A2A/MCP in llms.txt with Markdown 404s instead of spec-invalid stub files

web-accessibility - Fixed Focus Appearance mislabelled as 2.4.11 AA (it is 2.4.13 AAA) and added Focus Not Obscured; audio CAPTCHA no longer presented as passing Accessible Authentication; recalculated contrast ratios; added ADA Title II deadlines, precise EAA scope and EN 301 549 status; native <dialog> pattern and Baseline table for new HTML features; WebAIM 2026 screen reader data

web-performance - Next.js 16 APIs (fetchPriority/preload, proxy.ts, 'use cache'); fixed a GTM snippet that broke page view triggers, a backwards font-display: swap description, and an invented Vite flag; Lighthouse 13 insights and weights; fetchpriority vs preload rule; no-cache without no-store for bfcache; AVIF Baseline and JPEG XL status; added zstd compression and bfcache/Speculation Rules

all skills - Rewrote skill descriptions to match the refreshed content; seo-llmo description now under the 1024-character Agent Skills limit; added a marketplace description

v2.0.5 - Web performance: preconnect, script loading, fetchpriority, CSP/inline CSS

What's new in v2.0.5

Four new sections added to web-performance, all additive - no existing content changed.

preconnect and dns-prefetch for third-party origins

Decision rule: preconnect for origins that load within 2 seconds, dns-prefetch for everything else. Explains the cost of each step avoided (DNS, TCP, TLS), the crossorigin requirement for font origins (omitting it causes two connections instead of one), and the over-hinting risk (too many preconnects compete for bandwidth and may worsen the metrics they're meant to fix).

Script loading strategies

Decision table mapping each script type (GTM, analytics, error monitoring, A/B testing, chat, video, session replay) to the correct loading attribute. Before/after showing Google Tag Manager moved from its default blocking inline snippet to a declarative defer with a synchronous dataLayer initialization - the most common tag manager mistake. requestIdleCallback pattern for non-urgent scripts. Notes that analytics and tag managers are the most common cause of unused JavaScript and long tasks on otherwise well-optimized pages.

fetchpriority and the LCP image

Clarifies the distinction between loading="eager" (controls when the fetch starts) and fetchpriority="high" (controls scheduler priority among concurrent fetches). They are complementary - an eager image can still lose the priority race against render-blocking CSS. Adds a 5-point diagnostic checklist for when PageSpeed still reports slow LCP after the obvious preload hint is in place: render-blocking wrappers, preload in body instead of head, missing fetchpriority, late-hydrating client components, TTFB.

CSP interaction with inlined critical CSS

Silent failure mode: inlining CSS for LCP and then discovering the CSP blocks the <style> block at runtime - no build-time warning, the page renders completely unstyled. Covers all three mitigation approaches in order of security: 'unsafe-inline' (easiest), per-request nonce (recommended for strict CSP), SHA-256 hash (works for static content).

Checklist additions

Four new pre-deploy checklist items covering all of the above.

v2.0.4 - Semantic HTML, API docs link, onboarding friction

What's new in v2.0.4

Three remaining ORA gap fixes in seo-llmo.

Semantic HTML structure (Discovery - 2pts)

New subsection in SPA Considerations explaining that AI vector stores parse document structure to chunk content - not just measure text volume. Covers heading hierarchy, landmark elements (<main>, <nav>, <aside>), semantic lists and tables, and descriptive attributes. Includes curl checks to verify heading count and <main> presence.

API/docs linked from homepage HTML (Identity - 3pts)

ORA checks for a visible <a> link from your homepage HTML to your developer documentation as a separate check from the Link: response header. Added a note to the Link headers section explaining both are required independently, with an HTML example and a fallback suggestion for sites with no public API.

Agent onboarding friction (Auth & Access - 2pts)

Updated the llms.txt Agent instructions example to include two new lines: self-serve signup availability and API access terms. Agents use these declarations to correctly route users - without them, an agent may tell a user to "just sign up" when no self-serve flow exists. The note explains the reasoning so developers understand why these lines matter.

v2.0.3 - Explicit absence principle, A2A Agent Card, MCP discovery, SoftwareApplication schema

What's new in v2.0.3

Core philosophy: explicit absence beats silence

Agent-facing files should declare when a feature doesn't apply to a site - not be absent. When an agent requests pricing.md and gets a 404, it can't tell whether the product is free, pricing is hidden, or the file just wasn't created. This release applies that principle across every agent-facing file in the guide.

New content in seo-llmo

SoftwareApplication JSON-LD - Added the schema type for SaaS/app sites. Without it, agents can identify that an organization exists but not what type of product you have. Covers applicationCategory, offers block for free/paid/contact-based pricing.

A2A Agent Card - /.well-known/agent-card.json is now in-scope for all sites (moved out of the "out of scope" section). Two templates: full spec for sites with agent-callable skills, and a content-site stub with empty capabilities for sites that just want to close the discovery loop.

MCP server discovery - How to declare your MCP server (or its absence) in llms.txt and via /.well-known/mcp.json. Empty stub for sites with no MCP server.

Explicit stubs for pricing.md - Templates for free products and contact-based pricing, not just paid tiers.

agent.json with "api": null - Updated to explicitly declare no programmatic API for content sites, plus OpenAPI example for sites that have one.

Agentic search discoverability - Callout explaining that agentic search (the highest-scoring ORA criterion at up to 12 points) is a content strategy concern - topical authority through tutorials, comparisons, use-case pages. Technical baseline: product name in H1/title, developer resources listed in llms.txt.

Cross-platform consistency validation - Check that your llms.txt description, agent.json description_for_model, JSON-LD description, and meta tags all describe the same product consistently.

Static Hosting Notes - Added agent-card.json and mcp.json to the CloudFront/S3 content-type table.

v2.0.2 - Expanded agent-readiness from ORA analysis

What's new

Expanded agent-readiness coverage in the seo-llmo skill and guide, driven by analysis of ORA (ora.run) scan results alongside the existing Cloudflare isitagentready.com checks.

Added

Structured data

• sameAs entity linking with Wikidata and Wikipedia entries for AI brand disambiguation
• Speakable schema for voice assistant and AI readout
• contactPoint and address fields on Organization JSON-LD

llms.txt

• Agent instruction block (## Agent instructions) explaining how agents should interact with your site
• Modular per-section llms.txt (/docs/llms.txt, /api/llms.txt, /blog/llms.txt)

robots.txt

• NLWeb Schemamap: directive pointing agents at structured data feeds

Agent-Readiness section (new subsections)

• Trust anchor pages - /about, /contact, /privacy with 500+ chars each
• pricing.md - plain markdown pricing file at site root
• /.well-known/agent.json discovery file with template
• AGENTS.md for GitHub repos
• ?mode=agent lightweight agent view with edge function pattern

SPA / content

• Content efficiency: text:HTML ratio 5%+ target with measurement commands
• Explicit H1 + 500 chars of raw HTML text requirement

Validation

• ORA scanner added alongside isitagentready.com, including badge snippet

Install: npx ai-instruct init or /plugin update ai-instruct inside Claude Code.

v2.0.1

What's new

Support for agent-readiness checks from Cloudflare's isitagentready.com scanner, added to the seo-llmo skill and guide.

Added

• Content-Signal directive in robots.txt (search / ai-input / ai-train permissions)
• Markdown content negotiation - Cloudflare's Markdown for Agents feature plus a drop-in CloudFront Function for non-Cloudflare static sites (S3, Amplify)
• Link response headers (RFC 8288) with per-platform setup (CloudFront, Amplify, Netlify, Vercel, Nginx)
• Agent Skills index at /.well-known/agent-skills/index.json
• Validation curl snippets for agent-readiness
• Static hosting content-type rows for *.md and the agent-skills index

Changed

• Skill description widened to trigger on "agent-readiness", "isitagentready.com", and "Cloudflare Markdown for Agents"
• Section 0 goal question updated to include autonomous agents as a distinct audience
• Guide renamed in README to "SEO, LLMO & Agent-Readiness"

Out of scope (by design)

MCP Server Card, WebMCP, OAuth discovery, OAuth Protected Resource Metadata, A2A Agent Card, and commerce (x402/UCP/ACP) apply to sites exposing programmatic actions, not content/marketing sites. The guide links to the specs for readers building those.

Install: npx ai-instruct init or /plugin update ai-instruct inside Claude Code.

v2.0.0

v2.0.0 - Plugin and skills distribution

ai-instruct is now also a Claude Code plugin. The same five guides you have been adding to CLAUDE.md or ai-docs/ can now be installed in one command and auto-load only when relevant to the task.

What's new

Claude Code plugin - install all five guides as namespaced skills:

/plugin marketplace add ziniman/ai-instruct
/plugin install ai-instruct@ai-instruct

Skills mode in the CLI - install as skills without the plugin system:

npx ai-instruct init --skills          # writes to .claude/skills/  (project scope)
npx ai-instruct init --skills --user   # writes to ~/.claude/skills/ (user scope)

Five skills, auto-triggered by Claude Code:

• ai-instruct:seo-llmo - meta tags, JSON-LD structured data, llms.txt, AI crawlers (GPTBot, ClaudeBot, PerplexityBot)
• ai-instruct:web-accessibility - WCAG 2.2 AA, ARIA, keyboard navigation, color contrast, screen reader testing
• ai-instruct:web-performance - Core Web Vitals (LCP, CLS, INP), image and font optimization, bundle size, CDN caching
• ai-instruct:aws-spa-deploy - Amplify, CDK, Lambda, API Gateway, SES, CORS
• ai-instruct:google-analytics-4 - gtag.js, GTM, event tracking, e-commerce, Consent Mode v2

Each skill description tells Claude when to load it (accessibility triggers on any UI work, SEO triggers before launch, etc.), so all five ship together without bloating always-on context.

Breaking changes

None. The existing npx ai-instruct init flow is unchanged. The major version bump marks the significance of adding plugin distribution, not a compatibility break.

Single source of truth

The canonical content still lives in the standalone *-guide.md files at the repo root, so the same guides remain usable in Cursor, Copilot, Windsurf, Aider, and any other AI coding assistant. The skills are generated from those files at build time, ensuring no drift between formats.

For maintainers

The release process is documented in CLAUDE.md. npm version automatically syncs versions across package.json, plugin.json, and marketplace.json, and rebuilds the skills/ directory.

1.1.1

Add Product schema section to SEO guide for AI shopping visibility.

1.1.0 - Web Performance Guide

What's new

New guide: Web Performance

A comprehensive reference for measuring and improving web performance:

• Core Web Vitals (LCP, CLS, INP) - thresholds, what each measures, field vs. lab data
• LCP optimization - preload hints, fetchpriority, server response time, render-blocking resources
• Image optimization - AVIF/WebP conversion, responsive images, lazy loading
• Font loading - preconnect, font-display, self-hosting vs. Google Fonts
• JavaScript bundle size - code splitting, tree shaking, dynamic imports
• Legacy JavaScript and browser targets - browserslist, modern bundle output
• Third-party JavaScript - deferring, facades, impact measurement
• CSS build size - Tailwind purging, unused styles
• CDN and caching - cache headers, immutable assets, invalidation strategies
• Measurement and validation tools - PageSpeed Insights, Lighthouse, Search Console, WebPageTest

Also in this release

• Web Accessibility guide updated with color contrast depth: rgba pitfalls, Tailwind slate palette reference, and brand color token patterns
• New usage method in README: on-demand chat referencing (point your AI to ai-docs/ without permanent config)
• .planning/ added to .gitignore
• npm package cleaned up with files whitelist (no dev artifacts published)