AI Instruct

Drop-in guides for your AI assistant covering the domains most developers Google when building: deployment, analytics, SEO, accessibility, and more.

npx ai-instruct init

The CLI detects your AI tool (Claude Code, Cursor, Copilot, Windsurf), lets you pick which guides to add, downloads them to ai-docs/, and adds the right reference lines to your config file automatically.

Claude Code users can also install the guides as native skills, either via npx ai-instruct init --skills or as a one-command plugin install.

Guides

| Guide | File | Description | |-------|------|-------------| | Deploying a Static SPA on AWS | aws-spa-deployment-guide.md | Deploying a static single-page app (React/Vite) on AWS - Amplify hosting, custom domains, CDK backend with API Gateway + Lambda, SES email, CORS, and environment variables. | | Google Analytics 4 Implementation | google-analytics-guide.md | Google Analytics 4 (GA4) implementation - installation (gtag.js and GTM), event tracking, user properties, e-commerce, Consent Mode v2, and debugging. | | SEO, LLMO & Agent-Readiness | seo-llmo-guide.md | SEO, LLMO (Large Language Model Optimization), and agent-readiness for public sites - meta tags, Open Graph, JSON-LD, llms.txt, robots.txt with Content-Signal, sitemaps, Markdown content negotiation, Link headers, and the Agent Skills index. Scored by isitagentready.com. | | Web Accessibility | web-accessibility-guide.md | WCAG 2.2 AA implementation - semantic HTML, keyboard navigation, ARIA, forms, color contrast, focus management, motion, and testing with automated tools and screen readers. | | Web Performance | web-performance-guide.md | Core Web Vitals (LCP, CLS, INP), image and font optimization, JavaScript bundle size, CSS build size, CDN caching, third-party JavaScript impact, and validation tools. |

How to Use

The guides are written to be read by both humans and AI models. There are five main ways to use them:

0. CLI setup (recommended)

npx ai-instruct init

Run in your project root. The CLI handles detection, download, and config file updates automatically.

Claude Code: install as skills

If you use Claude Code, you can install the guides as native skills instead of referencing them from CLAUDE.md. Each skill has a description that tells Claude when to load it, so the guide content only enters context when it is actually relevant (a deployment task pulls in the AWS skill, a UI task pulls in the accessibility skill, etc.). This keeps your base CLAUDE.md lean and avoids loading every guide on every turn.

npx ai-instruct init --skills          # writes to .claude/skills/  (project scope, commit to share)
npx ai-instruct init --skills --user   # writes to ~/.claude/skills/ (personal, all your projects)

Project scope is the default and is the right choice when the guides apply to one specific project. Use --user for guides you want active across every project you work on.

Claude Code: install as a plugin

ai-instruct is also published as a Claude Code plugin bundling all 5 guides as skills. The repo is its own marketplace, so you can install everything in two commands inside Claude Code:

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

After installing, the skills become available as /ai-instruct:seo-llmo, /ai-instruct:web-accessibility, etc., and trigger automatically based on what you ask Claude to do. Update with /plugin update ai-instruct.

Use the plugin if you want one-command install and automatic updates. Use --skills (above) if you prefer to commit the skill files into your own repo for the team to share, or if you want to pick which skills to install.

1. Paste into chat

Copy a guide's contents (or a relevant section) and paste it directly into your AI chat before asking your question. Best for one-off tasks.

2. Reference from chat (on-demand, no config needed)

Download the guides to your project with npx ai-instruct init, then point your assistant directly to the ai-docs/ folder in your chat. The assistant reads the guide and applies it for that session - no permanent instructions file setup required.

| Assistant | How to reference a guide in chat | |-----------|----------------------------------| | Claude Code | @ai-docs/seo-llmo-guide.md in the chat, or ask: "Read ai-docs/seo-llmo-guide.md and implement the SEO recommendations" | | Cursor | @ai-docs/seo-llmo-guide.md in the chat composer | | GitHub Copilot | #file:ai-docs/seo-llmo-guide.md in the chat | | Windsurf | @ai-docs/seo-llmo-guide.md in the chat |

Good for one-off tasks where you don't want the guide loaded on every session. For many guides in this repo - deployment, analytics setup, performance optimization - this is not just the easiest approach but the right one: you implement it once and you're done.

3. Add to your project's AI instructions file (recommended)

Most AI coding assistants read a persistent instructions file from your project root. Download the relevant guide(s) into your project and reference them from your instructions file - the assistant will have the context automatically on every session.

| Assistant | Instructions file | How to reference a guide | |-----------|------------------|--------------------------| | Claude Code | CLAUDE.md | Add a line like Read seo-llmo-guide.md for SEO/LLMO practices. | | Cursor | .cursor/rules/ (one .mdc file per rule) or .cursorrules | Paste guide contents into a new .mdc file in .cursor/rules/ | | GitHub Copilot | .github/copilot-instructions.md | Paste guide contents or add See seo-llmo-guide.md for SEO context. | | Windsurf | .windsurfrules | Paste guide contents or reference the file path | | Aider | Pass with --read flag | aider --read seo-llmo-guide.md | | Base44 | Paste into chat | Copy the relevant guide and paste it into your Base44 chat before describing your task | | Lovable | Paste into chat | Copy the relevant guide and paste it into your Lovable chat before describing your task |

Best practices for instruction files:

• Keep guides as separate files rather than pasting everything into one giant instructions file - it's easier to update individual guides and keeps the instructions file readable
• Only include guides relevant to your project to avoid unnecessary context
• Put guides in a dedicated folder (e.g. ai-docs/) and reference them from your instructions file
• When a guide is updated in this repo, re-download it to get the latest practices

4. Global AI assistant instructions

Some assistants support a global (user-level) instructions file that applies to all projects. Useful for guides you always want active.

| Assistant | Global instructions location | |-----------|------------------------------| | Claude Code | ~/.claude/CLAUDE.md, or install guides as user-scope skills with npx ai-instruct init --skills --user (writes to ~/.claude/skills/) | | Cursor | Settings, Rules for AI, User Rules | | GitHub Copilot | Not supported (project-level only) |

Contributing

Pull requests are welcome - see CONTRIBUTING.md for guide format and writing guidelines. You can:

Building your own AI instruction guides for a different domain? Use this repo as a template to get the folder structure, CONTRIBUTING guidelines, and CLI wired up from the start.

• Add a new guide - create a focused .md file on a specific topic (deployment, accessibility, performance, auth, etc.)
• Update an existing guide - fix outdated information, add missing patterns, or improve clarity
• Fix errors - typos, broken examples, wrong commands

Guidelines for new guides

• Keep guides focused on a single topic
• Start with a "Before You Start" section - plain-English questions that let an AI assistant tailor its output (see CONTRIBUTING.md)
• Write for an audience that may not have deep coding experience
• Include working code snippets and real commands
• Note the date/context for time-sensitive information (e.g. "as of 2026")
• Use tables and checklists where appropriate

License

Apache 2.0 - see LICENSE. Free to use, modify, and redistribute.