Rules Eval

Rules Evaluation Framework

Table of Contents

1. Overview 2. Quick Start 3. Evaluation Workflow 4. Scoring 5. Resources

Overview

This skill evaluates Claude Code rules in .claude/rules/ directories against quality standards. It validates YAML frontmatter, glob pattern syntax, content quality, and directory organization. Rules files support path-scoped conditional loading via paths frontmatter and unconditional rules (no paths field).

Key validations: YAML syntax errors, unquoted glob patterns, Cursor-specific fields (alwaysApply, globs), overly broad patterns, content verbosity, and naming conventions.

Quick Start

# Evaluate rules in current project
/rules-eval

# Evaluate specific directory
/rules-eval .claude/rules/

# Detailed analysis with recommendations
/rules-eval --detailed

Evaluation Workflow

1. Scan .claude/rules/ for all .md files (including subdirectories) 2. Validate YAML frontmatter syntax and fields 3. Analyze glob patterns for correctness and specificity 4. Assess content quality (actionable, concise, non-conflicting) 5. Check organization (naming, structure, symlinks) 6. Measure token efficiency and redundancy

Scoring

Resources

Skill-Specific Modules

• Frontmatter Validation: See modules/frontmatter-validation.md
• Glob Pattern Analysis: See modules/glob-pattern-analysis.md
• Content Quality Metrics: See modules/content-quality-metrics.md
• Organization Patterns: See modules/organization-patterns.md

Tools

• Rules Validator: scripts/rules_validator.py

Related Skills

• abstract:skills-eval - Skill evaluation framework
• abstract:hooks-eval - Hook evaluation framework

Content Quality Metrics

Quality Criteria

Actionability

Rules should provide clear, actionable guidance. Descriptions alone are insufficient.

<!-- BAD: Just a description -->
This project uses TypeScript.

<!-- GOOD: Actionable guidance -->
Use strict TypeScript. Enable `noImplicitAny` and `strictNullChecks`.
Prefer interfaces over type aliases for object shapes.

Conciseness

Each rule file should be focused and concise (< 500 tokens typical).

Non-Conflicting

Rules across files should not contradict each other.

Single Topic

Each rule file should address one focused topic.

Scoring (25 points, deductive)

Starts at 25, deducts for issues found:

Frontmatter Validation

Valid Frontmatter Fields

Claude Code rules support these frontmatter fields:

Rules without paths are unconditional (apply to all files).

Common Errors

YAML Syntax Errors

# INVALID - unquoted glob starting with *
---
paths:
  - **/*.ts        # YAML parse error
---

# VALID - quoted glob
---
paths:
  - "**/*.ts"
---

Wrong Field Names

# INVALID - Cursor-specific fields
---
globs:             # Wrong! Use 'paths'
  - "*.ts"
alwaysApply: true  # Wrong! Cursor-only, not Claude Code
---

Invalid Structure

# INVALID - paths must be a list
---
paths: "**/*.ts"   # Should be a list
---

# VALID
---
paths:
  - "**/*.ts"
---

Scoring (25 points, deductive)

Starts at 25, deducts for issues found:

Glob Pattern Analysis

Pattern Quality Assessment

Good Patterns

"src/api/**/*.ts"       # Specific scope
"tests/**/*.test.ts"    # Clear intent
"{src,lib}/**/*.ts"     # Multiple dirs, quoted
"*.config.{js,ts}"      # Config files only

Problem Patterns

"**/*"                  # Too broad - matches everything
"*"                     # Root only, usually too narrow
**/*.ts                 # Unquoted - YAML parse error
"."                     # Invalid glob

Validation Rules

1. Syntax validity: Pattern must be valid glob syntax 2. Quoting: Patterns with *, {, }, [, ] must be quoted 3. Specificity: Patterns should not match everything (**/*) 4. Intent clarity: Pattern should clearly indicate target files

Scoring (20 points, deductive)

Starts at 20, deducts for issues found. Files without paths receive full score.

Organization Patterns

Directory Structure

Recommended Layout

.claude/rules/
  api-validation.md       # Descriptive names
  testing-standards.md    # Topic-based naming
  frontend/               # Subdirectories for grouping
    react-patterns.md
    css-conventions.md

Anti-Patterns

.claude/rules/
  rules1.md              # Non-descriptive names
  misc.md                # Catch-all files
  RULES.md               # Shouting case
  my rules file.md       # Spaces in filenames

Naming Conventions

• Use kebab-case: api-validation.md
• Be descriptive: name should indicate rule content
• Use subdirectories for 5+ rule files
• Avoid generic names: rules.md, misc.md, todo.md

Symlink Support

Symlinks enable shared rules across projects:

ln -s ~/shared-rules/code-style.md .claude/rules/code-style.md

Validate that symlink targets exist and are readable.

Scoring (15 points)