Skip to content

AI-Rulez Documentation

AI-Rulez

AI-Rulez is a CLI tool for managing AI assistant configurations across multiple tools.

Write your AI instructions once in a single configuration and generate tool-specific outputs for Claude, Cursor, Windsurf, Copilot, Gemini, and others.

Core Concepts

Directory-Based Configuration

Your configuration lives in .ai-rulez/ with organized subdirectories:

  • rules/: Mandatory constraints and standards
  • context/: Reference documentation and architecture
  • skills/: Specialized AI prompts for specific roles
  • domains/: Team or subsystem-specific content
  • config.toml: Main configuration (presets, profiles)

Presets

Presets define how content is formatted and where it's output for different tools. Built-in presets include:

  • claude → generates CLAUDE.md, .claude/rules/, .claude/skills/, .claude/agents/
  • cursor → generates .cursor/rules/
  • gemini → generates GEMINI.md
  • copilot → generates .github/copilot-instructions.md and .github/instructions/
  • windsurf → generates .windsurf/rules/
  • junie → generates .junie/guidelines.md and .junie/rules/
  • hermes → generates .hermes.md
  • xum → generates AGENTS.md and .xum/
  • pi → generates AGENTS.md, .agents/skills/, .pi/agents/, and .pi/mcp.json
  • And many others...
  • Custom tools: use a template preset or a provider-backed preset for full parity with built-ins.

Profiles

Profiles let different teams generate customized outputs. Each profile specifies which domains to include:

[profiles]
full = ["backend", "frontend", "qa"]
backend = ["backend", "qa"]
frontend = ["frontend", "qa"]

Quick Navigation

Getting Started

Using AI-Rulez

Advanced Topics

Typical Workflow

  1. Initialize your project:
ai-rulez init "my-project"
  1. Add content to .ai-rulez/:
  2. Write rules in rules/
  3. Add context in context/

  4. Create skills in skills/

  5. Generate outputs:

ai-rulez generate
  1. Commit the sources:
git add .ai-rulez/
git commit -m "docs: update AI assistant guidelines"

Generated files are gitignored by default (gitignore = true). Add them to the commit too only if you set gitignore = false.

Key Features

  • Single source of truth for all AI tool configurations
  • Domain scoping to organize rules by team or subsystem
  • Profile-based customization for different contexts
  • Modular structure to reduce merge conflicts
  • Built-in presets for 14 AI tools
  • Custom presets for any tool and format
  • Installed skills from external repositories
  • Remote includes for sharing rules across projects
  • MCP integration for programmatic access
  • Support for monorepos and multi-team projects
  • Optional shared AGENTS.md and .agents/skills for every tool that reads them (agents_md)
  • Machine-local, gitignored content and config overlay (config.local.*, .ai-rulez/local/)

Project Structure

After initialization, your project looks like:

project-root/
├── .ai-rulez/
│   ├── config.toml           # Main configuration
│   ├── rules/                # Base rules (all profiles)
│   ├── context/              # Reference docs (all profiles)
│   ├── skills/               # AI skills (all profiles)
│   ├── agents/               # Agent prompt files (all profiles)
│   └── domains/              # Team-specific content
│       ├── backend/
│       └── frontend/
├── CLAUDE.md                 # Generated for Claude (context and agents; rules go to .claude/rules/)
├── .cursor/rules/            # Generated for Cursor
├── GEMINI.md                 # Generated for Gemini
└── .github/copilot-instructions.md

Getting Help

  • CLI Help: ai-rulez --help, ai-rulez init --help, etc.
  • Validation: ai-rulez validate to check your configuration
  • Examples: Check the Examples section
  • Issues: Report problems on GitHub

Version

This documentation covers AI-Rulez V4 (TOML-based configuration with inline MCP servers and plugins).