Skip to content

Update readme #70

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonandersen merged 2 commits into from
Jan 27, 2026
Merged

Update readme #70

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
682fa28
Update readme
jonandersen Jan 23, 2026
2fad90b
Address PR review feedback on Quick Start section
jonandersen Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
506 changes: 46 additions & 460 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

26 changes: 26 additions & 0 deletions docs/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# Supported AI Coding Agents

## Agent Compatibility Table

| Agent | Standard Mode | Symlink Mode | MCP Support | Notes |
|-------|---------------|--------------|-------------|-------|
| **AMP** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Claude Code** | `CLAUDE.md` (+ `.claude/skills/` if configured) | `CLAUDE.md` -> `ai-rules/AGENTS.md` | `.mcp.json` | Skills support via `use_claude_skills` config |
| **Cline** | `.clinerules/*.md` | `.clinerules/AGENTS.md` -> `../ai-rules/AGENTS.md` | - | |
| **Codex** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Copilot** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Cursor** | `.cursor/rules/*.mdc` | `AGENTS.md` -> `ai-rules/AGENTS.md` | `.cursor/mcp.json` | Symlink mode: only project root level |
| **Firebender** | `firebender.json` | `firebender.json` (references `ai-rules/AGENTS.md`) | Embedded in `firebender.json` | Supports overlay files |
| **Gemini** | `GEMINI.md` | `GEMINI.md` -> `ai-rules/AGENTS.md` | Embedded in `.gemini/settings.json` | |
| **Goose** | `AGENTS.md` | `AGENTS.md` -> `ai-rules/AGENTS.md` | - | |
| **Kilocode** | `.kilocode/rules/*.md` | `.kilocode/rules/AGENTS.md` -> `../../ai-rules/AGENTS.md` | - | |
| **Roo** | `.roo/rules/*.md` | `.roo/rules/AGENTS.md` -> `../../ai-rules/AGENTS.md` | `.roo/mcp.json` | |

## Firebender Overlay Support

Firebender supports overlay configuration files. To customize your configuration:

1. Create `ai-rules/firebender-overlay.json` in the same parent directory as your generated `firebender.json`
2. Any values defined in the overlay file will be merged into the base configuration, with overlay values taking precedence

**MCP Integration:** If you have `ai-rules/mcp.json`, the MCP servers are merged into `firebender.json` first, then the overlay is applied. This allows you to override MCP configurations in the overlay if needed.
114 changes: 114 additions & 0 deletions docs/commands-and-skills.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Commands and Skills

## Custom Commands

Custom commands (also called "slash commands") allow you to define reusable prompts that can be invoked by name in supported AI agents.

### Setup

Create markdown files in `ai-rules/commands/`:

```
ai-rules/
└── commands/
└── commit.md
```

### Frontmatter Fields

Command files support optional YAML frontmatter:

| Field | Description | Agent Support |
|-------|-------------|---------------|
| `allowed-tools` | Tool restrictions for the command | Claude only |
| `description` | Human-readable description of what the command does | All |
| `model` | Specific model to use for this command | Claude only |

### Agent Behavior

| Agent | Output Location | Frontmatter |
|-------|-----------------|-------------|
| **AMP** | `.agents/commands/{name}-ai-rules.md` | Stripped |
| **Claude Code** | `.claude/commands/ai-rules/*.md` | Preserved |
| **Cursor** | `.cursor/commands/ai-rules/*.md` | Stripped |
| **Firebender** | `firebender.json` (commands array) | Stripped |

### Documentation

