⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

v5.7.0

ai-rulez

goldziher@goldziher⭐ 169 stars· last commit 6d ago· 3 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 169 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README


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

npx ai-rulez@latest init acme

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

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

Add a rule and generate:

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

- Every bug fix ships with a regression test.'
npx ai-rulez@latest generate
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 walks through it in five minutes.

Install

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

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/ai-rulez/SKILL.md7.2 KBupstream ↗
    ---
    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`).
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/goldziher-ai-rulez-skills-ai-rulez.md

// REPO STATS

169 stars
3 open issues
Last commit: 6d ago