# AI Rulez

> Manage AI assistant governance rules across Claude, Cursor, Windsurf, Copilot, Gemini, and other tools using ai-rulez. Use when configuring rules, context, skills, domains, profiles, includes, plugins, or generating tool-specific outputs.

- Skill: `goldziher/ai-rulez` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add goldziher/ai-rulez`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goldziher/ai-rulez/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: goldziher (https://skillmd.com/u/goldziher)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goldziher/ai-rulez

---


# AI-Rulez Governance

AI-Rulez centralizes AI assistant governance in a config directory (default `.ai-rulez/`) and generates tool-specific outputs for Claude, Cursor, Windsurf, Copilot, Gemini, Codex, and other presets.

Use this skill when:

- Setting up or modifying `.ai-rulez/` configuration
- Writing rules, context, skills, or agents for AI assistants
- 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
# Go (primary CLI)
go install github.com/Goldziher/ai-rulez@latest

# npm
npx ai-rulez@latest

# Python
uvx ai-rulez
```

## 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

# Validate configuration
ai-rulez validate
```

## Configuration Structure

```text
.ai-rulez/
  config.toml          # Main configuration
  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)
  domains/             # Domain-scoped content
    backend/
      rules/
      context/
      skills/
```

## config.toml

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

presets = ["claude", "cursor", "gemini"]
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 = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]

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

## Content Frontmatter

Rules, context, skills, and agents support YAML frontmatter:

```yaml
---
priority: high # critical, high, medium, low
targets: # Limit to specific presets
  - CLAUDE.md
  - .cursor/rules/*
description: Brief description
---
```

### Agent-only fields

Agent files under `.ai-rulez/agents/` accept additional frontmatter that maps to
Claude Code's subagent spec. Each is optional and only emitted into
`.claude/agents/*.md` (other presets skip fields they do not support):

```yaml
---
name: security-reviewer
description: Reviews code for security regressions
model: opus # haiku | sonnet | opus | inherit
effort: high # low | medium | high | xhigh | max | inherit
permission_mode: default
tools: # Restrict tool access
  - Read
  - Grep
  - Glob
---
```

`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` and `inherit`)
- **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`)
- **Windsurf**: per-agent in `.windsurf/agents/*.md` frontmatter (`max` → `high`)
- **Opencode**: per-agent `reasoningEffort` in `.opencode/agents/*.md`
- Cursor, Copilot, Gemini, Junie, Antigravity, Cline, Continue.dev: 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

Available presets: `claude`, `cursor`, `gemini`, `copilot`, `continue-dev`, `windsurf`, `cline`, `codex`, `amp`, `junie`, `opencode`, `hermes`, `antigravity`.

## 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.

## Plugins and Marketplaces

V4 introduces support for plugins and marketplace integrations to extend ai-rulez functionality with custom generators, presets, and validators.