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), b
SKILL.mdskills/ai-rulez/SKILL.md
GitHubAI-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.5.3
# Python (no install)
uvx ai-rulez==5.5.3
# 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 nestedAGENTS.mdand.agents/(skills, rules, agents, checks, commands, context, domains) instead of.ai-rulez/;generatetranslates them to every other tool and never writesAGENTS.mdor.agents/.agents_md_split = truereadsAGENTS.mdas one item per##heading. Start withai-rulez init --source agents.ai-rulez validate --strictworks in a repository with no ai-rulez config, linting the files that follow a convention;--path,--globand--outputschoose what else to lint.ai-rulez judge --estimate --model openai/gpt-4o-minipreviews a model grading of instruction files, again with no config; add--allow-llmto 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.5.3", "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 includingmax;inheritis not a Claude value and is dropped) - Codex: global in
.codex/config.tomland per-agent in.codex/agents/*.toml(max→high;inheritdropped) - Amp: global in
.amp/settings.json(xhigh→high) - Devin: per-agent in
.devin/agents/*.mdfrontmatter (max→high) - Opencode: per-agent
variantin.opencode/agents/*.md(joins the agent'smodelasmodel#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]]inconfig.tomlrenders into the native hooks file of 36 harnesses (a generated plugin module foropencode,kilo,mimocode,piandamp). 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(OKFdescriptionandx-ai-rulez.metadatafieldsseverity,tools,targets), rendered forcursor,kilo,qwen,factory,rovodev,amp,augmentandgitlab-duo. Manage them withai-rulez add|remove|list check. See checks.md. ai-rulez generate --userrenders a user config (~/.config/ai-rulez) into the home directories of 47 harnesses;clean --userremoves 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
generateandclean. [guard] generated = trueadds 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 lockwritesai-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 = falseopts out).lock --checkverifies offline,--diffpreviews,--subjectprints the digest to sign with cosign,generate --locked/--frozenare the CI modes. Exit codes:0ok,1could not run,2drift,3served skills left unpinned by the security scan. See lockfile.md.- Sources accept
version = "^1.2";ai-rulez lock --outdatedlists newer tags andai-rulez updatemoves range pins (codesAR730,AR731,AR732,AR735). ai-rulez validateruns deep content checks with stableARcodes (--fix,--since,--baseline,--format json|sarif|github|junit|markdown);ai-rulez scanruns only the security checks;validate --explain AR001explains a rule. See strict-validation.md.[[verifiers]]and.ai-rulez/verifiers/*.tomldeclare deterministic repo checks run byai-rulez verifiers run(--since,--staged,--format sarif|junit).ai-rulez sbomprints a CycloneDX bill of materials,ai-rulez cataloglists every item with owner, version, tokens and lock status (--html <dir>writes a static site),ai-rulez tokensandcostreport prompt-token cost,ai-rulez search <query>ranks skills.ai-rulez convertimports existing tool files, a rulesync project or askills-lock.jsoninto.ai-rulez/with a lossiness report.
Roles and Dynamic Skills
[[roles]]map a job to a slice of the content (domains,include/excludeselectors,skill_mode);generate --role <name>renders it andai-rulez roles list|show|resolveinspects it. See roles.md.delivery: static|served|bothin an authored skill'sx-ai-rulez.metadata(or[skills] delivery) serves a skill over MCP on demand instead of writing it to the harness trees: runai-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.