One source for the rules, skills and settings of every AI coding assistant
Documentation · Quick Start · Examples
ai-rulez keeps the instructions for your AI coding assistants in one directory, .ai-rulez/: rules, context, skills,
agents, commands, hooks, permissions and MCP servers. From that source it generates the native files of each assistant
your team uses (AGENTS.md, CLAUDE.md, .cursor/rules/, .github/instructions/, skill folders, MCP and settings
files) for 52 tools, and keeps them in sync.
- One source, every tool. Edit
.ai-rulez/, rungenerate, and Claude Code, Cursor, Codex, Copilot, Gemini CLI and the rest get the same guidance in their own format. - Checked in CI.
generate --checkcatches drift;validatelints content, links and security issues with stableARrule codes, and also works on plainAGENTS.mdandSKILL.mdfiles with no configuration. - Governed like dependencies. A lock file pins remote includes, installed skills and authored content; approvals, Sigstore signatures, SBOMs and an organization policy cover the rest.
- Packaged for distribution. Build plugin bundles and marketplaces, Agent Plugins and ARD manifests, and publish them.
npx ai-rulez@latest init acmeSet the tools you use in .ai-rulez/config.toml:
version = "5.0"
name = "acme"
presets = ["claude", "cursor", "codex", "copilot", "gemini"]Add a rule and generate:
npx ai-rulez@latest add rule testing --content '# Testing
- Every bug fix ships with a regression test.'
npx ai-rulez@latest generateAGENTS.md # rules and context, read by Codex, Cursor, Copilot and Gemini CLI
CLAUDE.md # imports @AGENTS.md for Claude Code
.agents/skills/ # skills
.claude/skills/
.gemini/settings.json # points Gemini CLI at AGENTS.md
.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml
Commit .ai-rulez/ with the generated files, and add ai-rulez generate --check to CI. The
Quick start walks through it in five minutes.
brew install goldziher/tap/ai-rulez # Homebrew (macOS, Linux)
npm install -g ai-rulez # npm (Node.js 22+)
pipx install ai-rulez # PyPI (Python 3.11+); or uv tool install ai-rulez
go install github.com/Goldziher/ai-rulez/v5/cmd/ai-rulez@latest # Go (note the /v5)On Windows x64, install with Scoop:
scoop bucket add goldziher https://github.com/Goldziher/scoop-bucket
scoop install goldziher/ai-rulezOr run it without installing: npx ai-rulez@latest <command> or uvx ai-rulez <command>. See
Installation for platforms, shell completion and git hooks.
52 built-in presets, one per assistant, CLI agent or IDE integration. Combine any of them in presets = [...];
Supported harnesses shows which rules, skills, agents, commands, MCP servers, hooks and permissions
each one receives. A tool that is not listed can be added as a custom preset.
All 52 built-in presets
| Preset | Tool |
|---|---|
aiassistant |
JetBrains AI Assistant |
amp |
Sourcegraph Amp |
antigravity |
Google Antigravity |
augment |
Augment Code |
baz |
Baz |
bob |
IBM Bob |
claude |
Claude Code |
cline |
Cline |
codebuddy |
CodeBuddy Code |
codebuff |
Codebuff |
codewhale |
Codewhale |
codex |
OpenAI Codex |
commandcode |
Command Code |
copilot |
GitHub Copilot |
copilot-cli |
GitHub Copilot CLI |
cortex |
Snowflake Cortex Code |
crush |
Crush |
cursor |
Cursor |
deepagents |
Deep Agents Code |
devin |
Devin CLI |
dsh |
DeepSeek Harness |
factory |
Factory Droid |
gemini |
Gemini CLI |
gitlab-duo |
GitLab Duo CLI |
goose |
goose |
grok |
Grok Build CLI |
hermes |
Hermes Agent |
junie |
JetBrains Junie |
kilo |
Kilo Code |
kimi |
Kimi Code |
kiro |
Kiro |
letta |
Letta Code |
mimocode |
MiMo Code |
muse |
Meta Muse Code |
omp |
oh-my-pi |
openclaw |
OpenClaw |
opencode |
OpenCode |
pi |
pi |
poolside |
Poolside Pool |
qoder |
Qoder |
qwen |
Qwen Code |
reasonix |
Reasonix |
replit |
Replit Agent |
rovodev |
Atlassian Rovo Dev |
takt |
Takt |
trae |
Trae |
vibe |
Mistral Vibe |
warp |
Warp |
xum |
Xum |
zcode |
ZCode |
zed |
Zed |
zoocode |
Zoo Code |
| Area | Commands | Docs |
|---|---|---|
| Author | add, edit, show, list, remove, domain, profile, include, skill install |
Configuration, Rules, Skills, Includes |
| Import | init --from auto, convert, migrate v5 |
CLI, Migrating to v5 |
| Generate | generate, generate --user, generate --recursive, generate --watch, clean |
Harnesses, Hooks and settings, Monorepo |
| Validate | validate, scan, verifiers run, judge, review |
Strict validation, Verifiers, Judge |
| Govern | lock, update, approve, sign, verify, sbom |
Lock file, Signing, Policy |
| Bundle and publish | generate --plugin, verify --plugin, publish |
Plugins, Publish |
| Operate | mcp --serve-skills, search, eval, tokens, cost, catalog, telemetry |
MCP server, Evals |
| Embed | pkg/airulez |
Go API |
validate --strict flags a defect, --explain describes it, and generate --check fails on drift:
verify --plugin reports hand-edited or stray files in a plugin bundle, and generate --plugin restores it:
Claude Code and Codex discover native skills through their names and descriptions, then load skill bodies on demand. In repositories with nested skill directories, metadata from multiple scopes can accumulate as a session moves between them. MCP delivery keeps served skills out of the native catalog. For Claude Code, generated project guidance tells Claude when to search for served skills using the task and repository path. Skill selection still depends on the model and client settings. Compare delivery options.
In a monorepo, generate --recursive and validate --recursive process every nested .ai-rulez/:
Static checks of ai-rulez scan against other open-source skill scanners, on a public dataset we did not write:
1384 skills (839 malicious, 545 benign) from the MaliciousSkillBench source-disjoint test partition, static, text-only, no LLM. Scored on each tool's own verdict; intervals are 95% clustered bootstrap.
| Tool | Version | Recall | False-positive rate | Precision | F1 |
|---|---|---|---|---|---|
| ai-rulez | 5.11.1 | 0.195 (0.139-0.271) | 0.338 (0.297-0.378) | 0.471 | 0.276 (0.210-0.354) |
| skill-scanner | 2.3.2 | 0.077 (0.044-0.125) | 0.040 (0.025-0.058) | 0.747 | 0.140 (0.082-0.216) |
| skillspector | 2.13.4 | 0.113 (0.073-0.167) | 0.194 (0.161-0.228) | 0.473 | 0.183 (0.124-0.254) |
That table is the last held-out read, of release 5.11.1. Unreleased changes are measured only on the dev partition,
which rule changes are tuned on, so expect lower numbers on held-out sources. ai-rulez-threat is
scan --fail-on threat, the gate to compare with the other scanners; ai-rulez is --fail-on warning:
8213 skills (6523 malicious, 1690 benign) from the MaliciousSkillBench source-disjoint dev partition, static, text-only, no LLM. Scored on each tool's own verdict; intervals are 95% clustered bootstrap.
| Tool | Version | Recall | False-positive rate | Precision | F1 |
|---|---|---|---|---|---|
| ai-rulez-threat | unreleased | 0.225 (0.209-0.242) | 0.007 (0.004-0.011) | 0.992 | 0.367 (0.345-0.389) |
| ai-rulez | unreleased | 0.437 (0.420-0.454) | 0.074 (0.062-0.087) | 0.958 | 0.600 (0.584-0.616) |
| skill-scanner | 2.3.2 | 0.312 (0.298-0.326) | 0.008 (0.004-0.013) | 0.993 | 0.475 (0.459-0.491) |
| skillspector | 2.13.4 | 0.323 (0.306-0.339) | 0.155 (0.138-0.173) | 0.889 | 0.473 (0.455-0.492) |
And on real, widely used skills, where every flag is a false alarm:
563 real skills from the clean track, all treated as benign, static, text-only, no LLM. A flag is a false alarm.
| Tool | Version | Skills flagged | Share flagged |
|---|---|---|---|
| ai-rulez-threat | unreleased | 12 of 563 | 2.1% (1.1-3.4) |
| ai-rulez | unreleased | 53 of 563 | 9.4% (7.1-11.9) |
| skill-scanner | 2.3.2 | 26 of 563 | 4.6% (3.0-6.4) |
| skillspector | 2.13.4 | 167 of 563 | 29.7% (25.9-33.4) |
Every number is reproducible with one command. See Scanner benchmark for the protocol and its limits.
ai-rulez generates and validates AGENTS.md, Agent Skills, Agent Plugins, ARD, llms.txt, OKF (the format of
.ai-rulez/ itself), MCP server configuration and Server Cards, CycloneDX and SPDX SBOMs, and in-toto/DSSE
attestations in Sigstore bundles. Standards conformance lists the versions, the conformance tests
and the known gaps.
GitHub Actions:
steps:
- uses: actions/checkout@v7
- uses: Goldziher/ai-rulez@v5
with:
version: 5.14.0
- run: ai-rulez generate --check
- run: ai-rulez validateSee GitHub Actions for the full workflow and the governance gate.
pre-commit or prek:
repos:
- repo: https://github.com/Goldziher/ai-rulez
rev: v5.14.0
hooks:
- id: ai-rulez-recursive
- id: ai-rulez-validateSee GitHub Actions for the governance gate and scheduled pin
updates, and Installation for Lefthook, Poly and init --setup-hooks.
Run ai-rulez migrate v5 --dry-run, then follow Migrating to v5.
Full documentation: goldziher.github.io/ai-rulez. Contributors: see CONTRIBUTING.md and Architecture.





