ai-rulez：面向 AI 智能体知识的标准合规生命周期工具

The standards-compliant lifecycle tool for agent knowledge and capabilities: author, generate, bundle, validate, govern, publish

Documentation · Quick Start · Examples

What it is

ai-rulez is a standards-compliant lifecycle tool for agent knowledge and capabilities. You keep rules, context, skills, agents, commands, hooks, permissions and MCP servers in one source of truth, .ai-rulez/, and ai-rulez takes them through the whole lifecycle:

author  ->  generate  ->  bundle  ->  lint / validate  ->  govern  ->  publish

Standards

The claim is "standards compliant", so each format ai-rulez names is generated or bundled from the same sources and checked against that standard's own schema or rules. A standard is marked supported when the code generates it and validates it today, and planned when it does not yet. docs/standards.md carries the pinned spec version, the conformance test suite and the known gaps for each row, and is the source of truth for test status.

Quick start

npx ai-rulez@latest init                 # author: scaffold .ai-rulez/ with config.toml

# .ai-rulez/config.toml
presets = ["claude", "cursor", "codex", "copilot", "gemini"]   # any of the 52 harnesses

npx ai-rulez@latest generate             # generate: write native files for each preset
npx ai-rulez@latest validate --strict    # validate: content and security checks, warnings fail
npx ai-rulez@latest lock                 # govern: pin includes, skills and authored content in ai-rulez.lock
npx ai-rulez@latest export okf           # bundle: an OKF bundle of your knowledge in docs/okf

Day-to-day:

ai-rulez generate --watch                # regenerate on every change to .ai-rulez/
ai-rulez generate --check                # CI: exit 2 when committed outputs differ from the sources
ai-rulez doctor                          # read-only diagnostics: drift, removed presets, missing tools
ai-rulez generate --user                 # the same, for your home directory (~/.claude, ~/.codex, ...)

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

Bundle and publish

Bundling and publishing need a [plugin] block (name, version and description) in config.toml:

ai-rulez generate --plugin               # plugin bundles and a marketplace index from the [plugin] block
ai-rulez export okf                      # an OKF bundle of your rules, context and skills (docs/okf)
ai-rulez publish --emit agent-plugins --emit ard --dry-run
ai-rulez publish --to github-release --execute --yes

publish runs a preflight first (validate --strict, lock --check, verify --plugin, a secret scan and the policy gates), writes a byte-reproducible tar.gz with SHA256SUMS, and uploads only when you pass --execute --yes. See Publish and Authoring plugins.

Validate

ai-rulez validate                        # config plus content checks, exit 2 on findings
ai-rulez validate --explain AR001        # what a rule checks and how to suppress it
ai-rulez validate --format sarif --output ai-rulez.sarif
ai-rulez okf validate docs/okf           # lint any OKF bundle, ai-rulez's or a third party's
ai-rulez generate --check                # generated files still match their sources

Govern

ai-rulez lock                            # pin remote includes, installed skills and authored content
ai-rulez approve --list                  # what still needs a reviewer's approval
ai-rulez sign --lock                     # a Sigstore bundle (DSSE over an in-toto statement) for the lock
ai-rulez verify --attestation            # check it offline against the [signing] policy
ai-rulez sbom -o ai-bom.cdx.json         # CycloneDX 1.6 (or --type spdx-json)

An organization policy sets tighten-only floors a repository cannot loosen. See the trust model.

Operate

• MCP server. ai-rulez mcp lets an assistant manage the configuration; with --serve-skills it serves skills on demand. See MCP server.
• Telemetry. Item-load records with an optional OTLP export. See telemetry.
• Evals and improve. ai-rulez eval scores skills; improve (experimental) optimizes them behind a held-out eval gate. See evals and improve.
• Cost and inventory. tokens, cost, catalog and search report what the configuration contains and costs.

Existing project on 4.x? Run ai-rulez migrate v5 --dry-run, then see Migrating to v5.

Installation

No install needed — npx ai-rulez@latest <command> works out of the box. Pick a permanent option below:

Homebrew (macOS / Linux)

brew install goldziher/tap/ai-rulez

npx (no install)

npx ai-rulez@latest <command>

npm (global)

npm install -g ai-rulez

uvx (no install)

uvx ai-rulez <command>

uv tool

uv tool install ai-rulez

pip / pipx

pip install ai-rulez
# or, isolated:
pipx install ai-rulez

Go

go install github.com/Goldziher/ai-rulez/v5/cmd/ai-rulez@latest

The module path needs /v5; without it @latest resolves to an old build.

pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Goldziher/ai-rulez
    rev: v5.0.0
    hooks:
      - id: ai-rulez-recursive # generate outputs across the repo
      - id: ai-rulez-validate # dry-run validation

Available hook ids: ai-rulez-validate, ai-rulez-generate, ai-rulez-recursive, ai-rulez-plugin-generate, and ai-rulez-plugin-verify. They trigger on root or nested .ai-rulez/ changes.

poly hook source

Add ai-rulez as a managed source in your existing poly.toml and select the hooks your repository needs. This requires Poly 0.14.0+; pin revision to the AI-Rulez release you want (the hooks run that release):

[[hooks.sources]]
id = "ai-rulez"
git = "https://github.com/Goldziher/ai-rulez.git"
revision = "v5.0.0"
hooks = ["ai-rulez-recursive", "ai-rulez-plugin-verify"]

The source also provides ai-rulez-validate, ai-rulez-generate, and ai-rulez-plugin-generate. Plugin hooks use --if-configured, so they skip consumer-only repositories that do not contain a producer [plugin] or multi-member [marketplace] block.

Resolve and commit the source lock, then install the Git shims:

poly hooks update
git add poly.toml poly-hooks.lock
poly hooks install

See the Poly hooks guide for local sources, machine install preferences, hook behavior, and the producer catalog.

lefthook

Add to lefthook.yml:

pre-commit:
  commands:
    ai-rulez:
      glob: ".ai-rulez/**"
      run: ai-rulez generate --recursive --no-local

Hooks run on each developer's machine and would otherwise load that developer's gitignored config.local.toml overlay and .ai-rulez/local/ content. Pass --no-local (also accepted by validate and tokens) where a hook should see only the shared configuration, as a teammate or CI does. If you do not, generate still refuses to write local-derived changes into tracked shared files; never add --allow-local-drift to a hook. See Poly hooks guide.

In a monorepo, ai-rulez generate --recursive and ai-rulez validate --recursive (-r) process every nested .ai-rulez/ root, report all failures, and exit non-zero if any root failed.

Or run ai-rulez init --setup-hooks while initializing a repo to wire hooks in automatically.

Documentation

Full documentation at goldziher.github.io/ai-rulez.

License

MIT