Skip to main content

AI-Rulez

One source for the rules, skills and settings of every AI coding assistant

npm version PyPI version Homebrew version Go version License Documentation

Documentation · Quick Start · Examples


What it is

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/, run generate, and Claude Code, Cursor, Codex, Copilot, Gemini CLI and the rest get the same guidance in their own format.
  • Checked in CI. generate --check catches drift; validate lints content, links and security issues with stable AR rule codes, and also works on plain AGENTS.md and SKILL.md files 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.

30-second example

npx ai-rulez@latest init acme

Set 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 generate
AGENTS.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.

ai-rulez init and generate: one .ai-rulez source becomes the native files of several AI tools

Install

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)

Or run it without installing: npx ai-rulez@latest <command> or uvx ai-rulez <command>. See Installation for platforms, shell completion and git hooks.

Supported tools

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

What else it does

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:

ai-rulez 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:

ai-rulez verify --plugin reporting changed and extra files in a plugin bundle, then generate --plugin restoring it

Skills served over MCP cost no context until an assistant asks for them:

ai-rulez tokens before and after serving skills over MCP, then find_skill and load_skill

In a monorepo, generate --recursive and validate --recursive process every nested .ai-rulez/:

ai-rulez generate --recursive over two nested roots, recursive validation, and a token budget check

Standards

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.

CI and git hooks

GitHub Actions:

steps:
  - uses: actions/checkout@v7
  - uses: Goldziher/ai-rulez@v5
    with:
      version: 5.10.0
  - run: ai-rulez generate --check
  - run: ai-rulez validate

See GitHub Actions for the full workflow and the governance gate.

pre-commit or prek:

repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v5.11.0
    hooks:
      - id: ai-rulez-recursive
      - id: ai-rulez-validate

See GitHub Actions for the governance gate and scheduled pin updates, and Installation for Lefthook, Poly and init --setup-hooks.

Upgrading from 4.x

Run ai-rulez migrate v5 --dry-run, then follow Migrating to v5.

Documentation

Full documentation: goldziher.github.io/ai-rulez. Contributors: see CONTRIBUTING.md and Architecture.

License

MIT

Metadata

Release files for ai-rulez 5.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-rulez 5.11.0
File Size Uploaded Provenance Actions
ai_rulez-5.11.0.tar.gz 23.5 kB With provenance Details for ai_rulez-5.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-rulez 5.11.0
File Interpreter ABI Platform Actions
ai_rulez-5.11.0-py3-none-any.whl Python 3 none any Details for ai_rulez-5.11.0-py3-none-any.whl

Total release size: 44.2 kB

Release files / ai_rulez-5.11.0.tar.gz

Download URL ai_rulez-5.11.0.tar.gz
Size 23.5 kB
Tags Source
SHA-256 checksum
How to use checksums
5c9855e6e109a1aab0d918f932782aac6126ef98500eccd18417464793979d31
BLAKE2b-256 checksum
How to use checksums
28f2218c8183c00759abd4d968270957adbfc4f2b9a7aebbaf755b437c31175a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / ai_rulez-5.11.0-py3-none-any.whl

Download URL ai_rulez-5.11.0-py3-none-any.whl
Size 20.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1e0c92a8dbbd9116bdca7e9033d17e0a333f165a391a6fea560b70ffafcaefbd
BLAKE2b-256 checksum
How to use checksums
98f6cbc2329d5324e0cfc70053f21c3412ba3a798fb4fce52e52153e7897e92b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for ai-rulez 5.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ai_rulez-5.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

5.13.1

This release

5.11.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page