Claude Cursor Skill

ai-rulez

Standards-compliant lifecycle tool for agent knowledge and capabilities: author in .ai-rulez/, generate for 52 harnesses (Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Devin, and more), bundle (OKF, Agent Plugins, ARD), validate, govern (lock, approvals, signing, SBO

LLM Mart · 0 points · 0 views 2 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download goldziher-ai-rulez-skills_ai-rulez-ca967ad.zip · 21 KB
goldziher/ai-rulez 162 16 forks MIT Updated 5h ago
Part of goldziher/ai-rulez — 151 skills

Install

skills CLI npx skills add https://github.com/Goldziher/ai-rulez/tree/main/skills/ai-rulez
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install goldziher-ai-rulez@llmmart
Git git clone https://github.com/Goldziher/ai-rulez.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole goldziher/ai-rulez collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

AI-Rulez

AI-Rulez is a standards-compliant lifecycle tool for agent knowledge and capabilities. It keeps one source of truth in a config directory (default .ai-rulez/) and takes it through author, generate (52 built-in harness presets: Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Devin, and others), bundle (OKF, Agent Plugins, ARD), lint and validate, govern (lock, approvals, Sigstore signing, policy, SBOM) and publish.

Use this skill when:

  • Setting up or modifying .ai-rulez/ configuration
  • Writing rules, context, skills, agents, commands, or checks for AI assistants
  • Declaring [[hooks]] or [permissions] once for every harness
  • Generating a personal config into the home directory with generate --user
  • Configuring domains, profiles, or includes
  • Using custom config directory names via --config-dir
  • Generating outputs for specific AI tools
  • Auditing planned writes/deletes with --dry-run
  • Installing or managing external skills

Installation

# npm (no install)
pnpm dlx ai-rulez@5.4.1

# Python (no install)
uvx ai-rulez==5.4.1

# Source builds (Go + Task; setup fetches and verifies the pinned native library)
# Checkout the source revision pinned in this repository's CI, then:
task build

Package commands use the published release. Source builds also need the pinned Liter-LLM native library: task build provisions it through scripts/setup-liter-llm.sh; a bare go install does not do that setup. Version 5.4.0 includes the governance and plugin validation fixes described below. For a reviewed source build, use the exact revision recorded in the CI workflow.

Quick Start

# Initialize a new project
ai-rulez init

# Add rules and context
ai-rulez add rule my-rule --priority high
ai-rulez add context my-context

# Generate outputs for all configured presets
ai-rulez generate

# Regenerate whenever .ai-rulez/ changes
ai-rulez generate --watch

# Validate configuration
ai-rulez validate

# Read-only diagnostics: drift, removed presets, missing tools
ai-rulez doctor

Lifecycle commands

ai-rulez generate --plugin              # bundle: plugin bundles from the [plugin] block
ai-rulez export okf                     # bundle: an OKF bundle of the knowledge
ai-rulez validate --strict              # validate: warnings fail
ai-rulez okf validate <bundle-dir>      # validate: an existing OKF bundle directory
ai-rulez lock                           # govern: pin includes, skills and content
ai-rulez sign --lock                    # govern: Sigstore attestation of the lock
ai-rulez sbom -o ai-bom.cdx.json        # govern: CycloneDX SBOM
ai-rulez publish --dry-run              # publish: preview release artifacts

Supported and planned standards, with pinned versions and test status, are in https://goldziher.github.io/ai-rulez/standards/.

Other sources and config-free checks

  • source = "agents" (or a configuration in .agents/ai-rulez.toml) reads the root and nested AGENTS.md and .agents/ (skills, rules, agents, checks, commands, context, domains) instead of .ai-rulez/; generate translates them to every other tool and never writes AGENTS.md or .agents/. agents_md_split = true reads AGENTS.md as one item per ## heading. Start with ai-rulez init --source agents.
  • ai-rulez validate --strict works in a repository with no ai-rulez config, linting the files that follow a convention; --path, --glob and --outputs choose what else to lint.
  • ai-rulez judge --estimate --model openai/gpt-4o-mini previews a model grading of instruction files, again with no config; add --allow-llm to send.

Configuration Structure

.ai-rulez/
  config.toml          # Governance configuration
  config.plugins.toml  # Plugin and marketplace layer, selected by default_layers
  rules/               # Governance rules (.md files with frontmatter)
  context/             # Contextual information (.md files)
  skills/              # Specialized capabilities (name/SKILL.md plus resources)
  agents/              # Agent definitions (.md files)
  commands/            # Custom commands (.md files)
  checks/              # Code-review guidelines (.md files)
  domains/             # Domain-scoped content
    backend/
      rules/
      context/
      skills/

config.toml

Keep governance in config.toml. Put marketplace registries ([[marketplaces]]) and authoring [plugin]/[marketplace] blocks in config.plugins.toml, and select that layer with default_layers = ["plugins"] before the first table in config.toml. Plugin authoring can use a separate plugin/.ai-rulez/ tree so public product skills exclude contributor rules.

version = "5.0"
name = "my-project"
description = "Project description"

presets = ["claude", "cursor", "gemini"]
default_layers = ["plugins"]
default = "backend"
builtins = ["go", "security", "testing"]

[profiles]
backend = ["backend", "shared"]
frontend = ["frontend", "shared"]

[[includes]]
name = "shared-rules"
source = "https://github.com/org/shared-rules"

[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"

[[mcp_servers]]
name = "ai-rulez"
command = "pnpm"
args = ["dlx", "ai-rulez@5.4.1", "mcp"]

[[scopes]]
path = "packages/web"
profile = "frontend"
presets = ["codex", "claude"]

Content Frontmatter

Authored .ai-rulez/ content uses OKF frontmatter: type, title and an x-ai-rulez identity. Tool-specific fields belong in x-ai-rulez.metadata. Use Principle for rules, Concept for context, Playbook for skills and Reference for agents. For example, .ai-rulez/rules/project-conventions.md:

---
type: Principle
title: Project conventions
description: Shared project conventions
x-ai-rulez:
  kind: rule
  id: project-conventions
  metadata:
    priority: high
    targets:
      - CLAUDE.md
      - .cursor/rules/*
---

priority accepts critical, high, medium, low and minimal. Older flat frontmatter remains readable for migration; run ai-rulez migrate okf to convert it and ai-rulez migrate okf --check to verify the authored tree.

For public plugin skills, set x-ai-rulez.metadata.name to a stable lowercase slug matching the skill directory and x-ai-rulez.id. This supplies the required native Agent Skills name across runtime projections.

Public skills/<name>/SKILL.md exports use native Agent Skills frontmatter, including name and description, without the OKF wrapper. This public skill is such an export; its frontmatter is not the authoring format for .ai-rulez/.

Agent-only fields

Agent files under .ai-rulez/agents/ put native subagent fields inside x-ai-rulez.metadata. Supported fields render into the configured harness; fields a harness does not support are omitted. For example, create .ai-rulez/agents/<agent-id>.md with security-reviewer as the ID:

---
type: Reference
title: Security reviewer
description: Reviews code for security regressions
x-ai-rulez:
  kind: agent
  id: security-reviewer
  metadata:
    name: security-reviewer
    model: opus
    effort: high
    permissionMode: default
    tools:
      - Read
      - Grep
      - Glob
---

Claude Code receives these fields in .claude/agents/<agent-id>.md using its native flat frontmatter. Keep the authored OKF file and generated native file distinct.

effort controls reasoning depth. Set a project-wide default and per-preset overrides in config.toml:

[defaults]
effort = "medium"

[defaults.effort_by_preset]
codex = "high"      # Codex applies it globally and per agent
claude = "xhigh"    # Claude applies it as `effort` per agent
amp = "max"         # Amp writes amp.anthropic.effort to .amp/settings.json

Resolution order (per preset, per agent): per-agent effort → defaults.effort_by_preset[<preset>] → defaults.effort → omit.

Per-preset support:

  • Claude: per-agent in .claude/agents/*.md (full vocabulary including max; inherit is not a Claude value and is dropped)
  • Codex: global in .codex/config.toml and per-agent in .codex/agents/*.toml (max → high; inherit dropped)
  • Amp: global in .amp/settings.json (xhigh → high)
  • Devin: per-agent in .devin/agents/*.md frontmatter (max → high)
  • Opencode: per-agent variant in .opencode/agents/*.md (joins the agent's model as model#variant)
  • Cursor, Copilot, Gemini, Junie, Antigravity, Cline: silently skipped (those tools expose effort via UI toggles or user-managed config files we don't generate).

Domains and Profiles

Domains group content for different teams or concerns. Profiles select which domains are active.

ai-rulez domain add backend
ai-rulez add rule api-standards --domain backend
ai-rulez profile add backend-team backend shared
ai-rulez generate --profile backend-team

Includes

Share rules across projects using git repositories or local paths:

ai-rulez include add shared-rules https://github.com/org/shared-rules
ai-rulez include add local-rules ./path/to/local --merge-strategy include-override

Installed Skills

Install named skills from external repositories:

ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg
ai-rulez skill install ai-rulez --source https://github.com/Goldziher/ai-rulez
ai-rulez skill list
ai-rulez skill remove kreuzberg

Skills are fetched dynamically at generation time and included in outputs. Skill references/, scripts/, and assets/ directories are preserved as separate generated resource files when the target preset supports skill directories.

Built-in Presets

52 presets are available (ai-rulez init writes the list into a comment in the new config.toml): aiassistant, amp, antigravity, augment, baz, bob, claude, cline, codebuddy, codebuff, codewhale, codex, commandcode, copilot, copilot-cli, cortex, crush, cursor, deepagents, devin, dsh, factory, gemini, gitlab-duo, goose, grok, hermes, junie, kilo, kimi, kiro, letta, mimocode, muse, omp, openclaw, opencode, pi, poolside, qoder, qwen, reasonix, replit, rovodev, takt, trae, vibe, warp, xum, zcode, zed, zoocode, plus the opt-in okf preset (creates an Open Knowledge Format bundle at <project-root>/docs/okf/ by default; see ai-rulez export okf). The mcp preset is a shared utility (the generic .mcp.json) invoked automatically when MCP servers are configured.

windsurf is now devin and continue-dev was removed; ai-rulez doctor reports both. harnesses.md has the per-preset feature matrix (rules folder, skills, agents, commands, MCP, hooks, permissions, checks, user scope).

Hooks, Permissions, Checks and User Scope

  • [[hooks]] in config.toml renders into the native hooks file of 36 harnesses (a generated plugin module for opencode, kilo, mimocode, pi and amp). Events, matchers and timeouts are translated per harness; a group a harness cannot express is skipped with a warning. See settings.md.
  • [permissions] (allow, ask, deny, Claude Code rule syntax) is translated for 24 harnesses. A rule that cannot be expressed is skipped, never widened, and an unenforced deny is reported. See permissions.md.
  • Checks are code-review guidelines in .ai-rulez/checks/<name>.md (OKF description and x-ai-rulez.metadata fields severity, tools, targets), rendered for cursor, kilo, qwen, factory, rovodev, amp, augment and gitlab-duo. Manage them with ai-rulez add|remove|list check. See checks.md.
  • ai-rulez generate --user renders a user config (~/.config/ai-rulez) into the home directories of 47 harnesses; clean --user removes what it wrote. See user-scope.md.
  • Settings files you also edit (JSON, JSONC, TOML, YAML) are merged key by key, so your own keys and comments survive generate and clean.
  • [guard] generated = true adds a PreToolUse hook (ai-rulez guard) that blocks agent edits to generated files and points at the source under .ai-rulez/.

Lock, Updates and Verification

  • ai-rulez lock writes ai-rulez.lock: commits and digests of remote includes, installed skills and skill sources, plus every authored item and generated output. It is enforced whenever the file exists ([lock] enforce = false opts out). lock --check verifies offline, --diff previews, --subject prints the digest to sign with cosign, generate --locked/--frozen are the CI modes. Exit codes: 0 ok, 1 could not run, 2 drift, 3 served skills left unpinned by the security scan. See lockfile.md.
  • Sources accept version = "^1.2"; ai-rulez lock --outdated lists newer tags and ai-rulez update moves range pins (codes AR730, AR731, AR732, AR735).
  • ai-rulez validate runs deep content checks with stable AR codes (--fix, --since, --baseline, --format json|sarif|github|junit|markdown); ai-rulez scan runs only the security checks; validate --explain AR001 explains a rule. See strict-validation.md.
  • [[verifiers]] and .ai-rulez/verifiers/*.toml declare deterministic repo checks run by ai-rulez verifiers run (--since, --staged, --format sarif|junit).
  • ai-rulez sbom prints a CycloneDX bill of materials, ai-rulez catalog lists every item with owner, version, tokens and lock status (--html <dir> writes a static site), ai-rulez tokens and cost report prompt-token cost, ai-rulez search <query> ranks skills.
  • ai-rulez convert imports existing tool files, a rulesync project or a skills-lock.json into .ai-rulez/ with a lossiness report.

Roles and Dynamic Skills

  • [[roles]] map a job to a slice of the content (domains, include/exclude selectors, skill_mode); generate --role <name> renders it and ai-rulez roles list|show|resolve inspects it. See roles.md.
  • delivery: static|served|both in an authored skill's x-ai-rulez.metadata (or [skills] delivery) serves a skill over MCP on demand instead of writing it to the harness trees: run ai-rulez mcp --serve-skills (find_skill, load_skill, list_skill_resources). [[skill_sources]] serve skills from a git repository or directory. See mcp-server.md.

A tool that isn't built in can be supported at full parity with a provider-backed custom preset: set provider = "<project-relative spec.toml>" and point it at a declarative spec validated against schema/provider.schema.json. See the ai-rulez references for the spec shape.

MCP Integration

MCP servers are configured inline in config.toml with [[mcp_servers]]. ai-rulez exposes an MCP server for AI assistants to read, create, update, validate, dry-run, and generate configuration:

ai-rulez mcp

Configure in your AI tool's MCP settings to enable CRUD operations from within the assistant.

MCP server env values can use ${VAR} placeholders. ai-rulez generate resolves them from --env, process env, and dotenv files, then refuses to write secret-bearing generated MCP configs unless the target paths are gitignored (gitignore = true or generate --gitignore adds them to the managed block).

Plugins and Marketplaces

ai-rulez can package the same source (skills, commands, agents, MCP servers) as distributable plugin bundles and a marketplace index for Claude, Cursor, Codex, Gemini, Kimi, OpenCode, Factory, Hermes, Pi, Agent Plugins and Copilot via ai-rulez generate --plugin. Consumer [[plugins]]/[[marketplaces]] arrays declare plugins to install from a marketplace (no output file is written for them: generate warns that [[plugins]] has no effect; enable plugins through [claude.settings] for Claude Code and .codex/config.toml for Codex).

Verification and distribution

Use migrate okf --check, validate --strict --no-local, lock --check, and generate --check --no-local --strict-config to check the authored configuration. For published plugins, use verify --plugin before regenerating to detect existing drift; after intentional regeneration, check it again and verify public skill exports. Package from a committed tree with publish --tag <release-tag>, then run publish verify <dist-directory> on the actual archive. A successful local package does not publish a release or registry package.

Version 5.4.0 includes fixes for registered marketplace members, both-layout MCP ownership, OpenCode skill IDs and shared include-cache locking. The repository validates with a reviewed source build pinned in CI; use that exact source revision when reproducing its checks.

The exact reviewed source revision is recorded in .github/workflows/ai-rulez-validation.yml. It includes the ID-only OKF skill projection fix, strict Hermes package metadata, and cache isolation by configured source path and revision. Use that workflow as the source of truth for the pin.

Files (ai-rulez)
  • references
    • cli-reference.md 13.6 KB 
      # CLI Reference

## Global Flags

- `--config <path>` — Override config discovery
- `--config-dir <name>` — Configuration directory name below the working directory
- `--debug, -D` — Enable debug output
- `--quiet, -q` — Suppress progress bars and non-essential output
- `--token, -T <token>` — Git access token for private repos (or `AI_RULEZ_GIT_TOKEN` env var)

## Core Commands

### `ai-rulez init`

Initialize `.ai-rulez/` directory with configuration.

Flags:

- `--domains, -d <names>` — Comma-separated initial domains
- `--skip-content, -s` — Skip example content files
- `--from, -F <source>` — Import from existing tool files, such as `auto`
- `--setup-hooks, -H` — Configure git hooks
- `--yes, -y` — Automatically answer yes to prompts
- `--config-dir <path>` — Directory to scaffold (default `.ai-rulez`; use `.config/ai-rulez` for the `.config/` convention)

### `ai-rulez generate`

Render outputs for all configured presets.

Flags:

- `--profile <name>` — Select a specific profile
- `--role <name>` — Generate the slice of content a `[[roles]]` entry selects (mutually exclusive with `--profile`; works with `--user`)
- `--locked` / `--frozen` — Require `ai-rulez.lock` to match remote sources and authored content (`--frozen` never uses the network); exit 2 on a source difference
- `--dry-run, -d` — Print planned directories, writes, and stale generated-file deletions without mutating files
- `--gitignore, -i` — Opt in to the managed `.gitignore` block with generated output patterns (off by default; same as `gitignore = true`)
- `--config-dir, -n <name>` — Use a non-default config directory name instead of `.ai-rulez`
- `--recursive, -r` — Generate for every discovered config directory
- `--offline` — Use cached includes and skills without fetching
- `--env, -e KEY=VALUE` — MCP env override; repeatable
- `--env-file, -E <path>` — Dotenv file for MCP placeholders; repeatable
- `--no-local` — Ignore the machine-local `config.local.*` overlay and `local/` content
- `--strict-config` — Fail on unknown or invalid config keys instead of warning (env `AI_RULEZ_STRICT=1`)
- `--yes, -y` — With `--user`, skip the confirmation; always, silence the summary of new hook and MCP commands (env `AI_RULEZ_ACK_COMMANDS=1`)
- `--plugin` — Generate distributable plugin bundles and a marketplace index from the `[plugin]` block
- `--if-configured` — With `--plugin`, skip successfully when plugin authoring is not configured
- `--watch, -w` — Generate, then regenerate on every change to `.ai-rulez/`, the local overlay and local includes (not combinable with `--dry-run`, `--check`, `--user`, `--plugin` or `--recursive`)
- `--check` — Render in memory and compare with the disk without writing; exits 2 on drift
- `--user` — Render the user config (`~/.config/ai-rulez`, or `--config <dir>`) into the per-user directories of each harness; `--yes, -y` skips the confirmation

`--update-gitignore`, `--no-configure-cli-mcp, -M` and `--skip-cli-mcp, -S` were removed in v5 (use `--gitignore`; the others had no effect).

Exit codes: `0` ok, `1` a config failed to load or generate, `2` `--check` found drift or `--locked`/`--frozen` found a source that differs from the lock.

### `ai-rulez clean`

Remove generated outputs. `--dry-run` previews, `--yes` skips the prompt, `--include-edited` also removes generated files edited by hand (otherwise kept with a warning), `--user` removes what `generate --user` wrote, `--profile`, `--keep-gitignore`, `--keep-manifest`.

### `ai-rulez validate`

Check configuration and content structure for errors. Exit `0` valid, `1` invalid or cannot load, `2` `--strict` findings at or above `--fail-on`.

Flags:

- `--config-dir <name>` — Use a non-default config directory name instead of `.ai-rulez`
- `--recursive, -r`, `--no-local`, `--repo-root <dir>`
- `--strict` — Deep content validation with stable finding codes; exits 2 on findings at or above `--fail-on`
- With `--strict` (or any `--format`): `--format text|json|sarif|github|junit|markdown`, `--output <file>`, `--fail-on error|warning|info|none`, `--analyzer <names>`, `--lint-profile default|strict|permissive`, `--external` and `--allow-egress <scanner>`, `--baseline <file>`, `--update-baseline --baseline-reason <text>`, `--strict-baseline`, `--since <rev>` / `--changed` with `--since-depth <n|all>` and `--since-max-files <n>`, `--fix` / `--fix-unsafe` with `--dry-run`
- `--explain <code>` — Print what a rule checks, why, examples and how to suppress it
- `--path <file|dir>` and `--glob <pattern>` (repeatable) — Also lint files outside the content tree, inside the project root; `--outputs` also lints the generated files
- With no configuration file, `validate`, `scan` and `doctor` lint the files that follow a convention (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, `.claude/`, `.agents/`, `.cursor/rules`, plugin manifests, hooks, MCP files) and write nothing; `generate`, `clean` and `lock` still need a configuration

### `ai-rulez judge`

Grade instruction files (`AGENTS.md`, rules, skills, agents, commands) with a model against a rubric. Reads no configuration: the model comes from `--model provider/model` or `AI_RULEZ_LLM_MODEL`, the key from the provider's own variable. Nothing is sent without `--allow-llm`; `--estimate` (alias `--dry-run`) lists the files, egress host, model and cost and sends nothing. `--min-score` (default 0.7), `--max-cost` (default $0.25), `--rubric <file>`, `--format text|json`. Exit `0` all passed, `1` could not run, `2` a file scored below `--min-score` or was skipped for secrets.

### `ai-rulez scan`

Security checks only (`AR0xx`): secrets, hidden characters, prompt injection, risky shell, unpinned remotes. Same output, baseline and changed-only flags as `validate`, plus `--external` for `[[lint.external]]` scanners (`--write-baseline --reason`, `--scanner-baseline`, `--show-suppressed`). `ai-rulez scanners list|doctor [--external] [--format json]` inspects those scanners.

### `ai-rulez doctor`

Read-only diagnostics with `error`, `warning` and `info` findings: config validity, removed presets (`windsurf` is
`devin`; `continue-dev` is gone), generated-output drift, generated paths git does not ignore, unresolved MCP
`${VAR}` placeholders, missing hook scripts, lock drift and preset tools missing from `PATH`. Flags: `--strict`,
`--format text|json`, `--profile`, `--no-local`.
Exits 2 on errors (and warnings with `--strict`), 1 when the configuration cannot be loaded.

### `ai-rulez verify`

Verify signatures and provenance: `--attestation`, `--approvals`, `--self`, `--plugin` (plugin bundles). Drift is `generate --check`; a bare `verify` exits 1 with that pointer.

### `ai-rulez export okf` / `import okf` / `okf validate`

Open Knowledge Format (OKF v0.2) support, see `docs/okf.md`.

- `ai-rulez export okf [--output-dir <dir>] [--profile <p>] [--include rules,context,skills,agents,commands,checks] [--check]` — create a deterministic OKF bundle in `okf.dir` (default `<project-root>/docs/okf/`); `--check` writes nothing and exits 2 on drift
- `ai-rulez import okf <dir|git-url[@ref][#subdir]> [--into rules|context|skills] [--domain <d>] [--dry-run] [--force]` — convert a bundle into `.ai-rulez/` sources; never overwrites without `--force`, scans imported text (AR001-AR011) first
- `ai-rulez okf validate <dir|git-url> [--format json] [--fail-on error|warning|info|none]` — lint any bundle (AR9B0-AR9B9)

### `ai-rulez convert`

Import another tool's files (`--from native`, `rulesync`, `skills-lock` or `auto`) into `.ai-rulez/` with a lossiness report (`mapped`, `approximated`, `dropped`, `needs-action`, `unsupported`). Writes nothing without `--write`; flags `--dry-run`, `--force`, `--domain`, `--format text|json`, `--report`, `--fail-on`, `--allow-findings`, `--list`.

### `ai-rulez mcp`

Start the MCP server for AI assistant integrations. `ai-rulez mcp --serve-skills` serves skills read-only (`find_skill`, `load_skill`, `list_skill_resources`): `--profile`, `--role`, `--targets`, `--domain`, `--allow`, `--deny`, `--source`, `--include-static`, `--frozen`, `--offline`, `--budget-bytes`, `--usage-log`, `--usage-sink`, `--no-watch`, `--reload-interval`.

### `ai-rulez guard`

Hidden PreToolUse hook added by `[guard] generated = true`: exits 2 when a tool call edits a generated file, 0 otherwise (fails open).

## CRUD Commands

### Rules

- `ai-rulez add rule <name> [--domain <d>] [--priority <p>] [--content <c>]`
- `ai-rulez remove rule <name> [--domain <d>] [--yes]`
- `ai-rulez list rules [--domain <d>] [--format json]`

### Context

- `ai-rulez add context <name> [--domain <d>] [--priority <p>] [--content <c>]`
- `ai-rulez remove context <name> [--domain <d>] [--yes]`
- `ai-rulez list context [--domain <d>] [--format json]`

### Skills

- `ai-rulez add skill <name> [--domain <d>] [--description <desc>]`
- `ai-rulez remove skill <name> [--domain <d>] [--yes]`
- `ai-rulez list skills [--domain <d>] [--format json]`
- `ai-rulez list --placement [--profile <p>]` — where each skill and command ends up (core or plugin-only)

`add`, `remove` and `list` also take `--local` for the machine-local tree at `<config-dir>/local/`, which is created when local content is added. Agents and commands work like rules; checks use shared content only.

### Agents, Commands and Checks

- `ai-rulez add agent|command|check <name> [--domain <d>] [--description <desc>] [--content <c>]`
- `ai-rulez remove agent|command|check <name> [--domain <d>] [--yes]`
- `ai-rulez list agents|commands|checks [--domain <d>] [--format json]`

Checks are code-review guidelines (`.ai-rulez/checks/<name>.md`) and have no `--local`.

### Domains

- `ai-rulez domain add <name> [--description <desc>]`
- `ai-rulez domain remove <name> [--yes]`
- `ai-rulez domain list [--format json]`

### Profiles

- `ai-rulez profile add <name> <domains...>`
- `ai-rulez profile add <name> <domains...> [--set-default, -s]`
- `ai-rulez profile remove <name>`
- `ai-rulez profile list [--format json]`
- `ai-rulez profile set-default <name>`

### Includes

- `ai-rulez include add <name> <source> [--path <p>] [--ref <r>] [--include <types>] [--merge-strategy <s>] [--install-to <t>]`
- `ai-rulez include remove <name> [--yes]`
- `ai-rulez include list [--format json]`

### Installed Skills

- `ai-rulez skill install <name> --source <url> [--path <p>] [--ref <r>]`
- `ai-rulez skill remove <name> [--yes]`
- `ai-rulez skill list [--format json]`
- `ai-rulez skill update [name...]` — Re-pin installed skills in `ai-rulez.lock`

Commands that print JSON take `--format text|json`; `--json` was removed in v5.

## Roles, Lock and Catalog

- `ai-rulez roles list|show <name>|resolve <name> [--format json]` — Inspect `[[roles]]`; `list --format json` is the `roles.json` manifest
- `ai-rulez lock [name...]` — Pin remote includes, installed skills, skill sources, authored content and outputs in `ai-rulez.lock`. Flags: `--check` (offline, exit 2 and names each difference; exit 1 with no lock file), `--diff`, `--subject [--output <file>]`, `--outdated [--fail-on-outdated]`, `--content-only`, `--format text|json` (with `--check`, `--diff`, `--outdated`, `--subject`), `--kind include|skill|source|served`, `--profile`, `--role`, `--include-static`, `--source`, `--refuse-findings`, `--recursive`. Exit `3`: served skills left unpinned by the security scan
- `ai-rulez update [name...] [--dry-run] [--allow-downgrade] [--accept-moved-tag] [--kind include|skill|source] [--format json]` — Move `version` range pins to the newest allowed tag
- `ai-rulez catalog [--format json] [--schema-version 1|2]` — Items with owner, version, tokens, roles and lock status; `--html <dir>` writes a static site (`--role`, `--include-excerpt`, `--indexable`, `--clean`, `--base-title`, `--allow-findings AR001`)
- `ai-rulez sbom [--type cyclonedx] [--online] [-o <file>]` — CycloneDX 1.6 bill of materials
- `ai-rulez tokens [--role <name>] [--by-role] [--budget <n>] [--compare-profiles <p>] [--tokenizer ...] [--format json]` — Prompt-token surface per runtime; `ai-rulez cost [--target <preset>] [--top <n>] [--budget <n>] [--format text|json|markdown]` names the biggest offenders

## Verification, Search and Evals

- `ai-rulez verifiers run|list|explain|test` — Deterministic repo checks from `[[verifiers]]` and `.ai-rulez/verifiers/*.toml`; `run` takes `--since <rev>`, `--staged`, `--all`, `--rule`, `--name`, `--format text|json|sarif|junit`, `--output`, `--fail-on`, `--strict`, `--strict-applicability`
- `ai-rulez search <query> [--limit <n>] [--format json]` ranks the skills a skills server would serve (same selection flags as `mcp --serve-skills`); `search --eval <cases.yaml> [--k] [--min] [--baseline] [--max-flips] [--output]` measures the ranking
- `ai-rulez eval run [skill...]` — Run skill evals through a runner and score them (`--harness`, `--runner`, `--runner-command`, `--ablation`, `--dry-run`, `--max-cost`, `--changed-only`, `--force`, `--threshold`, `--format json|markdown|junit`); results are signed per user, so CI needs `--force`
- `ai-rulez telemetry hook|record|export|feedback`, `ai-rulez telemetry hook|record|flush|preview|doctor`, `ai-rulez telemetry report|evals` — Opt-in, identifier-only usage and item-load telemetry
- `ai-rulez llm doctor [--ping]` / `llm estimate <file>` — Inspect `[llm]` access without calling a model
- `ai-rulez local init|show|set|unset|path` — Manage the machine-local `config.local.*` overlay

## Exit Codes

`0` success, `1` the command could not run, `2` findings, drift or a failed gate (`validate`, `scan`, `generate --check`, `verify`, `lock --check`, `doctor`, `verifiers`, `eval`, budgets, ...), `3` `lock` only: served skills left unpinned.

## Other Commands

### `ai-rulez version`

Print version information.

### `ai-rulez builtins list`

List available built-in domains.
    • configuration.md 9.5 KB 
      # Configuration Reference

## config.toml Schema

```toml
version = "5.0"              # Required, must be "5.0"
name = "my-project"           # Required, project name

description = ""              # Optional project description

presets = [                   # Built-in names and/or custom preset tables
  "claude",
  "cursor",
  { name = "custom", type = "markdown", path = "docs/AI_GUIDE.md" },
]

default = ""                  # Default profile name
default_layers = ["plugins"]   # Select config.plugins.toml before any table

gitignore = true              # Opt in to the managed .gitignore block (default: false)
# agents_md = false           # Default true: one AGENTS.md, CLAUDE.md imports @AGENTS.md

builtins = true               # Enable all built-in domains
# builtins = false            # Disable all built-in domains
# builtins = ["go", "security", "!ai-governance"]  # Enable specific builtins

[profiles]                    # Profile → domain mappings
backend = ["backend", "shared", "builtin:docker"]  # builtin:<name> scopes a pack to this profile
frontend = ["frontend", "shared"]

[[scopes]]                    # Optional scoped outputs in subfolders
path = "packages/web"
profile = "frontend"
presets = ["codex", "claude"] # Defaults to codex + claude when omitted

[[installed_skills]]          # External skills to pull at generate time
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"
path = "skills/kreuzberg"     # Optional (defaults to skills/<name>)
ref = "main"                  # Optional git ref
local_override = "../local"   # Optional local dev path

[[includes]]                  # External content sources
name = "shared-rules"
source = "https://github.com/org/shared-rules"
path = ""                     # Subdirectory within repo
ref = "main"                  # Git ref
include = ["rules", "context", "skills"]  # Content types to import
merge_strategy = "local-override"  # local-override | include-override | error
install_to = ""               # Install as domain (e.g., "domains/backend")
local_override = ""           # Local dev path override

[defaults]
effort = "medium"             # low | medium | high | xhigh | max | inherit
# omit_agent_fields = ["model", "tools"]  # model | effort | tools | description

[defaults.effort_by_preset]   # Per-preset overrides (beat defaults.effort)
codex = "high"
claude = "xhigh"
amp = "max"

[header]
style = "detailed"            # detailed | compact | minimal
# hashes = "content"          # content (default: per-file Content-Hash) | full (adds project-wide Source-Hash) | none

[[mcp_servers]]
name = "ai-rulez"
command = "ai-rulez"
args = ["mcp"]

[[mcp_servers]]
name = "grafana"
command = "uvx"
args = ["mcp-grafana"]
env = { GRAFANA_URL = "http://localhost:3000", GRAFANA_SERVICE_ACCOUNT_TOKEN = "${GRAFANA_SERVICE_ACCOUNT_TOKEN}" }

[[roles]]                     # name, domains, skills/rules/agents/commands include+exclude, skill_mode, extends, match (docs/roles.md)
[role_manifest]               # enabled = true writes .ai-rulez/roles.json
[lock]                        # enforce, include_outputs, scope (docs/lockfile.md)
```

## Built-in Presets

| Preset       | Output Path                     |
| ------------ | ------------------------------- |
| claude       | CLAUDE.md                       |
| cursor       | .cursor/rules/, .cursor/commands/, .cursor/agents/, .agents/skills/ |
| gemini       | GEMINI.md, .gemini/, .agents/   |
| copilot      | .github/copilot-instructions.md, .github/{skills,agents,commands}/ |
| devin        | AGENTS.md, .devin/              |
| cline        | .clinerules/, .cline/           |
| codex        | AGENTS.md, .agents/skills/ and .codex/ |
| amp          | AGENTS.md and .agents/ (.amp/settings.json) |
| junie        | AGENTS.md and .junie/           |
| opencode     | AGENTS.md, .opencode/, opencode.json |
| hermes       | .hermes.md                      |
| antigravity  | .agents/, GEMINI.md             |
| xum          | AGENTS.md and .xum/             |
| pi           | AGENTS.md, .agents/skills, .pi/agents, .pi/mcp.json |
| baz          | AGENTS.md (root and nested), .agents/skills, .claude/agents |
| okf          | docs/okf/ (Open Knowledge Format bundle; `[okf] dir`) |

These are 15 of the 52 built-in presets. The rest: `aiassistant`, `augment`, `bob`, `codebuddy`, `codebuff`,
`codewhale`, `commandcode`, `copilot-cli`, `cortex`, `crush`, `deepagents`, `dsh`, `factory`, `gitlab-duo`, `goose`,
`grok`, `kilo`, `kimi`, `kiro`, `letta`, `mimocode`, `muse`, `omp`, `openclaw`, `poolside`, `qoder`, `qwen`,
`reasonix`, `replit`, `rovodev`, `takt`, `trae`, `vibe`, `warp`, `zcode`, `zed`, `zoocode`. See
`docs/harnesses.md` for the feature matrix. `windsurf` was renamed `devin`; `continue-dev` was removed.

## Hooks and Permissions

```toml
[[hooks]]
event = "PreToolUse"
matcher = "Bash"
[[hooks.hooks]]
script = "scripts/guard.sh"          # or: command = "..."

[permissions]
allow = ["Bash(npm run test:*)"]
ask   = ["Bash(git push:*)"]
deny  = ["Read(./.env)"]
```

Both use Claude Code names and syntax and are translated per harness (`docs/settings.md`, `docs/permissions.md`).
`generate --user` renders a user config into home directories (`docs/user-scope.md`).

## Available Builtins

Language domains: `rust`, `python`, `typescript`, `go`, `java`, `ruby`, `php`, `elixir`, `csharp`, `r`

Cross-language binding domains: `pyo3`, `napi-rs`, `magnus`, `ext-php-rs`, `rustler`, `wasm`, `jni-rs`, `extendr`, `cgo`, `vite-plus`

Practice domains: `ai-governance` (auto), `agent-delegation` (auto), `code-quality` (auto), `testing` (auto), `git-workflow` (auto), `security` (auto), `token-efficiency` (auto), `documentation`, `polyglot-bindings`, `default-commands`, `cicd`, `observability`, `docker`

## Content Frontmatter Fields

```yaml
---
type: Principle
title: TypeScript conventions
x-ai-rulez:
  kind: rule
  id: typescript-conventions
  metadata:
    priority: medium
    targets:
      - CLAUDE.md
      - .cursor/rules/*
    globs:
      - "**/*.tsx"
---
```

For authored `.ai-rulez/` content, use OKF frontmatter and tool metadata under
`x-ai-rulez.metadata`. Public `skills/<name>/SKILL.md` exports use native Agent
Skills `name`/`description` frontmatter. `migrate okf --check` detects older
authored formats; legacy fields remain readable for migration.

## Plugin layer

Keep marketplace registries (`[[marketplaces]]`) and producer `[plugin]` and
`[marketplace]` in `config.plugins.toml`. Deprecated `[[plugins]]` consumer
entries have no effect; configure plugin enablement in the harness settings. The root's `default_layers` selects
that file. Plugin metadata does not belong to the root governance config.
Use a separate author root for public product capabilities when contributor
rules and maintainer agents should stay private to the repository.

## Merge Strategies

- **local-override** (default): Local content wins on name conflicts
- **include-override**: Included content wins on conflicts
- **error**: Fail immediately on any name conflict

## MCP Environment Placeholders

MCP server env values may use `${VAR}` placeholders. Placeholder names must match
`[A-Za-z_][A-Za-z0-9_]*` and are resolved during `ai-rulez generate` from repeated
`--env KEY=VALUE` flags, process environment variables, then dotenv files. By default,
`.env` is loaded from the generation base directory. If `--env-file` is supplied, the
default `.env` is skipped; multiple env files are merged in flag order, with later files
winning.

Generated MCP configs contain resolved values. If an env value came from a placeholder, or
if an env key contains `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, or `CREDENTIAL`, generation
fails before writing unless the generated MCP config path is gitignored or covered by
planned `--gitignore` patterns. Secret values are redacted before source-hash calculation.

## Profile Resolution

1. If `profiles.default` is explicitly defined → use it
2. If no profiles are defined → include root + all domains
3. If profiles exist but `default` is not among them → include root + builtin + FromInclude domains

## Config Directory and Generated Manifest

- `.ai-rulez/` remains the default config root.
- Config discovery also accepts the project-level `.config/` convention: `.config/ai-rulez/config.toml`. `.ai-rulez/` wins when both exist at the same level. Only version 5.0 TOML configurations are read. For a 4.x project, run `pnpm dlx ai-rulez@5.4.1 migrate v5`; for older formats, follow the staged migration in [the v5 migration guide](https://github.com/Goldziher/ai-rulez/blob/main/docs/migration-v5.md).
- `ai-rulez init --config-dir .config/ai-rulez` scaffolds the `.config/` layout; generated outputs and the managed `.gitignore` block then reference `.config/ai-rulez/`.
- `ai-rulez generate --config-dir <name>` and `validate --config-dir <name>` use another config directory (nested values such as `.config/ai-rulez` are supported).
- `ai-rulez --config <path/to/config.toml> generate` loads that exact file.
- Generation writes `.generated-manifest.json` under the active config directory and removes only stale files listed in that manifest.
- Assistant directories such as `.claude/`, `.codex/`, `.cursor/`, `.gemini/`, `.devin/`, and `.agents/` are not considered fully owned; user settings, hooks, personal skills, and other local files are preserved.

## Scoped Outputs

Use `[[scopes]]` to generate subfolder-specific `AGENTS.md` and `CLAUDE.md` files with separate profile content:

```toml
[profiles]
frontend = ["frontend"]

[[scopes]]
path = "packages/web"
profile = "frontend"
presets = ["codex", "claude"]
```

Root output and scoped output are generated independently. `--dry-run` shows the target paths for both.
    • includes-and-skills.md 4.4 KB 
      # Includes and Installed Skills

## Includes

Includes let you import rules, context, skills, agents, and commands from external git repositories or local paths. (MCP servers are not importable from an include.)

### Adding Includes

```bash
# From a git repository
ai-rulez include add shared-rules https://github.com/org/shared-rules

# With specific content types
ai-rulez include add shared-rules https://github.com/org/shared-rules --include rules,context

# Install into a domain
ai-rulez include add backend-rules https://github.com/org/backend --install-to domains/backend

# With merge strategy
ai-rulez include add overrides https://github.com/org/overrides --merge-strategy include-override

# Local path
ai-rulez include add local-rules ./path/to/local
```

### Include Config Options

```toml
[[includes]]
name = "shared-rules"
source = "https://github.com/org/shared-rules"
path = "modules/core"              # Subdirectory within repo containing .ai-rulez/
ref = "v2.0"                       # Branch, tag, or commit
include = ["rules", "context"]     # Content types (default: all)
merge_strategy = "local-override"
install_to = "domains/shared"      # Install as domain instead of merging at root
local_override = "../local-shared" # Use local path for development
```

### How Includes Work

1. During config load, each include source is fetched with sparse git checkout or local scan
2. The source may use an `.ai-rulez/` wrapper or a bare/flattened layout (a directory exposing `rules/`, `context/`, `skills/`, `agents/`, or `commands/` directly, at the repo root or under `path`)
3. Content is merged with local content using the configured merge strategy
4. Domains from includes are marked as `FromInclude` and always included regardless of profile

### Local Override

The `local_override` field lets you point to a local checkout during development. If the path exists, it's used instead of the git source. If it doesn't exist, the include is silently skipped.

## Installed Skills

Installed skills are named skills fetched from external repositories at generation time. Unlike includes (which import `.ai-rulez/` content), installed skills expect a `skills/<name>/SKILL.md` structure at the repository root.

### Installing Skills

```bash
# Install by name (defaults to skills/<name>/ path in repo)
ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg

# With explicit path
ai-rulez skill install my-skill --source https://github.com/org/repo --path custom/skill/path

# With specific git ref
ai-rulez skill install my-skill --source https://github.com/org/repo --ref v2.0
```

### Installed Skills Config

```toml
[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"
path = "skills/kreuzberg"       # Optional, defaults to skills/<name>
ref = "main"                    # Optional git ref
local_override = "../kreuzberg" # Optional local dev path
```

### Skill Directory Structure

```text
repo-root/
  skills/
    my-skill/
      SKILL.md                 # Required - main skill content with frontmatter
      references/              # Optional - additional reference documents
        api-reference.md
        configuration.md
      scripts/                 # Optional - executable helper scripts
      assets/                  # Optional - static files or images
```

### How Installed Skills Work

1. During `ai-rulez generate`, each installed skill is fetched from its source
2. `SKILL.md` is read and parsed (frontmatter + content)
3. `references/`, `scripts/`, and `assets/` are loaded as skill resources
4. Presets with skill directories emit resources as sibling files and add a resource index to `SKILL.md`
5. The skill is added to the root-level skills in the content tree
6. Local skills with the same name take precedence (installed skill is skipped with a warning)

### Creating Distributable Skills

To make your project's skill installable:

1. Create `skills/<name>/SKILL.md` at your repository root
2. Add YAML frontmatter with `name`, `description`, and optional `metadata`
3. Write comprehensive instructions in the skill body
4. Optionally add `references/*.md` for detailed reference documentation

```yaml
---
name: my-library
description: >-
  Brief description of what this skill covers and when to use it.
license: MIT
metadata:
  author: your-org
  version: "1.0"
  repository: https://github.com/your-org/your-repo
---
# My Library

Instructions for AI assistants working with your library...
```
    • presets-and-outputs.md 7.4 KB 
      # Presets and Output Generation

## Generation Flow

1. Load the selected config root (default `.ai-rulez/config.toml`) and scan content directories
2. Load builtins (lowest priority)
3. Resolve includes (merge external content)
4. Resolve installed skills (fetch and add to content tree)
5. Select profile → determine active domains
6. Generate preset outputs from combined content, including configured scoped subfolder outputs
7. Remove stale files from `.generated-manifest.json`, write outputs, update the manifest, and (when `gitignore = true`) update the managed `.gitignore` block

## Built-in Presets

Configure in `config.toml`:

```toml
presets = [
  "claude",       # → CLAUDE.md
  "cursor",       # → .cursor/rules/*.mdc
  "gemini",       # → GEMINI.md
  "copilot",      # → .github/copilot-instructions.md
  "devin",        # → AGENTS.md, .devin/
  "cline",        # → .clinerules/, .cline/
  "codex",        # → AGENTS.md, .agents/skills/ and .codex/
  "amp",          # → AGENTS.md and .agents/ (.amp/settings.json)
  "junie",        # → AGENTS.md and .junie/
  "opencode",     # → AGENTS.md, .opencode/, opencode.json
  "hermes",       # → .hermes.md
  "antigravity",  # → .agents/, GEMINI.md
  "xum",          # → AGENTS.md, .xum/skills, .xum/agents, .xum/mcp.jsonc
  "pi",           # → AGENTS.md, .agents/skills, .pi/agents, .pi/mcp.json
  "baz",          # → AGENTS.md (root and nested), .agents/skills, .claude/agents
  "okf"           # → docs/okf/ (Open Knowledge Format bundle)
]
```

These are 15 of the 52 built-in presets. The others: `aiassistant`, `augment`, `bob`, `codebuddy`, `codebuff`,
`codewhale`, `commandcode`, `copilot-cli`, `cortex`, `crush`, `deepagents`, `dsh`, `factory`, `gitlab-duo`, `goose`,
`grok`, `kilo`, `kimi`, `kiro`, `letta`, `mimocode`, `muse`, `omp`, `openclaw`, `poolside`, `qoder`, `qwen`,
`reasonix`, `replit`, `rovodev`, `takt`, `trae`, `vibe`, `warp`, `zcode`, `zed`, `zoocode`. `docs/harnesses.md` is the
matrix of what each writes (rules folder, skills, agents, commands, MCP, hooks, permissions, checks, user scope).

Removed and renamed: `windsurf` is `devin` (`.windsurf/` is `.devin/`, `windsurf_model` is `devin_model`);
`continue-dev` is gone.

## Features by Preset Family

- **Hooks**: top-level `[[hooks]]` render for 36 harnesses, into the harness's settings file or a generated plugin
  module (`opencode`, `kilo`, `mimocode`, `pi`, `amp`). `junie`, `zcode`, `hermes` and `kimi` read hooks from the
  user config only, so they need `generate --user`.
- **Permissions**: top-level `[permissions]` render for 24 harnesses. `amp`, `pi`, `cline`, `kiro`, `factory`,
  `crush` and `rovodev` have no committable permission file and are named in a warning.
- **Checks**: authored files at `.ai-rulez/checks/<name>.md` render for `cursor`, `kilo`, `qwen`, `factory`, `rovodev`, `amp`, `augment` and
  `gitlab-duo`.
- **User scope**: `generate --user` supports 47 presets; `aiassistant`, `baz`, `codebuff`, `replit` and `xum` have no
  user-level location.
- **Commands as skills**: `claude`, `codex`, `antigravity`, `devin` and `warp` write commands as skills.
- **Shared outputs**: presets that write the same path must render identical bytes, otherwise `generate` fails and
  names them.

## Reasoning Effort Per Preset

When `defaults.effort` or `defaults.effort_by_preset` is set, presets with native effort support emit it:

| Preset     | File                                            | Field                    | Scope                |
| ---------- | ----------------------------------------------- | ------------------------ | -------------------- |
| `claude`   | `.claude/agents/<id>.md`                        | `effort`                 | per-agent            |
| `codex`    | `.codex/config.toml`, `.codex/agents/<id>.toml` | `model_reasoning_effort` | global and per-agent |
| `amp`      | `.amp/settings.json`                            | `amp.anthropic.effort`   | global               |
| `devin`    | `.devin/agents/<id>.md`                         | `reasoning_effort`       | per-agent            |
| `opencode` | `.opencode/agents/<id>.md`                      | `variant`                | per-agent            |
| `xum`      | `.xum/agents/<id>.md`                           | `ai.thinkingLevel`       | per-agent            |
| `pi`       | `.pi/agents/<id>.md`                            | `thinking`               | per-agent            |

Resolution order: per-agent metadata → `defaults.effort_by_preset[<preset>]` → `defaults.effort` → omit. Each preset maps the canonical tier to its own vocabulary (e.g. Codex caps at `xhigh`/drops `inherit`; Amp uses `max` instead of `xhigh`). Other presets (cursor, copilot, gemini, junie, hermes, antigravity, cline) silently skip — those tools expose effort via UI toggles or user-managed config files we don't generate.

## Custom Presets

Define custom output formats:

```toml
[[presets]]
name = "team-guide"
type = "markdown"        # Single markdown file
path = "docs/AI_GUIDE.md"

[[presets]]
name = "rules-dir"
type = "directory"       # Directory of files
path = ".ai-rules/"

[[presets]]
name = "config-json"
type = "json"            # JSON output
path = ".ai-config.json"
```

For full parity with a built-in preset (skills, agents, commands, MCP sidecars),
point a custom preset at a declarative provider spec instead of a template:

```toml
[[presets]]
name = "my-tool"
provider = ".ai-rulez/providers/my-tool.toml"   # relative to the project root
```

The spec is validated against `schema/provider.schema.json` and its `name` must
match the preset's `name`.

## Profile-based Generation

```bash
# Generate with default profile
ai-rulez generate

# Generate with specific profile
ai-rulez generate --profile backend

# Preview without writing
ai-rulez generate --dry-run

# Use a non-default config directory
ai-rulez generate --config-dir ai-policy
```

## Content Priority

Content is rendered in priority order: critical → high → medium → low → minimal.

## Target Filtering

Use `targets` in frontmatter to limit content to specific outputs:

```yaml
---
targets:
  - CLAUDE.md # Only included in Claude output
  - .cursor/rules/* # Only included in Cursor output
---
```

Content without `targets` is included in all outputs.

## Header Styles

Control generated file headers:

- **detailed**: Full header with tool info, generation notice, and instructions
- **compact**: Brief header with tool name and generation notice
- **minimal**: Bare minimum header

## MCP Server Integration

MCP servers are configured inline in `config.toml` under `[[mcp_servers]]`, allowing assistants to access ai-rulez functionality without a separate service.

Env values may use `${VAR}` placeholders resolved by `generate` from `--env`, process env, and dotenv files. Generated MCP configs contain resolved values, so secret-bearing MCP outputs must be gitignored before they are written.

## Cleanup Safety

Generation no longer treats assistant directories as fully owned. Stale cleanup is manifest-based:

- The manifest lives at `<config-dir>/.generated-manifest.json`.
- Only files listed in the previous manifest can be deleted as stale.
- User-owned files in `.claude/`, `.codex/`, `.cursor/`, `.gemini/`, `.devin/`, `.cline/`, `.agents/`, `.opencode/`, `.junie/`, and custom output directories are preserved.
- `ai-rulez generate --dry-run` prints `write-file`, `unchanged`, `edited` and `delete-stale` entries without changing the filesystem.
  • SKILL.md 17.8 KB 
    ---
name: ai-rulez
description: >-
  Standards-compliant lifecycle tool for agent knowledge and capabilities:
  author in .ai-rulez/, generate for 52 harnesses (Claude Code, Cursor, Codex,
  Copilot, Gemini CLI, OpenCode, Devin, and more), bundle (OKF, Agent Plugins,
  ARD), validate, govern (lock, approvals, signing, SBOM) and publish. Use when
  configuring rules, context, skills, checks, hooks, permissions, domains,
  profiles, includes, plugins, or generating tool-specific outputs.
license: MIT
metadata:
  author: Goldziher
  version: "5.4.1"
  repository: https://github.com/Goldziher/ai-rulez
---

# AI-Rulez

AI-Rulez is a standards-compliant lifecycle tool for agent knowledge and capabilities. It keeps one source of truth in a config directory (default `.ai-rulez/`) and takes it through author, generate (52 built-in harness presets: Claude Code, Cursor, Codex, Copilot, Gemini CLI, OpenCode, Devin, and others), bundle (OKF, Agent Plugins, ARD), lint and validate, govern (lock, approvals, Sigstore signing, policy, SBOM) and publish.

Use this skill when:

- Setting up or modifying `.ai-rulez/` configuration
- Writing rules, context, skills, agents, commands, or checks for AI assistants
- Declaring `[[hooks]]` or `[permissions]` once for every harness
- Generating a personal config into the home directory with `generate --user`
- Configuring domains, profiles, or includes
- Using custom config directory names via `--config-dir`
- Generating outputs for specific AI tools
- Auditing planned writes/deletes with `--dry-run`
- Installing or managing external skills

## Installation

```bash
# npm (no install)
pnpm dlx ai-rulez@5.4.1

# Python (no install)
uvx ai-rulez==5.4.1

# Source builds (Go + Task; setup fetches and verifies the pinned native library)
# Checkout the source revision pinned in this repository's CI, then:
task build
```

Package commands use the published release. Source builds also need the pinned
Liter-LLM native library: `task build` provisions it through
`scripts/setup-liter-llm.sh`; a bare `go install` does not do that setup.
Version 5.4.0 includes the governance and plugin validation fixes described below.
For a reviewed source build, use the exact revision recorded in the CI workflow.

## Quick Start

```bash
# Initialize a new project
ai-rulez init

# Add rules and context
ai-rulez add rule my-rule --priority high
ai-rulez add context my-context

# Generate outputs for all configured presets
ai-rulez generate

# Regenerate whenever .ai-rulez/ changes
ai-rulez generate --watch

# Validate configuration
ai-rulez validate

# Read-only diagnostics: drift, removed presets, missing tools
ai-rulez doctor
```

## Lifecycle commands

```bash
ai-rulez generate --plugin              # bundle: plugin bundles from the [plugin] block
ai-rulez export okf                     # bundle: an OKF bundle of the knowledge
ai-rulez validate --strict              # validate: warnings fail
ai-rulez okf validate <bundle-dir>      # validate: an existing OKF bundle directory
ai-rulez lock                           # govern: pin includes, skills and content
ai-rulez sign --lock                    # govern: Sigstore attestation of the lock
ai-rulez sbom -o ai-bom.cdx.json        # govern: CycloneDX SBOM
ai-rulez publish --dry-run              # publish: preview release artifacts
```

Supported and planned standards, with pinned versions and test status, are in
<https://goldziher.github.io/ai-rulez/standards/>.

## Other sources and config-free checks

- `source = "agents"` (or a configuration in `.agents/ai-rulez.toml`) reads the root and nested `AGENTS.md` and `.agents/` (skills, rules, agents, checks, commands, context, domains) instead of `.ai-rulez/`; `generate` translates them to every other tool and never writes `AGENTS.md` or `.agents/`. `agents_md_split = true` reads `AGENTS.md` as one item per `##` heading. Start with `ai-rulez init --source agents`.
- `ai-rulez validate --strict` works in a repository with no ai-rulez config, linting the files that follow a convention; `--path`, `--glob` and `--outputs` choose what else to lint.
- `ai-rulez judge --estimate --model openai/gpt-4o-mini` previews a model grading of instruction files, again with no config; add `--allow-llm` to send.

## Configuration Structure

```text
.ai-rulez/
  config.toml          # Governance configuration
  config.plugins.toml  # Plugin and marketplace layer, selected by default_layers
  rules/               # Governance rules (.md files with frontmatter)
  context/             # Contextual information (.md files)
  skills/              # Specialized capabilities (name/SKILL.md plus resources)
  agents/              # Agent definitions (.md files)
  commands/            # Custom commands (.md files)
  checks/              # Code-review guidelines (.md files)
  domains/             # Domain-scoped content
    backend/
      rules/
      context/
      skills/
```

## config.toml

Keep governance in `config.toml`. Put marketplace registries (`[[marketplaces]]`) and authoring
`[plugin]`/`[marketplace]` blocks in `config.plugins.toml`, and select that layer with
`default_layers = ["plugins"]` before the first table in `config.toml`. Plugin authoring
can use a separate `plugin/.ai-rulez/` tree so public product skills exclude contributor rules.

```toml
version = "5.0"
name = "my-project"
description = "Project description"

presets = ["claude", "cursor", "gemini"]
default_layers = ["plugins"]
default = "backend"
builtins = ["go", "security", "testing"]

[profiles]
backend = ["backend", "shared"]
frontend = ["frontend", "shared"]

[[includes]]
name = "shared-rules"
source = "https://github.com/org/shared-rules"

[[installed_skills]]
name = "kreuzberg"
source = "https://github.com/kreuzberg-dev/kreuzberg"

[[mcp_servers]]
name = "ai-rulez"
command = "pnpm"
args = ["dlx", "ai-rulez@5.4.1", "mcp"]

[[scopes]]
path = "packages/web"
profile = "frontend"
presets = ["codex", "claude"]
```

## Content Frontmatter

Authored `.ai-rulez/` content uses OKF frontmatter: `type`, `title` and an
`x-ai-rulez` identity. Tool-specific fields belong in `x-ai-rulez.metadata`.
Use `Principle` for rules, `Concept` for context, `Playbook` for skills and
`Reference` for agents. For example, `.ai-rulez/rules/project-conventions.md`:

```yaml
---
type: Principle
title: Project conventions
description: Shared project conventions
x-ai-rulez:
  kind: rule
  id: project-conventions
  metadata:
    priority: high
    targets:
      - CLAUDE.md
      - .cursor/rules/*
---
```

`priority` accepts `critical`, `high`, `medium`, `low` and `minimal`. Older flat
frontmatter remains readable for migration; run `ai-rulez migrate okf` to convert
it and `ai-rulez migrate okf --check` to verify the authored tree.

For public plugin skills, set `x-ai-rulez.metadata.name` to a stable lowercase
slug matching the skill directory and `x-ai-rulez.id`. This supplies the required
native Agent Skills name across runtime projections.

Public `skills/<name>/SKILL.md` exports use native Agent Skills frontmatter,
including `name` and `description`, without the OKF wrapper. This public skill
is such an export; its frontmatter is not the authoring format for `.ai-rulez/`.

### Agent-only fields

Agent files under `.ai-rulez/agents/` put native subagent fields inside
`x-ai-rulez.metadata`. Supported fields render into the configured harness;
fields a harness does not support are omitted. For example, create
`.ai-rulez/agents/<agent-id>.md` with `security-reviewer` as the ID:

```yaml
---
type: Reference
title: Security reviewer
description: Reviews code for security regressions
x-ai-rulez:
  kind: agent
  id: security-reviewer
  metadata:
    name: security-reviewer
    model: opus
    effort: high
    permissionMode: default
    tools:
      - Read
      - Grep
      - Glob
---
```

Claude Code receives these fields in `.claude/agents/<agent-id>.md` using
its native flat frontmatter. Keep the authored OKF file and generated native
file distinct.

`effort` controls reasoning depth. Set a project-wide default and per-preset
overrides in `config.toml`:

```toml
[defaults]
effort = "medium"

[defaults.effort_by_preset]
codex = "high"      # Codex applies it globally and per agent
claude = "xhigh"    # Claude applies it as `effort` per agent
amp = "max"         # Amp writes amp.anthropic.effort to .amp/settings.json
```

Resolution order (per preset, per agent): per-agent `effort` →
`defaults.effort_by_preset[<preset>]` → `defaults.effort` → omit.

Per-preset support:

- **Claude**: per-agent in `.claude/agents/*.md` (full vocabulary including `max`; `inherit` is not a Claude value and is dropped)
- **Codex**: global in `.codex/config.toml` and per-agent in `.codex/agents/*.toml` (`max` → `high`; `inherit` dropped)
- **Amp**: global in `.amp/settings.json` (`xhigh` → `high`)
- **Devin**: per-agent in `.devin/agents/*.md` frontmatter (`max` → `high`)
- **Opencode**: per-agent `variant` in `.opencode/agents/*.md` (joins the agent's `model` as `model#variant`)
- Cursor, Copilot, Gemini, Junie, Antigravity, Cline: silently skipped (those tools expose effort via UI toggles or user-managed config files we don't generate).

## Domains and Profiles

Domains group content for different teams or concerns. Profiles select which domains are active.

```bash
ai-rulez domain add backend
ai-rulez add rule api-standards --domain backend
ai-rulez profile add backend-team backend shared
ai-rulez generate --profile backend-team
```

## Includes

Share rules across projects using git repositories or local paths:

```bash
ai-rulez include add shared-rules https://github.com/org/shared-rules
ai-rulez include add local-rules ./path/to/local --merge-strategy include-override
```

## Installed Skills

Install named skills from external repositories:

```bash
ai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg
ai-rulez skill install ai-rulez --source https://github.com/Goldziher/ai-rulez
ai-rulez skill list
ai-rulez skill remove kreuzberg
```

Skills are fetched dynamically at generation time and included in outputs.
Skill `references/`, `scripts/`, and `assets/` directories are preserved as separate generated resource files when the target preset supports skill directories.

## Built-in Presets

52 presets are available (`ai-rulez init` writes the list into a comment in the new `config.toml`): `aiassistant`, `amp`, `antigravity`, `augment`, `baz`, `bob`, `claude`, `cline`, `codebuddy`, `codebuff`, `codewhale`, `codex`, `commandcode`, `copilot`, `copilot-cli`, `cortex`, `crush`, `cursor`, `deepagents`, `devin`, `dsh`, `factory`, `gemini`, `gitlab-duo`, `goose`, `grok`, `hermes`, `junie`, `kilo`, `kimi`, `kiro`, `letta`, `mimocode`, `muse`, `omp`, `openclaw`, `opencode`, `pi`, `poolside`, `qoder`, `qwen`, `reasonix`, `replit`, `rovodev`, `takt`, `trae`, `vibe`, `warp`, `xum`, `zcode`, `zed`, `zoocode`, plus the opt-in `okf` preset (creates an Open Knowledge Format bundle at `<project-root>/docs/okf/` by default; see `ai-rulez export okf`). The `mcp` preset is a shared utility (the generic `.mcp.json`) invoked automatically when MCP servers are configured.

`windsurf` is now `devin` and `continue-dev` was removed; `ai-rulez doctor` reports both. [harnesses.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/harnesses.md) has the per-preset feature matrix (rules folder, skills, agents, commands, MCP, hooks, permissions, checks, user scope).

## Hooks, Permissions, Checks and User Scope

- `[[hooks]]` in `config.toml` renders into the native hooks file of 36 harnesses (a generated plugin module for `opencode`, `kilo`, `mimocode`, `pi` and `amp`). Events, matchers and timeouts are translated per harness; a group a harness cannot express is skipped with a warning. See [settings.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/settings.md).
- `[permissions]` (`allow`, `ask`, `deny`, Claude Code rule syntax) is translated for 24 harnesses. A rule that cannot be expressed is skipped, never widened, and an unenforced deny is reported. See [permissions.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/permissions.md).
- Checks are code-review guidelines in `.ai-rulez/checks/<name>.md` (OKF `description` and `x-ai-rulez.metadata` fields `severity`, `tools`, `targets`), rendered for `cursor`, `kilo`, `qwen`, `factory`, `rovodev`, `amp`, `augment` and `gitlab-duo`. Manage them with `ai-rulez add|remove|list check`. See [checks.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/checks.md).
- `ai-rulez generate --user` renders a user config (`~/.config/ai-rulez`) into the home directories of 47 harnesses; `clean --user` removes what it wrote. See [user-scope.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/user-scope.md).
- Settings files you also edit (JSON, JSONC, TOML, YAML) are merged key by key, so your own keys and comments survive `generate` and `clean`.
- `[guard] generated = true` adds a PreToolUse hook (`ai-rulez guard`) that blocks agent edits to generated files and points at the source under `.ai-rulez/`.

## Lock, Updates and Verification

- `ai-rulez lock` writes `ai-rulez.lock`: commits and digests of remote includes, installed skills and skill sources, plus every authored item and generated output. It is enforced whenever the file exists (`[lock] enforce = false` opts out). `lock --check` verifies offline, `--diff` previews, `--subject` prints the digest to sign with cosign, `generate --locked`/`--frozen` are the CI modes. Exit codes: `0` ok, `1` could not run, `2` drift, `3` served skills left unpinned by the security scan. See [lockfile.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/lockfile.md).
- Sources accept `version = "^1.2"`; `ai-rulez lock --outdated` lists newer tags and `ai-rulez update` moves range pins (codes `AR730`, `AR731`, `AR732`, `AR735`).
- `ai-rulez validate` runs deep content checks with stable `AR` codes (`--fix`, `--since`, `--baseline`, `--format json|sarif|github|junit|markdown`); `ai-rulez scan` runs only the security checks; `validate --explain AR001` explains a rule. See [strict-validation.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/strict-validation.md).
- `[[verifiers]]` and `.ai-rulez/verifiers/*.toml` declare deterministic repo checks run by `ai-rulez verifiers run` (`--since`, `--staged`, `--format sarif|junit`).
- `ai-rulez sbom` prints a CycloneDX bill of materials, `ai-rulez catalog` lists every item with owner, version, tokens and lock status (`--html <dir>` writes a static site), `ai-rulez tokens` and `cost` report prompt-token cost, `ai-rulez search <query>` ranks skills.
- `ai-rulez convert` imports existing tool files, a rulesync project or a `skills-lock.json` into `.ai-rulez/` with a lossiness report.

## Roles and Dynamic Skills

- `[[roles]]` map a job to a slice of the content (`domains`, `include`/`exclude` selectors, `skill_mode`); `generate --role <name>` renders it and `ai-rulez roles list|show|resolve` inspects it. See [roles.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/roles.md).
- `delivery: static|served|both` in an authored skill's `x-ai-rulez.metadata` (or `[skills] delivery`) serves a skill over MCP on demand instead of writing it to the harness trees: run `ai-rulez mcp --serve-skills` (`find_skill`, `load_skill`, `list_skill_resources`). `[[skill_sources]]` serve skills from a git repository or directory. See [mcp-server.md](https://github.com/Goldziher/ai-rulez/blob/main/docs/mcp-server.md).

A tool that isn't built in can be supported at full parity with a provider-backed custom preset: set `provider = "<project-relative spec.toml>"` and point it at a declarative spec validated against `schema/provider.schema.json`. See the `ai-rulez` references for the spec shape.

## MCP Integration

MCP servers are configured inline in `config.toml` with `[[mcp_servers]]`. ai-rulez exposes an MCP server for AI assistants to read, create, update, validate, dry-run, and generate configuration:

```bash
ai-rulez mcp
```

Configure in your AI tool's MCP settings to enable CRUD operations from within the assistant.

MCP server env values can use `${VAR}` placeholders. `ai-rulez generate` resolves them from `--env`,
process env, and dotenv files, then refuses to write secret-bearing generated MCP configs unless the
target paths are gitignored (`gitignore = true` or `generate --gitignore` adds them to the managed block).

## Plugins and Marketplaces

ai-rulez can package the same source (skills, commands, agents, MCP servers) as distributable plugin bundles and a marketplace index for Claude, Cursor, Codex, Gemini, Kimi, OpenCode, Factory, Hermes, Pi, Agent Plugins and Copilot via `ai-rulez generate --plugin`. Consumer `[[plugins]]`/`[[marketplaces]]` arrays declare plugins to install from a marketplace (no output file is written for them: `generate` warns that `[[plugins]]` has no effect; enable plugins through `[claude.settings]` for Claude Code and `.codex/config.toml` for Codex).

## Verification and distribution

Use `migrate okf --check`, `validate --strict --no-local`, `lock --check`, and
`generate --check --no-local --strict-config` to check the authored configuration.
For published plugins, use `verify --plugin` before regenerating to detect existing
drift; after intentional regeneration, check it again and verify public skill exports.
Package from a committed tree with `publish --tag <release-tag>`, then run
`publish verify <dist-directory>` on the actual archive. A successful local package
does not publish a release or registry package.

Version 5.4.0 includes fixes for registered marketplace members, both-layout MCP ownership,
OpenCode skill IDs and shared include-cache locking. The repository validates with a reviewed
source build pinned in CI; use that exact source revision when reproducing its checks.

The exact reviewed source revision is recorded in
`.github/workflows/ai-rulez-validation.yml`. It includes the ID-only OKF skill
projection fix, strict Hermes package metadata, and cache isolation by configured
source path and revision. Use that workflow as the source of truth for the pin.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude