ai-instruct — плагин для Claude Code: веб-гайды и установка

<div align="center">

# AI Instruct

**Turn your AI assistant into a senior web developer. Production-ready guides for SEO, performance, agent-readiness, and more.**

[![npm version](https://img.shields.io/npm/v/ai-instruct?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/ai-instruct)
[![npm downloads](https://img.shields.io/npm/dm/ai-instruct?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/ai-instruct)
[![GitHub stars](https://img.shields.io/github/stars/ziniman/ai-instruct?style=for-the-badge&logo=github&logoColor=white&color=181717)](https://github.com/ziniman/ai-instruct/stargazers)
[![license](https://img.shields.io/badge/license-Apache%202.0-blue?style=for-the-badge)](https://github.com/ziniman/ai-instruct/blob/main/LICENSE)
[![last commit](https://img.shields.io/github/last-commit/ziniman/ai-instruct?style=for-the-badge&logo=github&logoColor=white&color=181717)](https://github.com/ziniman/ai-instruct/commits/main)

```sh
npx ai-instruct init
```

</div>

Each guide is a deep reference on one domain - the real-world patterns, production decisions, and gotchas that take experience to get right. Drop them into your project and your AI assistant gets that domain expertise immediately, without extra prompting.

The CLI handles setup automatically: detects your tool (Claude Code, Cursor, Copilot, Windsurf), downloads the guides you pick, and wires up the right config references so your assistant loads them on every session.

Claude Code users can also install as native [skills](https://docs.claude.com/en/docs/claude-code/skills) or a one-command [plugin](#claude-code-install-as-a-plugin) - guides trigger automatically based on what you're working on, keeping your base context lean.

## Guides

| Guide | File | Description |
|-------|------|-------------|
| Deploying a Static SPA on AWS | [aws-spa-deployment-guide.md](./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-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-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](https://isitagentready.com/). |
| Web Accessibility | [web-accessibility-guide.md](./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](./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)

```sh
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](https://docs.claude.com/en/docs/claude-code/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. Long guides are split further: the skill's `SKILL.md` holds the Section 0 questions and an index, and Claude reads only the `references/` files for the sections that apply.

```sh
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](https://docs.claude.com/en/docs/claude-code/plugins) 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](./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](https://github.com/ziniman/ai-instruct/generate) 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](./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](./LICENSE). Free to use, modify, and redistribute.