- [Claude Code Slash Commands](https://code.claude.com/docs/en/slash-commands)
- [Cursor Commands](https://cursor.com/docs/agent/chat/commands)
- [Firebender Commands](https://docs.firebender.com/context/commands)

---

## Claude Code Skills

Claude Code supports optional rules through [skills](https://docs.claude.com/en/docs/claude-code/skills). This requires `use_claude_skills: true` in your config.

When enabled and a source rule has `alwaysApply: false`, the tool generates:
- **CLAUDE.md** - References required rules (`alwaysApply: true`) only
- **.claude/skills/{rule-name}/SKILL.md** - Individual skill files for optional rules

### Example

Source file `ai-rules/testing.md`:

```markdown
---
description: React Testing Library best practices
alwaysApply: false
---
# Testing Rules
- Prefer user-centric queries (getByRole, getByLabelText)
- Avoid implementation details (testId, class names)
- Test behavior, not implementation
```

Generates:
- `CLAUDE.md` - Contains only required rules
- `.claude/skills/testing/SKILL.md` - Skill that Claude can invoke when working with test files

Skills use the `description` field as the skill name for better discoverability.

---

## User-Defined Skills

You can define custom skill folders that are symlinked to supported agents' skill directories during generation.

### Setup

Create skill folders in `ai-rules/skills/<skill-name>/` with a `SKILL.md` file:

```
ai-rules/
└── skills/
└── debugging/
└── SKILL.md
```

### SKILL.md Format

```markdown
---
name: debugging
description: Debugging guidelines and best practices
---

# Debugging Guidelines

Your skill content here...
```

### Generated Symlinks

When you run `ai-rules generate`, symlinks are created:

| Agent | Symlink Location |
|-------|------------------|
| AMP | `.agents/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` |
| Claude | `.claude/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` |
| Codex | `.codex/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` |
| Cursor | `.cursor/skills/ai-rules-generated-debugging` -> `../../ai-rules/skills/debugging` |

Skill folders without a `SKILL.md` file are skipped with a warning.
34 changes: 34 additions & 0 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Configuration

You can set default values for commonly used options in a configuration file. This is especially useful in team environments or when you have consistent preferences across projects.

## Configuration File

Create `ai-rules/ai-rules-config.yaml` in the `ai-rules` directory:

```yaml
agents: [claude, cursor, cline] # Generate rules only for these agents
command_agents: [claude, amp] # Generate commands for these agents (defaults to agents list if not specified)
nested_depth: 2 # Search 2 levels deep for ai-rules/ folders
gitignore: true # Ignore the generated rules in git
```

## Configuration Precedence

Options are resolved in the following order (highest to lowest priority):

1. **CLI options** - `--agents`, `--nested-depth`, `--no-gitignore`
2. **Config file** - `ai-rules/ai-rules-config.yaml` (at current working directory)
3. **Default values** - All agents, depth 0, generated files are NOT git ignored

## Experimental Options

### Claude Code Skills Mode

```yaml
use_claude_skills: true # Default: false
```

Experimental toggle to test Claude Code's skills feature. When enabled, rules with `alwaysApply: false` are generated as separate skills in `.claude/skills/` instead of being included in `CLAUDE.md`. This allows Claude Code to selectively apply optional rules based on context.

See [Commands and Skills](commands-and-skills.md) for more details on skills.
41 changes: 41 additions & 0 deletions docs/mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# MCP Configuration

The AI Rules Tool supports generating Model Context Protocol (MCP) configurations for compatible AI coding agents. MCP enables AI agents to connect to external tools and services.

## Setup

Create `ai-rules/mcp.json` with your MCP server configurations:

```json
{
"mcpServers": {
"server-name": {
"command": "executable-command",
"args": ["arg1", "arg2"],
"env": {
"ENV_VAR": "${use_environment_variable}"
}
},
"remote-server-name": {
"type": "http",
"url": "https://api.example.com/mcp"
}
}
}
```

## Generation

Run `ai-rules generate` to automatically create agent-specific MCP configurations.

## Supported Agents

See the [Supported Agents](agents.md) table for which agents support MCP and their generated file locations:

| Agent | MCP File Location |
|-------|-------------------|
| Claude Code | `.mcp.json` |
| Cursor | `.cursor/mcp.json` |
| Firebender | Embedded in `firebender.json` |
| Gemini | Embedded in `.gemini/settings.json` |
| Roo | `.roo/mcp.json` |
78 changes: 78 additions & 0 deletions docs/project-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
# Project Structure Examples

## Standard Mode

For projects using YAML frontmatter in rule files:

```
monorepo/
├── ai-rules/ # Global rule files
│ ├── .generated-ai-rules/ # Processed files (generated)
│ ├── commands/ # Custom commands
│ │ └── commit.md
│ ├── skills/ # User-defined skills
│ │ └── debugging/
│ │ └── SKILL.md
│ ├── general.md # Repository-wide rules
│ ├── ai-rules-config.yaml # Configuration
│ └── mcp.json # MCP server configuration
│
├── frontend/ # Frontend application
│ ├── ai-rules/ # Frontend-specific rules
│ │ ├── .generated-ai-rules/
│ │ ├── react.md
│ │ └── styling.md
│ ├── CLAUDE.md # Generated
│ ├── AGENTS.md # Generated
│ ├── .cursor/rules/ # Generated (*.mdc)
│ └── src/
│
├── backend/ # Backend services
│ ├── ai-rules/
│ │ ├── .generated-ai-rules/
│ │ ├── api.md
│ │ └── database.md
│ ├── CLAUDE.md
│ ├── AGENTS.md
│ └── api/
│
├── CLAUDE.md # Root rules (generated)
├── AGENTS.md # Root rules (generated)
├── .cursor/rules/ # Root Cursor rules (generated)
├── .clinerules/ # Root Cline rules (generated)
├── .mcp.json # Root MCP config (generated)
└── firebender.json # Root Firebender config (generated)
```

## Symlink Mode

For simple projects with a single `AGENTS.md` file:

```
project/
├── ai-rules/
│ ├── AGENTS.md # Source file (your rules)
│ ├── commands/ # Custom commands (optional)
│ │ └── commit.md
│ ├── skills/ # User-defined skills (optional)
│ │ └── debugging/
│ │ └── SKILL.md
│ └── mcp.json # MCP config (optional)
│
├── CLAUDE.md # Symlink -> ai-rules/AGENTS.md
├── GEMINI.md # Symlink -> ai-rules/AGENTS.md
├── AGENTS.md # Symlink -> ai-rules/AGENTS.md
├── firebender.json # References ai-rules/AGENTS.md
├── .clinerules/
│ └── AGENTS.md # Symlink -> ../ai-rules/AGENTS.md
├── .cursor/
│ ├── commands/ai-rules/ # Commands (generated)
│ └── mcp.json # MCP config (if mcp.json exists)
├── .kilocode/rules/
│ └── AGENTS.md # Symlink -> ../../ai-rules/AGENTS.md
├── .roo/
│ ├── rules/
│ │ └── AGENTS.md # Symlink -> ../../ai-rules/AGENTS.md
│ └── mcp.json # MCP config (if mcp.json exists)
└── .mcp.json # Claude MCP config (if mcp.json exists)
```
60 changes: 60 additions & 0 deletions docs/rule-format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Source Rule File Format

Rule files are markdown files (`.md`) stored in your `ai-rules/` directory. There are two modes of operation: Standard Mode and Symlink Mode.

## Standard Mode

Use Standard Mode when you want fine-grained control over rules with YAML frontmatter.

### Format

```markdown
---
description: Context description for when to apply this rule
alwaysApply: true/false
fileMatching: "**/*.ext"
---

# Rule Content

Your markdown content here...
```

### Frontmatter Fields

All fields are optional:

| Field | Description | Default |
|-------|-------------|---------|
| `description` | Context description that helps agents understand when to apply this rule if `alwaysApply` is `false` | - |
| `alwaysApply` | `true` = referenced directly in agent rule files; `false` = included as optional rules based on context | `true` |
| `fileMatching` | Glob patterns for which files this rule applies to (e.g., `"**/*.ts"`, `"src/**/*.py"`). Currently supported in Cursor. | - |

If frontmatter is omitted entirely, the file is treated as a regular markdown rule with default settings (`alwaysApply: true`).

## Symlink Mode

Use Symlink Mode for simple setups where all agents share the same rules.

### Requirements

- Must be named `AGENTS.md`
- Must be the only file in the `ai-rules/` directory (commands/ and skills/ subdirectories are allowed)
- Must not start with `---` (no YAML frontmatter)

### Format

```markdown
# Project Rules

- Use TypeScript for all new code
- Write comprehensive tests
- Follow conventional commits
- Prefer explicit types over `any`
```

### How It Works

In Symlink Mode, `ai-rules generate` creates symlinks pointing to `ai-rules/AGENTS.md` for supported agents instead of generating separate files. This keeps all your rules in one place.

See [Supported Agents](agents.md) for details on which agents support symlink mode.