Skip to content
GoldziherPublic

About

Author, generate, validate and govern AI agent rules, skills, plugins and MCP configuration across 52 coding assistants. Review with verified model evidence, evaluate skills, lock and sign dependencies, and publish bundles. CLI, MCP server and Go API.

Topics

Resources

Contributing

Security policy

Stars

179 stars

Watchers

3 watching

Forks

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Latest commit

 

History

3,672 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AI-Rulez

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

npm version PyPI version Homebrew version Go version CI 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)

On Windows x64, install with Scoop:

scoop bucket add goldziher https://github.com/Goldziher/scoop-bucket
scoop install goldziher/ai-rulez

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

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.

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

How it compares

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.

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.14.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.14.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

About

Author, generate, validate and govern AI agent rules, skills, plugins and MCP configuration across 52 coding assistants. Review with verified model evidence, evaluate skills, lock and sign dependencies, and publish bundles. CLI, MCP server and Go API.

Topics

Resources

Contributing

Security policy

Stars

179 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages