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

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.

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.

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.

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.