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:
\n.ai-rulez/ configuration[[hooks]] or [permissions] once for every harnessgenerate --user--config-dir--dry-run# npm (no install)\npnpm dlx ai-rulez@5.4.1\n\n# Python (no install)\nuvx ai-rulez==5.4.1\n\n# Source builds (Go + Task; setup fetches and verifies the pinned native library)\n# Checkout the source revision pinned in this repository's CI, then:\ntask build\nPackage commands use the published release. Source builds also need the pinned\nLiter-LLM native library: task build provisions it through\nscripts/setup-liter-llm.sh; a bare go install does not do that setup.\nVersion 5.4.0 includes the governance and plugin validation fixes described below.\nFor a reviewed source build, use the exact revision recorded in the CI workflow.
# Initialize a new project\nai-rulez init\n\n# Add rules and context\nai-rulez add rule my-rule --priority high\nai-rulez add context my-context\n\n# Generate outputs for all configured presets\nai-rulez generate\n\n# Regenerate whenever .ai-rulez/ changes\nai-rulez generate --watch\n\n# Validate configuration\nai-rulez validate\n\n# Read-only diagnostics: drift, removed presets, missing tools\nai-rulez doctor\nai-rulez generate --plugin # bundle: plugin bundles from the [plugin] block\nai-rulez export okf # bundle: an OKF bundle of the knowledge\nai-rulez validate --strict # validate: warnings fail\nai-rulez okf validate <bundle-dir> # validate: an existing OKF bundle directory\nai-rulez lock # govern: pin includes, skills and content\nai-rulez sign --lock # govern: Sigstore attestation of the lock\nai-rulez sbom -o ai-bom.cdx.json # govern: CycloneDX SBOM\nai-rulez publish --dry-run # publish: preview release artifacts\nSupported and planned standards, with pinned versions and test status, are in\nhttps://goldziher.github.io/ai-rulez/standards/.
\nsource = \"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..ai-rulez/\n config.toml # Governance configuration\n config.plugins.toml # Plugin and marketplace layer, selected by default_layers\n rules/ # Governance rules (.md files with frontmatter)\n context/ # Contextual information (.md files)\n skills/ # Specialized capabilities (name/SKILL.md plus resources)\n agents/ # Agent definitions (.md files)\n commands/ # Custom commands (.md files)\n checks/ # Code-review guidelines (.md files)\n domains/ # Domain-scoped content\n backend/\n rules/\n context/\n skills/\nKeep governance in config.toml. Put marketplace registries ([[marketplaces]]) and authoring\n[plugin]/[marketplace] blocks in config.plugins.toml, and select that layer with\ndefault_layers = [\"plugins\"] before the first table in config.toml. Plugin authoring\ncan use a separate plugin/.ai-rulez/ tree so public product skills exclude contributor rules.
version = \"5.0\"\nname = \"my-project\"\ndescription = \"Project description\"\n\npresets = [\"claude\", \"cursor\", \"gemini\"]\ndefault_layers = [\"plugins\"]\ndefault = \"backend\"\nbuiltins = [\"go\", \"security\", \"testing\"]\n\n[profiles]\nbackend = [\"backend\", \"shared\"]\nfrontend = [\"frontend\", \"shared\"]\n\n[[includes]]\nname = \"shared-rules\"\nsource = \"https://github.com/org/shared-rules\"\n\n[[installed_skills]]\nname = \"kreuzberg\"\nsource = \"https://github.com/kreuzberg-dev/kreuzberg\"\n\n[[mcp_servers]]\nname = \"ai-rulez\"\ncommand = \"pnpm\"\nargs = [\"dlx\", \"ai-rulez@5.4.1\", \"mcp\"]\n\n[[scopes]]\npath = \"packages/web\"\nprofile = \"frontend\"\npresets = [\"codex\", \"claude\"]\nAuthored .ai-rulez/ content uses OKF frontmatter: type, title and an\nx-ai-rulez identity. Tool-specific fields belong in x-ai-rulez.metadata.\nUse Principle for rules, Concept for context, Playbook for skills and\nReference for agents. For example, .ai-rulez/rules/project-conventions.md:
---\ntype: Principle\ntitle: Project conventions\ndescription: Shared project conventions\nx-ai-rulez:\n kind: rule\n id: project-conventions\n metadata:\n priority: high\n targets:\n - CLAUDE.md\n - .cursor/rules/*\n---\npriority accepts critical, high, medium, low and minimal. Older flat\nfrontmatter remains readable for migration; run ai-rulez migrate okf to convert\nit 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\nslug matching the skill directory and x-ai-rulez.id. This supplies the required\nnative Agent Skills name across runtime projections.
Public skills/<name>/SKILL.md exports use native Agent Skills frontmatter,\nincluding name and description, without the OKF wrapper. This public skill\nis such an export; its frontmatter is not the authoring format for .ai-rulez/.
Agent files under .ai-rulez/agents/ put native subagent fields inside\nx-ai-rulez.metadata. Supported fields render into the configured harness;\nfields a harness does not support are omitted. For example, create\n.ai-rulez/agents/<agent-id>.md with security-reviewer as the ID:
---\ntype: Reference\ntitle: Security reviewer\ndescription: Reviews code for security regressions\nx-ai-rulez:\n kind: agent\n id: security-reviewer\n metadata:\n name: security-reviewer\n model: opus\n effort: high\n permissionMode: default\n tools:\n - Read\n - Grep\n - Glob\n---\nClaude Code receives these fields in .claude/agents/<agent-id>.md using\nits native flat frontmatter. Keep the authored OKF file and generated native\nfile distinct.
effort controls reasoning depth. Set a project-wide default and per-preset\noverrides in config.toml:
[defaults]\neffort = \"medium\"\n\n[defaults.effort_by_preset]\ncodex = \"high\" # Codex applies it globally and per agent\nclaude = \"xhigh\" # Claude applies it as `effort` per agent\namp = \"max\" # Amp writes amp.anthropic.effort to .amp/settings.json\nResolution order (per preset, per agent): per-agent effort →\ndefaults.effort_by_preset[<preset>] → defaults.effort → omit.
Per-preset support:
\n.claude/agents/*.md (full vocabulary including max; inherit is not a Claude value and is dropped).codex/config.toml and per-agent in .codex/agents/*.toml (max → high; inherit dropped).amp/settings.json (xhigh → high).devin/agents/*.md frontmatter (max → high)variant in .opencode/agents/*.md (joins the agent's model as model#variant)Domains group content for different teams or concerns. Profiles select which domains are active.
\nai-rulez domain add backend\nai-rulez add rule api-standards --domain backend\nai-rulez profile add backend-team backend shared\nai-rulez generate --profile backend-team\nShare rules across projects using git repositories or local paths:
\nai-rulez include add shared-rules https://github.com/org/shared-rules\nai-rulez include add local-rules ./path/to/local --merge-strategy include-override\nInstall named skills from external repositories:
\nai-rulez skill install kreuzberg --source https://github.com/kreuzberg-dev/kreuzberg\nai-rulez skill install ai-rulez --source https://github.com/Goldziher/ai-rulez\nai-rulez skill list\nai-rulez skill remove kreuzberg\nSkills are fetched dynamically at generation time and included in outputs.\nSkill references/, scripts/, and assets/ directories are preserved as separate generated resource files when the target preset supports skill directories.
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]] 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..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.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/.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.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]] 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 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\nConfigure in your AI tool's MCP settings to enable CRUD operations from within the assistant.
\nMCP server env values can use ${VAR} placeholders. ai-rulez generate resolves them from --env,\nprocess env, and dotenv files, then refuses to write secret-bearing generated MCP configs unless the\ntarget paths are gitignored (gitignore = true or generate --gitignore adds them to the managed block).
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).
Use migrate okf --check, validate --strict --no-local, lock --check, and\ngenerate --check --no-local --strict-config to check the authored configuration.\nFor published plugins, use verify --plugin before regenerating to detect existing\ndrift; after intentional regeneration, check it again and verify public skill exports.\nPackage from a committed tree with publish --tag <release-tag>, then run\npublish verify <dist-directory> on the actual archive. A successful local package\ndoes not publish a release or registry package.
Version 5.4.0 includes fixes for registered marketplace members, both-layout MCP ownership,\nOpenCode skill IDs and shared include-cache locking. The repository validates with a reviewed\nsource build pinned in CI; use that exact source revision when reproducing its checks.
\nThe exact reviewed source revision is recorded in\n.github/workflows/ai-rulez-validation.yml. It includes the ID-only OKF skill\nprojection fix, strict Hermes package metadata, and cache isolation by configured\nsource path and revision. Use that workflow as the source of truth for the pin.