ai-rulez

---

The Problem

Every AI coding tool wants its own config: Claude needs CLAUDE.md, Cursor wants .cursor/rules/, Copilot expects .github/copilot-instructions.md. Each has different formats, frontmatter, and directory conventions. If you use more than one tool, you're maintaining duplicate rules that inevitably drift apart.

The Solution

Write your rules, context, skills, agents, and commands once in .ai-rulez/. Run generate. Get native configs for every tool you use.

npx ai-rulez@latest init && npx ai-rulez@latest generate

Prefer the project-level .config/ convention? ai-rulez auto-discovers .config/ai-rulez/ as well, and ai-rulez init --config-dir .config/ai-rulez scaffolds it.

ai-rulez generates correct, tool-native output for 14 platforms: Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Continue.dev, Codex, OpenCode, Hermes, Amp, Junie, Antigravity, and Xum. Each preset respects the target tool's conventions — proper frontmatter, directory structure, file extensions, agent formats.

For a tool that isn't built in, a custom preset can point at a declarative provider spec (provider = ".ai-rulez/providers/my-tool.toml") and get the same full feature set as a built-in — root instructions file, skills/agents/commands, per-agent frontmatter, and MCP sidecars. See Custom Presets.

Set agents_md = true to write AGENTS.md and .agents/skills/ once for the tools that read them (Codex, Cursor, Copilot, Gemini, Claude through an @AGENTS.md shim, and more) instead of one copy per tool. Off by default. See docs/agents-md.md.

Generate Plugins, Not Just Config

ai-rulez doesn't only write config into your repo — it also packages your project as distributable plugins. Run ai-rulez generate --plugin and the same .ai-rulez/ source (skills, commands, agents, MCP servers) becomes installable plugin bundles and a marketplace index for Claude, Cursor, Codex, Gemini, Kimi, OpenCode, Factory, and Hermes Agent. An opt-in Agent Plugins runtime (runtimes = ["agent-plugins"]) additionally emits portable Agent Plugins 1.0.0 packages.

ai-rulez generate --plugin           # write plugin bundles + marketplace.json
ai-rulez generate --plugin --dry-run # preview
ai-rulez verify --plugin             # prove committed output matches its sources

Write MCP launch commands and hooks once with the canonical ${PLUGIN_ROOT} variable — a hook either runs a command already on the consumer’s machine or bundles a project script into the plugin’s hooks/ directory, so it works in a fresh clone — and each runtime gets its own manifest with the variable and hook format rewritten to fit. Hermes generation emits both a project plugin and a buildable Python entry-point package. Use plugin.content_root to keep distributable skills separate from contributor governance. Supports single-plugin repos and monorepos ([marketplace].members), plus a Claude statusline passthrough. See Authoring Plugins.

What Ships Out of the Box

ai-rulez isn't just a config generator. It ships with 33 builtin domains containing opinionated rules, skills, agents, and workflows that establish a professional development baseline immediately.

Auto-Included Domains

Set builtins in your config — true for every domain, or a list to pick — and these seven come along without being named, unless you exclude one with !. Omit the builtins field entirely and no builtin content is loaded at all.

Each one ships always-on content (rules, or context such as the agent roster) that is read on every request — rules in .claude/rules/ under the default split mode (inlined into CLAUDE.md with [rules] mode = "inline"), context and the agent roster in CLAUDE.md — and some also ship on-demand skills, whose body costs nothing until the assistant loads it.

Builtin Agents

Specialized agents ready to use as subagents: