Skip to content

Configuration Schema

The ai-rulez configuration is validated against a formal JSON Schema to provide editor support like autocompletion and real-time validation.

Config schema

The schema is embedded in the CLI. ai-rulez validate validates the raw config file against it (converting TOML to JSON first) and then runs the structural checks, so edit your .ai-rulez/config.toml and run ai-rulez validate.

# .ai-rulez/config.toml
version = "5.0"
name = "My Project"

Most modern editors support TOML schema references. Add this to enable autocompletion (for VS Code with TOML extension):

Add a .vscode/settings.json to reference the schema:

{
  "evenBetterToml.schema.associations": {
    ".ai-rulez/config.toml": "https://raw.githubusercontent.com/Goldziher/ai-rulez/main/schema/ai-rules.schema.json"
  }
}

Validation Rules

Required Fields

  • version: Must be "5.0"
  • name: Project name (required, non-empty string)

Optional Fields

  • description: Project description
  • presets: List of tool presets (e.g., claude, cursor, gemini)
  • profiles: Named profiles specifying which domains to include
  • default: Default profile name
  • schema: URL of the JSON Schema, for editor support
  • rules: Rules output mode (mode, mode_by_preset, baz_scoped, baz_default, baz.include, baz_rest, baz_unscoped, baz_dedupe, baz_dedupe_max, baz_budget; see Rules)
  • scopes: Additional scoped output roots. Their root files (AGENTS.md/CLAUDE.md) stay in the subfolder; rule files go to the root rules folders
  • gitignore: Whether to maintain the managed .gitignore block with generated output patterns (default: false)
  • includes: External content sources to merge
  • installed_skills: Skills to install from external repositories
  • header: Header style, timestamp, hashes, text, mcp_line and nested for generated files
  • defaults: Global effort and per-preset effort_by_preset / model_by_preset
  • builtins: Built-in domains (true, false, or a list with ! exclusions)
  • compact: Omit per-rule priority annotations from inline sections
  • source: Where the content is read from: ai-rulez (default, the .ai-rulez tree) or agents (AGENTS.md and .agents/; see .agents as a source)
  • agents_md_split: With the agents source, read AGENTS.md as one context item per ## heading (default false); see Splitting AGENTS.md
  • agents_md: Render AGENTS.md and .agents/skills once for the presets that read them (default true)
  • mcp_servers: Array of MCP server configurations
  • mcp: Project-level MCP generation options (self_server, self_server_version, self_server_launcher, self_server_command, skills_instructions, skills_instructions_text, serve_skills, discover_skills, index_cache, read_only, daemon, daemon_idle_timeout, authoring, no_watch, allow, deny, tools, exclude)
  • plugins: Array of plugin installs from a marketplace (consumer side)
  • marketplaces: Array of marketplace sources
  • plugin: Producer-side authoring block for a distributable plugin bundle
  • marketplace: Producer-side marketplace index authoring block
  • placement: Whether skills and commands are core (written to the harness trees) or plugin-only; see Plugins
  • claude: Claude Code options: [claude.settings] (manage, managed entries of .claude/settings.json) and [claude.skills] (hide_from_menu)
  • codex: Codex options, such as project_doc_max_bytes for the AGENTS.md size warning
  • codex_skills_dir: Directory the codex preset writes skills to (default .agents/skills)
  • gitignore_exclude: Patterns kept out of the managed .gitignore block, for outputs you commit; see Configuration
  • bundle_exclude: Extra patterns left out when skill and command resources are copied or listed
  • hooks: Top-level [[hooks]] rendered into each harness's native hook format; see Hooks and permissions
  • permissions: allow, ask and deny rules translated for each harness with a permission surface; see Permissions
  • guard: [guard] generated = true adds a PreToolUse hook that blocks agent edits to generated files (version, command tune how it launches); see Settings
  • session_start: [session_start] (on by default for Claude Code) adds a SessionStart hook that runs ai-rulez session-start in remote sessions (generate, when, mode, timeout, version, command, prompt, prompt_text); see Run generate when a remote session starts
  • roles: [[roles]] map a job to a slice of the shared content; see Roles
  • role_manifest: enabled writes roles.json; skill_mode_fallback (drop or serve) decides what an off skill does on a harness that cannot hide it
  • domains: Per-domain settings keyed by domain name ([domains.<name>] delivery)
  • delivery: [delivery.stub] description, body, body_file: customises the generated dynamic-skills stub; see Configuration
  • skills: Defaults for every skill ([skills] delivery = "static" | "served" | "both"); see MCP server
  • skill_sources: [[skill_sources]] remote or local skill sources that are served over MCP and pinned in the lock
  • catalog: [catalog] defaults for ai-rulez catalog (title, include_excerpt, exclude_owners, indexable, max_items_per_page, render_markdown); see Catalog
  • governance: [governance] approval policy (require_approval, exempt, min_approvers, approvers, approvers_from, teams, min_assurance, forbid_self_approval, max_age, enforce); see Approvals
  • lock: [lock] content pinning (enforce, include_outputs, scope); see Lock file
  • lint: [lint] strict-validation settings (severities, ignores, budgets, tolerate, security, evals, traps, metadata, external scanners); see Strict validation
  • verifiers: [[verifiers]] deterministic repository checks run by ai-rulez verifiers run; see Verifiers
  • okf: [okf] bundle options (dir, include, index_style, spec); see OKF
  • usage: [usage] skills_index writes skills-index.json for usage reports; see Usage telemetry
  • llm: [llm] model access (backend, model, base_url, api_key_env, budgets, allow_network, ...); network and credential keys are honoured only from user scope; see LLM access
  • telemetry: [telemetry] item-load telemetry and OTLP export; egress keys, service_name and resource are honoured only from user scope; see Telemetry

Which of these a repository may set, and which only the user config file or the environment may enable, is in the trust model.

Field Constraints

  • version: Must be "5.0"
  • name: Non-empty string
  • priority (in markdown frontmatter): One of critical, high, medium, low, minimal
  • targets (in markdown frontmatter): Selects output files, as preset names (claude), root files (CLAUDE.md), paths or base names, directory prefixes (.cursor/rules/), globs (.cursor/rules/*), or *. See Targets
  • mcp_servers[].name: Unique identifier for each server
  • mcp_servers[].description: Human-readable description
  • mcp_servers[].command: Command to execute for local stdio servers (npx, uvx, ai-rulez, etc.)
  • mcp_servers[].args: Command arguments for local servers
  • mcp_servers[].profiles: Restrict the server to the named profiles
  • mcp_servers[].domain: Restrict the server to a domain; it is included only when the active profile or role selects that domain
  • mcp_servers[].transport: stdio, http, or sse (default: stdio)
  • mcp_servers[].url: Remote MCP URL for http or sse transports
  • mcp_servers[].headers: HTTP headers for http/sse servers; values may contain ${VAR} placeholders resolved by generate
  • mcp_servers[].enabled: Set to false to omit the server from generated MCP outputs
  • mcp_servers[].env: Environment variables; values may contain ${VAR} placeholders resolved by generate
  • installed_skills[].include / exclude: Globs over skill directory names that select several skills from one repository with one entry; exclude wins
  • installed_skills[].name_prefix: Prefix prepended to every resolved skill name and output directory
  • installed_skills[].trust: Scan level of the imported skills, error (default) or warn
  • installed_skills[].domain: Place the skill in a domain so a profile or a role selects it by domain

MCP placeholder names must match [A-Za-z_][A-Za-z0-9_]*. Generation resolves them from --env KEY=VALUE, process env, then dotenv files. Secret-bearing MCP outputs must be gitignored before generated configs are written.

File Structure

Configuration is TOML; content is markdown files with optional YAML frontmatter:

# config.toml
version = "5.0"
name = "My Project"

[[mcp_servers]]
name = "ai-rulez"
command = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]

Content files use markdown with optional YAML frontmatter:

---
priority: high
targets: ["CLAUDE.md"]
custom_field: value
---

# Title

Content here

Available Schemas

The schema files are available in the repository:

File Format Version Notes
schema/ai-rules.schema.json JSON Schema v5 Config schema; accepts version "5.0" only
schema/ai-rules-local.schema.json JSON Schema V4 Machine-local config.local.toml overlay; used by validate, local set and the MCP validate_config tool
schema/provider.schema.json JSON Schema V4 Declarative provider spec referenced by [[presets]] provider = "..."; see Provider-backed Presets
schema/roles-manifest.schema.json JSON Schema v1 roles.json and roles list --format json; see Roles
schema/catalog.schema.json JSON Schema v2 ai-rulez catalog --format json --schema-version 2 and the catalog.json of catalog --html; see Catalog
schema/catalog-diff.schema.json JSON Schema v1 ai-rulez catalog diff --format json; see Catalog
schema/catalog.v1.schema.json JSON Schema v1 ai-rulez catalog --format json (the default until the next minor release)
schema/plan.schema.json JSON Schema v1 ai-rulez generate --emit-plan FILE and generator.PlanOutputs: every file a run would write, merge or remove, with digests and no secrets; see Embedding the plan
schema/validate-report.schema.json JSON Schema v1 ai-rulez validate --format json and scan --format json
schema/cost-report.schema.json JSON Schema v1 ai-rulez cost --format json
schema/telemetry-doctor.schema.json JSON Schema v1 ai-rulez telemetry doctor --format json
schema/eval-report.schema.json JSON Schema v1 ai-rulez eval run --format json
schema/judge-report.schema.json JSON Schema v2 ai-rulez judge --format json: per unit the verified findings, scores, attached conventions and coverage, or what --estimate would send; see Judge
schema/okf-validate.schema.json JSON Schema v1 ai-rulez okf validate --format json
schema/convert-report.schema.json JSON Schema v1 ai-rulez convert --format json
schema/lock-diff.schema.json JSON Schema v1 ai-rulez lock --diff --format json; see Lock file
schema/cache-status.schema.json JSON Schema v1 ai-rulez cache status --format json: where the index cache is, its size and entry counts, and warnings
schema/cache-clear.schema.json JSON Schema v1 ai-rulez cache clear --format json: the cache directories removed
schema/lock-outdated.schema.json JSON Schema v1 ai-rulez lock --outdated --format json: sources with a version constraint and the newer tags they could move to
schema/review-report.schema.json JSON Schema v1 ai-rulez review --format json: the rubric with its weights and formula, one entry per item, and the egress manifest of --estimate
schema/lock-subject.schema.json JSON Schema v1 ai-rulez lock --subject --format json: the lock-subject digest a signature commits to
schema/verify-attestation.schema.json JSON Schema v1 ai-rulez verify --attestation --format json: the outcome of verifying the signed lock
schema/approve-list.schema.json JSON Schema v1 ai-rulez approve --list --format json: the [governance] policy and the approval status of pinned content; see Approvals
schema/verify-approvals.schema.json JSON Schema v1 ai-rulez verify --approvals --format json: the re-check of signed and review-linked approvals; see Approvals
schema/update.schema.json JSON Schema v1 ai-rulez update --format json: the pins that move, or would with --dry-run
schema/search.v1.schema.json JSON Schema v1 ai-rulez search <query> --format json: served skills ranked against a query (lexical or hybrid)
schema/search-eval.v1.schema.json JSON Schema v1 ai-rulez search --eval <cases.yaml> --format json, also the file --output writes
schema/convert-report.schema.json JSON Schema v1 ai-rulez convert --format json: every input construct as mapped, approximated or dropped
schema/publish-manifest.schema.json JSON Schema v1 <name>-<version>.manifest.json written by ai-rulez publish: the bundle's files, source, lock and digests
schema/publish-plan.schema.json JSON Schema v1 publish-plan.json (and ai-rulez publish --format json): artifacts with digests and the argv --execute would run
schema/eval-case.schema.json JSON Schema v1 *.eval.yaml / .yml / .json skill eval cases under skills/<name>/
schema/eval-activation.v1.schema.json JSON Schema v1 ai-rulez eval run --mode activation --format json: activation rates, intervals and the confusion matrix; see Activation mode
schema/improve-report.schema.json JSON Schema v1 report.json of an experimental ai-rulez improve run (improve-report/1)
schema/verifiers-report.schema.json JSON Schema v1 ai-rulez verifiers run --format json and the MCP run_verifiers result; see Verifiers
schema/verifiers-spec.schema.json JSON Schema v1 .ai-rulez/verifiers/*.toml declaration files; see Verifiers
schema/doctor-report.schema.json JSON Schema v1 ai-rulez doctor --format json: the findings by check and severity
schema/tokens-report.schema.json JSON Schema v1 ai-rulez tokens --format json: the cost of the generated files per runtime and domain
schema/scanners-list.schema.json JSON Schema v1 ai-rulez scanners list --format json: the configured external scanners
schema/scanners-doctor.schema.json JSON Schema v1 ai-rulez scanners doctor --format json: as scanners list plus the probed version
schema/roles-show.schema.json JSON Schema v1 ai-rulez roles show <name> --format json: the declared role, the effective role and its chain
schema/roles-resolve.schema.json JSON Schema v1 ai-rulez roles resolve <name> --format json: what a person holding the role gets
schema/sbom-report.schema.json JSON Schema v1 ai-rulez sbom --format json when the run reports instead of printing the document (a failed gate, --check, -o)
schema/verify-plugin.schema.json JSON Schema v1 ai-rulez verify --plugin --format json: whether the plugin bundles match their provenance
schema/publish-verify.schema.json JSON Schema v1 ai-rulez publish verify --format json: one result per dist directory
schema/publish-emit.schema.json JSON Schema v1 ai-rulez publish emit <emitter> --format json: the files the emitter wrote
schema/verifiers-list.schema.json JSON Schema v1 ai-rulez verifiers list --format json: the declared verifiers
schema/verifiers-test.schema.json JSON Schema v1 ai-rulez verifiers test --format json: the outcome of the self-test examples
schema/verifiers-explain.schema.json JSON Schema v1 ai-rulez verifiers explain <name> --format json: what one verifier checks
schema/export-okf.schema.json JSON Schema v1 ai-rulez export okf --format json: the files written, or the drift of --check
schema/sign-report.schema.json JSON Schema v1 ai-rulez sign --format json: what the run signed
schema/change-result.schema.json JSON Schema v1 add, remove, edit, domain, profile, include, skill install\|remove with --format json: what changed and where
schema/error-document.schema.json JSON Schema v1 What every command with a --format flag prints on stdout when it fails before it has a report; see the CLI reference
schema/policy.schema.json JSON Schema v1 An organization policy file (--policy, AI_RULEZ_POLICY, managed path); see Organization policy
schema/policy-effective.schema.json JSON Schema v1 ai-rulez validate --show-policy --format json: the policy layers, the effective policy with the origin of every value, and what the repository tried to loosen

Access them at (versioned to the release; main is the tip):

  • Main schema: https://raw.githubusercontent.com/Goldziher/ai-rulez/main/schema/ai-rules.schema.json
  • Local overlay schema: https://raw.githubusercontent.com/Goldziher/ai-rulez/main/schema/ai-rules-local.schema.json
  • Provider schema: https://raw.githubusercontent.com/Goldziher/ai-rulez/main/schema/provider.schema.json
  • Roles manifest schema: https://raw.githubusercontent.com/Goldziher/ai-rulez/main/schema/roles-manifest.schema.json

The local overlay schema accepts the same keys as the main schema without the requirement that version and name be present, and adds the overlay-only markers (remove = true on named-list entries, "!name" in presets). See Local Configuration.

Validation Commands

Use the ai-rulez validate command to check your configuration against the schema at any time:

# Validate current directory
ai-rulez validate

# Validate a specific config.toml
ai-rulez -C .ai-rulez/config.toml validate

# Debug output
ai-rulez validate --debug