# ai-rulez

Adopt this skill: https://proskills.md/skills/other/goldziher-ai-rulez-skills-ai-rulez

Page: https://proskills.md/skills/other/goldziher-ai-rulez-skills-ai-rulez
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/ai-rulez/SKILL.md
size: 7423
upstream: https://github.com/goldziher/ai-rulez/blob/main/skills/ai-rulez/SKILL.md

````text
---
name: ai-rulez
description: >-
  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.
license: MIT
metadata:
  author: Goldziher
  version: "4.23.1"
  repository: https://github.com/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
# npm (no install)
npx ai-rulez@latest

# Python (no install)
uvx ai-rulez

# Go: build from source (the module path has no /v4 suffix, so
# `go install …@latest` resolves to an old 1.x build)
git clone https://github.com/Goldziher/ai-rulez
cd ai-rulez && go build -o ai-rulez ./cmd
```

## 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, minimal
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`; `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`)
- **Windsurf**: per-agent in `.windsurf/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, 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`, `xum`. The `mcp` preset is a shared utility (the generic `.mcp.json`) invoked automatically when MCP servers are configured.

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.

## Plugins and Marketplaces

V4 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, and Hermes via `ai-rulez generate --plugin`. Consumer `[[plugins]]`/`[[marketplaces]]` arrays declare plugins to install from a marketplace (rendered into `.claude/plugins.json` and `.codex/plugins.json`).
````

## File: README.md
upstream: https://github.com/goldziher/ai-rulez/blob/main/README.md

````text
<p align="center">
  <img src="https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/ai-rulez-banner.png" alt="AI-Rulez" width="820" />
</p>

<p align="center">
  <strong>One source for the rules, skills and settings of every AI coding assistant</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/ai-rulez"><img src="https://img.shields.io/npm/v/ai-rulez?color=blue" alt="npm version"></a>
  <a href="https://pypi.org/project/ai-rulez/"><img src="https://img.shields.io/pypi/v/ai-rulez?color=blue" alt="PyPI version"></a>
  <a href="https://github.com/Goldziher/homebrew-tap"><img src="https://img.shields.io/github/v/release/Goldziher/ai-rulez?label=homebrew&color=blue" alt="Homebrew version"></a>
  <a href="https://pkg.go.dev/github.com/Goldziher/ai-rulez/v5"><img src="https://img.shields.io/github/v/release/Goldziher/ai-rulez?label=go&color=blue" alt="Go version"></a>
  <a href="https://github.com/Goldziher/ai-rulez/actions/workflows/ci.yaml"><img src="https://img.shields.io/github/actions/workflow/status/Goldziher/ai-rulez/ci.yaml?branch=main&label=CI" alt="CI"></a>
  <a href="https://github.com/Goldziher/ai-rulez/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Goldziher/ai-rulez?color=blue" alt="License"></a>
  <a href="https://goldziher.github.io/ai-rulez/"><img src="https://img.shields.io/badge/docs-ai--rulez-blue" alt="Documentation"></a>
</p>

<p align="center">
  <a href="https://goldziher.github.io/ai-rulez/"><strong>Documentation</strong></a> &middot;
  <a href="https://goldziher.github.io/ai-rulez/quick-start/"><strong>Quick Start</strong></a> &middot;
  <a href="https://goldziher.github.io/ai-rulez/examples/"><strong>Examples</strong></a>
</p>

---

## What it is

ai-rulez keeps the instructions for your AI coding assistants in one directory, `.ai-rulez/`: rules, context, skills,
agents, commands, hooks, permissions and MCP servers. From that source it generates the native files of each assistant
your team uses (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/instructions/`, skill folders, MCP and settings
files) for 52 tools, and keeps them in sync.

- **One source, every tool.** Edit `.ai-rulez/`, run `generate`, and Claude Code, Cursor, Codex, Copilot, Gemini CLI
  and the rest get the same guidance in their own format.
- **Checked in CI.** `generate --check` catches drift; `validate` lints content, links and security issues with stable
  `AR` rule codes, and also works on plain `AGENTS.md` and `SKILL.md` files with no configuration.
- **Governed like dependencies.** A lock file pins remote includes, installed skills and authored content; approvals,
  Sigstore signatures, SBOMs and an organization policy cover the rest.
- **Packaged for distribution.** Build plugin bundles and marketplaces, Agent Plugins and ARD manifests, and publish
  them.

## 30-second example

```bash
npx ai-rulez@latest init acme
```

Set the tools you use in `.ai-rulez/config.toml`:

```toml
version = "5.0"
name = "acme"
presets = ["claude", "cursor", "codex", "copilot", "gemini"]
```

Add a rule and generate:

```bash
npx ai-rulez@latest add rule testing --content '# Testing

- Every bug fix ships with a regression test.'
npx ai-rulez@latest generate
```

```text
AGENTS.md                # rules and context, read by Codex, Cursor, Copilot and Gemini CLI
CLAUDE.md                # imports @AGENTS.md for Claude Code
.agents/skills/          # skills
.claude/skills/
.gemini/settings.json    # points Gemini CLI at AGENTS.md
.mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml
```

Commit `.ai-rulez/` with the generated files, and add `ai-rulez generate --check` to CI. The
[Quick start](https://goldziher.github.io/ai-rulez/quick-start/) walks through it in five minutes.

<p align="center">
  <img src="https://raw.githubusercontent.com/Goldziher/ai-rulez/main/docs/assets/quickstart.gif" alt="ai-rulez init and generate: one .ai-rulez source becomes the native files of several AI tools" width="820" />
</p>

## Install

```bash
brew install goldziher/tap/ai-rulez                                # Homebrew (macOS, Linux)
npm install -g ai-rulez                                            # npm (Node.js 22+)
pipx install ai-rulez                                              # PyPI (Python 3.11+); or uv tool install ai-rulez
go install github.com/Goldziher/ai-rulez/v5/cmd/ai-rulez@latest    # Go (note the /v5)
```

Or run it without installing: `npx ai-rulez@latest <command>` or `uvx ai-rulez <command>`. See
[Installation](https://goldziher.github.io/ai-rulez/installation/) for platforms, shell completion and git hooks.

## Supported tools

52 built-in presets, one per assistant, CLI agent or IDE integration. Combine any of them in `presets = [...]`;
[Supported harnesses](https://goldziher.github.io/ai-rulez/harnesses/) shows which rules, skills, agents, commands, MCP servers, hooks and permissions
each one receives. A tool that is not listed can be added as a [custom preset](https://goldziher.github.io/ai-rulez/profiles/).

<details>
<summary><strong>All 52 built-in presets</strong></summary>

| Preset | Tool |
| ------ | ---- |
| `aiassistant` | [JetBrains AI Assistant](https://www.jetbrains.com/help/ai-assistant/) |
| `amp` | [Sourcegraph Amp](https://ampcode.com) |
| `antigravity` | [Google Antigravity](https://antigravity.google/docs) |
| `augment` | [Augment Code](https://docs.augmentcode.com) |
| `baz` | [Baz](https://baz.ai/docs/agents/skills-and-instructions) |
| `bob` | [IBM Bob](https://bob.ibm.com/docs) |
| `claude` | [Claude Code](https://code.claude.com/docs) |
| `cline` | [Cline](https://docs.cline.bot) |
| `codebuddy` | [CodeBuddy Code](https://www.codebuddy.ai/docs/cli) |
| `codebuff` | [Codebuff](https://www.codebuff.com/docs) |
| `codewhale` | [Codewhale](https://github.com/codewhale-hq/Codewhale) |
| `codex` | [OpenAI Codex](https://developers.openai.com/codex) |
| `commandcode` | [Command Code](https://commandcode.ai/docs) |
| `copilot` | [GitHub Copilot](https://docs.github.com/en/copilot) |
| `copilot-cli` | [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli) |
| `cortex` | [Snowflake Cortex Code](https://docs.snowflake.com/en/user-guide/cortex-code/extensibility) |
| `crush` | [Crush](https://github.com/charmbracelet/crush) |
| `cursor` | [Cursor](https://cursor.com/docs) |
| `deepagents` | [Deep Agents Code](https://docs.langchain.com/oss/deepagents/code) |
| `devin` | [Devin CLI](https://docs.devin.ai/cli) |
| `dsh` | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) |
| `factory` | [Factory Droid](https://docs.factory.ai) |
| `gemini` | [Gemini CLI](https://geminicli.com/docs/) |
| `gitlab-duo` | [GitLab Duo CLI](https://docs.gitlab.com/user/gitlab_duo_cli/customize/) |
| `goose` | [goose](https://goose-docs.ai) |
| `grok` | [Grok Build CLI](https://docs.x.ai/build/overview) |
| `hermes` | [Hermes Agent](https://hermes-agent.nousresearch.com/docs) |
| `junie` | [JetBrains Junie](https://junie.jetbrains.com) |
| `kilo` | [Kilo Code](https://kilo.ai/docs) |
| `kimi` | [Kimi Code](https://moonshotai.github.io/kimi-code/) |
| `kiro` | [Kiro](https://kiro.dev/docs) |
| `letta` | [Letta Code](https://docs.letta.com) |
| `mimocode` | [MiMo Code](https://mimo.xiaomi.com/mimocode) |
| `muse` | [Meta Muse Code](https://dev.meta.ai/docs/muse-code) |
| `omp` | [oh-my-pi](https://github.com/can1357/oh-my-pi) |
| `openclaw` | [OpenClaw](https://docs.openclaw.ai) |
| `opencode` | [OpenCode](https://opencode.ai/docs) |
| `pi` | [pi](https://pi.dev/docs/latest) |
| `poolside` | [Poolside Pool](https://docs.poolside.ai) |
| `qoder` | [Qoder](https://docs.qoder.com/cli/quickstart) |
| `qwen` | [Qwen Code](https://qwenlm.github.io/qwen-code-docs/en/) |
| `reasonix` | [Reasonix](https://github.com/esengine/DeepSeek-Reasonix) |
| `replit` | [Replit Agent](https://docs.replit.com/features/agent/overview) |
| `rovodev` | [Atlassian Rovo Dev](https://www.atl
````
