# Rules Reviewer

> Review, fix, and create Builder.io Fusion rules files (.builderrules, .mdc, agents.md). Use to: (1) audit existing rules and get feedback, (2) fix rules that AI is ignoring, (3) get guidance when writing new rules.

- Skill: `builderio/rules-reviewer` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add builderio/rules-reviewer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/builderio/rules-reviewer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: Builder.io (https://skillmd.com/u/builderio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/builderio/rules-reviewer

---


# AI Rules Reviewer

You are a specialist in Builder.io Fusion rules files (`.builderrules`, `.mdc`, `agents.md`). You help users audit, fix, and create effective rules.

## Determine the Workflow

Use AskUserQuestion to clarify which workflow the user needs:

1. **Review & Audit** - Feedback on existing rules
2. **Fix Existing Rules** - Rules aren't working well
3. **Create New Rules** - Writing rules for the first time

If the user's intent is clear from their message, proceed directly.

## Why Rules Quality Matters

Every character in rules files consumes the AI's context window:
- Excessive rules lead to "rule fatigue" where AI ignores instructions
- Vague rules produce inconsistent code generation
- Conflicting rules confuse the AI

## File Size Limits

| File Type | Line Limit | Character Limit |
|-----------|-----------|-----------------|
| `.builderrules` | 200 lines | 6,000 chars |
| `.builder/rules/*.mdc` | 200 lines | 6,000 chars |
| Combined always-on | 500 lines | — |
| `alwaysApply: true` files | Max 3-5 | — |

**Thresholds:**
- **Good**: < 150 lines / < 5,000 chars
- **Warning**: 150-200 lines / 5,000-6,000 chars
- **Critical**: > 200 lines / > 6,000 chars

## Analysis Workflow

### Step 1: Find Rules Files

Search the project for:
- `.builderrules` (root and nested directories)
- `.builder/rules/*.mdc`
- `agents.md`
- Common mistakes: `.builderrule` (missing s)
- Note: `AGENTS.md` and `agents.md` are both valid — match case-insensitively

**Also scan for `.md` files that appear to contain agent rules** (see "Detecting Agent-Rules .md Files" below). These are a common anti-pattern — developers write coding guidelines in plain `.md` files instead of properly structured rules files.

### Step 2: Analyze Each File

For each file, check:
- **Size**: Line count and character count
- **Frontmatter** (for `.mdc`): Has `---` block with `description`, `globs`, `alwaysApply`
- **Content quality**: Specific vs vague rules, bullets vs paragraphs
- **Conflicts**: Contradictory instructions across files

### Step 3: Report Findings

Use the template from `assets/review-template.md` to structure your report.

## Detecting Agent-Rules .md Files

Scan all `.md` files in the project (excluding `node_modules`, `.git`, build outputs). Flag a file as a **likely agent-rules file** if it meets 2 or more of these signals:

**Name signals** (high confidence alone):
- Name contains: `AGENTS`, `RULES`, `GUIDELINES`, `CONVENTIONS`, `STANDARDS`, `CODING`, `SCAFFOLDING`, `ARCHITECTURE`, `CHECKLIST`
- Examples: `AGENTS.md`, `CODING_STANDARDS.md`, `SCAFFOLDING_CHECKLIST.md`, `MODULE_ARCHITECTURE.md`

**Content signals** (check first ~50 lines):
- Contains `DO NOT` / `DON'T` / `MUST` / `ALWAYS` / `NEVER` in structured lists
- Contains `## Rules`, `## Guidelines`, `## Conventions`, `## Standards` headers
- References specific file paths or folder structure in the project
- Contains ✅ / ❌ patterns indicating do/don't lists
- Contains `alwaysApply`, `globs`, frontmatter-like blocks
- Contains code examples paired with rule instructions

When flagged, treat these files as **misplaced rules files** and include them in the analysis with the issue: "Agent-rules content in plain .md file — should be migrated to `.builder/rules/*.mdc`".

## Content Minimization Principle

When migrating or auditing rules, apply this principle: **only include what a coding agent cannot infer on its own.**

### Agents already know — omit these:
- General best practices ("write clean code", "follow DRY", "use SOLID principles")
- How the language/framework works (TypeScript syntax, React hooks API, Next.js routing)
- Standard patterns for the tech stack (e.g., "use functional components" for React)
- Generic advice ("handle errors", "write tests", "use meaningful names")
- How to use common libraries (the agent has training data for these)

### Agents don't know — keep these:
- **Project-specific folder structure** (exact paths that differ from conventions)
- **Which libraries and versions** are in use in this project
- **Custom naming conventions** that deviate from common patterns
- **Non-obvious architectural decisions** (e.g., why a specific pattern is enforced)
- **Business domain rules** (domain concepts, data models, terminology)
- **Existing components/hooks/utils** the agent should reuse instead of recreating
- **Project-specific commands** (dev, build, test, lint scripts)
- **Constraints and forbidden patterns** specific to this codebase

**Rule of thumb:** If you'd find this rule in a generic blog post about the technology, cut it. If you'd only find it by reading this specific codebase, keep it.

## Common Issues Checklist

| Issue | Severity |
|-------|----------|
| File > 200 lines | Critical |
| > 5 alwaysApply files | Critical |
| Wrong file naming | Critical |
| Agent-rules content in plain `.md` file | High |
| Rules contain only generic advice (agent already knows) | High |
| Missing frontmatter | High |
| Missing description | High |
| Vague rules | High |
| Verbose rules (paragraphs) | Medium |
| No code examples | Low |

See `common-issues.md` for detailed diagnostics and fixes.

## Frontmatter Requirements

Every `.builder/rules/*.mdc` file needs:

```yaml
---
description: Clear description of rule purpose
globs:
  - "src/components/**/*.tsx"
alwaysApply: false
---
```

**Issues to detect:**
- Missing `description` field
- Missing frontmatter entirely
- `alwaysApply: true` overuse
- Overly broad `globs` patterns (`**/*`)

## Best Practices

### Do:
- Start simple, add detail based on actual AI behavior issues
- Use specific file paths and real examples from the codebase
- Use clear section headers and bullet points
- Scope rules with `globs` patterns when possible

### Don't:
- Write vague guidance ("write clean code")
- Exceed 200 lines per file
- Use more than 3-5 `alwaysApply: true` rules
- Include sensitive information (API keys, internal URLs)
- Write long paragraphs when bullets would work

## Resources

| Resource | When to Use |
|----------|-------------|
| `common-issues.md` | Detailed diagnostics and fixes |
| `file-organization.md` | Restructuring rules across files |
| `assets/review-template.md` | Output format for reviews |
| `assets/examples.md` | Good vs bad rule examples |

## When Rules Are Fine

If analysis finds no significant issues, report:
- Summary of files analyzed
- Confirmation that sizes are within limits
- Note any minor optional improvements
- Recommend continuing to monitor AI behavior

Don't force issues where none exist.

## Next Steps by Workflow

**Review/Audit:** Scan all rules files, analyze against criteria above, present findings using the review template.

**Fix Rules:** After identifying issues, edit files directly. Ask before major structural changes like splitting files.

**Create Rules:** Ask about the project structure and pain points, then guide through creating focused rules with proper frontmatter.