Eval RulesCAUTION

The most comprehensive Claude Code guide: agentic workflows, hooks, skills, MCP servers, quizzes, and production-ready templates. 430K+ lines.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: eval-rules
description: "Audit Claude Code instruction rules in .claude/rules/ and ~/.claude/rules/: frontmatter, paths glob validity against real files, symlink load status, and day-to-day usefulness, then update rules with the user. Use for first-time rules setup, rules that apply too often or never, or periodic rules hygiene. Not for Codex .rules command-approval files."
allowed-tools: Read Glob Bash Edit
effort: medium
argument-hint: "[path to rules dir, default: .claude/rules/]"
---

# Rules evaluator

Discover every Claude Code rule file, validate its structure and `paths` globs against the real project, then review each rule with the user so the rules directory ends in better shape than it started.

This skill covers Claude Code instruction rules in `.claude/rules/` and `~/.claude/rules/`. It does not cover Codex `.rules` files, which are Starlark command-approval policies, not instructions. See "Codex" below.

## When to use

- Writing `.claude/rules/` files for the first time
- A rule never seems to apply, or applies to everything
- Moving `@` imports from CLAUDE.md into path-scoped rules
- Periodic hygiene: are these rules still accurate and useful?
- After onboarding to a new codebase

## Modes

| Request | Run |
|---|---|
| Default | Steps 1-5, with the interactive review |
| `audit-only`, or the user asks for no changes | Steps 1-3 and 5: list each proposed change instead of asking or editing, and omit the user-answer rows from the report |

When a `ctxharness doctor --format json` report generated during this task is available, every rules-layer finding it reports must appear in the audit. The doctor checks structure only; dead patterns, breadth and content are this skill's job.

## Key concepts

| Mechanism | When it loads |
|---|---|
| `@file` import in CLAUDE.md | Session start |
| Project rule without `paths` | Session start, same priority as `.claude/CLAUDE.md` |
| Project rule with `paths` | When Claude reads a file matching a pattern, not on every tool use |
| User rule in `~/.claude/rules/` | Applies to every project; loaded before project rules. Whether `paths` scoping applies to user rules is not documented: report it as unverified instead of assuming |

- All `.md` files under `.claude/rules/` are discovered recursively.
- `paths` is the only frontmatter field Claude Code reads from a rule; other fields are ignored without an error. It accepts a YAML list or a comma-separated string. Fields from other tools' rule formats, such as Cursor's `globs`, `alwaysApply` or `description`, are therefore ignored too: a rule scoped with `globs:` silently loads always-on.
- If the frontmatter YAML does not parse, Claude Code ignores the frontmatter and loads the rule as if it had no `paths`, so a broken scoped rule silently becomes always-on.
- Brace expansion works (`"src/**/*.{ts,tsx}"`). A rule's whole `paths` list shares a budget of 1,000 expanded patterns and 4 MiB; a pattern over budget is used unexpanded and its literal braces match nothing.
- A `[` that cannot be read as a bracket expression (for example `photos [2024/**`) makes that pattern invalid: it matches nothing, the other patterns still work. Escape a literal bracket as `\[`.
- Project rules are skipped when `project` is excluded from `--setting-sources`.
- User rules load before project rules; neither overrides the other, so a conflict between them is a defect to resolve.

### Symlinked rules

- A symlink whose target is inside the working directory loads normally.
- A symlink whose target is outside the working directory is treated like an external import: it does not load until external imports are approved for the project, and after approval only the linked rules without `paths` load.
- A symlink to a network path (UNC share, `/net`, `/Network`) never loads. `\\wsl$` paths are not network paths.
- Circular symlinks are detected and handled.
- The memory documentation says the approval prompt appears only for `@path` imports, but the v2.1.284 changelog reads: "Fixed rules symlinked into `.claude/rules` from outside the project being skipped without ever showing the external-imports approval prompt". From v2.1.284, an external symlinked rule asks for the same approval; on older versions it is skipped silently. Check the running version before reporting the load status.

To share rules across projects without approval, put them in `~/.claude/rules/`.

## Scoring Criteria (12 pts per scoped rule)

| # | Criterion | Max | What is checked |
|---|---|---|---|
| 1 | **frontmatter parses** | 1 | Frontmatter, when present, is valid YAML (a broken block turns the rule always-on) |
| 2 | **paths field** | 2 | Present (1) + at least one non-empty pattern, as a list or comma-separated string (1) |
| 3 | **pattern validity** | 3 | Every pattern is checked. Score 3 times the share of patterns that match at least one file and are neither invalid nor over the expansion budget, rounded down |
| 4 | **scope** | 2 | Not dead: the union of all patterns matches at least one file (1) + not too broad: that union covers under 30% of the project files counted in Step 1 (1) |
| 5 | **content quality** | 3 | Clear title (1) + specific, actionable rules (1) + under 150 lines (1) |
| Bonus | **focus** | +1 | Under 15 rules in the file |

**Always-on rules** (no `paths`): score criteria 1 and 5 only (4 pts, plus bonus), mark them `always-on`, and decide in the interactive step whether they should be scoped.

**User rules** (`~/.claude/rules/`): their patterns resolve against whichever project is open, so criteria 3 and 4 are `N/A` in a user-level audit. Score them only when auditing a named project.

**Symlinked rules**: add a load-status note (`loads`, `needs external-import approval`, `loads only after approval and only if unscoped`, `never loads: network path`). A rule that cannot load gets status `Fix` regardless of score.

**Thresholds:** Good >= 83%, Needs work 58-82%, Fix < 58%.

## Execution instructions

### Step 1: Dis

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

whitepapers/recap-cards/en/_extensions

whitepapers/recap-cards/fr/_extensions

Gates applied: no_behavioural_pass.