| name | rule-review |
| description | Audit an existing agent-rules file (AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md, .github/instructions/*.md) across seven dimensions and emit a verdict per finding with concrete evidence. Goes beyond length / embedded code / language precision / redundancy / order (which 10x covers) by adding (6) cross-tool drift detection when multiple rules files exist for the same scope, and (7) dead-rule check that greps the codebase for the patterns each rule targets — if nothing matches, the rule may be obsolete. Cites the ai-devkit rule in ~/.claude/rules/ that already covers redundant content. Read-only by default; --fix applies safe rewrites (remove redundancy, split oversized rules, reorder by importance). Trigger phrases: "review AGENTS.md", "audit my CLAUDE.md", "check my rule file", "rule review", "is my AGENTS.md any good".
|
| argument-hint | <path-to-rules-file> [--fix] |
| allowed-tools | ["Read","Write","Edit","Bash","Grep","Glob","AskUserQuestion"] |
/rule-review — Audit a Rules File With Evidence
This skill reads an agent-rules file (any common format) and emits a structured audit across seven dimensions. Each finding cites concrete evidence: a line number, a file path, a ~/.claude/rules/ reference, a grep result, or a contradicting file. By default it's read-only — it diagnoses but doesn't change anything. With --fix, it applies safe rewrites.
Built on findings from Lulla et al. (well-used AGENTS.md → −28% time / −16% tokens) and Gloaguen et al. (redundant or LLM-generated rule files → +20–23% cost). The dimensions exist because each one is a documented failure mode in those evaluations.
When to use, when to skip
Use when:
- You just authored or edited
AGENTS.md / CLAUDE.md and want a sanity check before committing.
- You inherited a project and the rules file feels bloated or unanchored.
- The agent keeps ignoring or misapplying a rule — review checks whether the rule is even reachable.
- You suspect drift between multiple rules files (root vs nested, AGENTS.md vs CLAUDE.md, vs
.github/copilot-instructions.md).
Skip when:
- The file is the empty / one-line shim (e.g.
CLAUDE.md containing only @AGENTS.md). Review the canonical file it points to instead.
- You're authoring from scratch — use
/agents-md first; come back here for the audit after.
- The file is auto-generated by a tool that doesn't expect human review (e.g. CI-generated
AGENTS.md).
Relationship to other skills
/agents-md — upstream. Authors the file this skill audits. Steps 4–5 of /agents-md already apply the test-of-inclusion and size budget; this skill verifies the result against the broader dimension list.~/.claude/rules/*.md — read-only reference. Findings cite specific rules from this layer when flagging redundancy.docs/reference/lessons.md — read-only reference. Findings citing "no Why:" propose deriving the reason from a matching lessons entry.
Output language
The audit report and any --fix rewrites to the target file are written in English, regardless of the user's chat language. This matches the global policy in ~/.claude/CLAUDE.md §13. Interactive prompts during the audit may use the user's working language; the persisted findings and fixed file content are always English.
The seven dimensions
- Length — file size vs ~200-line guideline. Too long ⇒ U-shaped attention drops middle content; rule #47 on line 320 is rarely applied.
- Embedded code or config blocks — fenced
... blocks longer than ~10 lines, or full config snippets pasted in. These belong in referenced files, not rules.
- Language precision — vague verbs ("ensure", "consider", "try to"), intent-language without behavior ("write clean code"), abstract nouns ("good design"). Each should be rewritten as an observable, falsifiable rule.
- Redundancy with auto-active layer — content already in
~/.claude/rules/*.md (when ai-devkit's rules layer is installed) or in publicly trained model knowledge. Each redundant rule cites the source that already covers it.
- Order — important rules in the middle (low-attention zone). Critical rules should be at top; references at the bottom.
- Cross-tool drift (beyond 10x) — when more than one rules file exists for the same scope (
AGENTS.md + CLAUDE.md + .github/copilot-instructions.md + .cursor/rules/*.mdc), check that they don't contradict. Drift creates a coin-flip for the agent.
- Dead rules (beyond 10x) — for each rule that targets a code pattern (file naming, import style, framework idiom), grep the codebase. If nothing matches the pattern the rule enforces or forbids, the rule may be obsolete and should be flagged.
Initial Response
When invoked:
- Path given (
/rule-review AGENTS.md): jump to Step 1.
- No path: glob the repo for rule files. List candidates in order of likelihood:
Which file to audit?
- AGENTS.md (root, 187 lines)
- CLAUDE.md (root, 1 line, imports AGENTS.md)
- src/api/AGENTS.md (nested, 42 lines)
- .cursor/rules/api.mdc (Cursor)
- .github/copilot-instructions.md (Copilot)
Pass: /rule-review <path>
Then STOP.
Process
Step 0: Read and parse
Read the target file FULLY. Strip the YAML frontmatter (if any). Split into:
- Headings (
#, ##, ###) — used for the order check (Dimension 5).
- Bulleted lists — typical rule format.
- Numbered lists — typical procedural rule format.
- Paragraphs — usually intro / connective tissue.
- Fenced code blocks — flagged for Dimension 2.
Print summary: Parsed: <N> headings, <M> rules, <K> code blocks, total <L> lines.
Step 1: Dimension 1 — length
wc -l <file>
| Lines | Verdict | Note |
|---|
| ≤ 150 | OK | |
| 151–200 | WARN | At the recommended ceiling. Consider splitting area-specific content. |
| 201–300 | FAIL | Over guidance. Recommend split. List the largest sections. |
| > 300 | FAIL (critical) | Strongly over. Middle of file is in low-attention zone. |
Step 2: Dimension 2 — embedded code / config blocks
For each fenced code block, measure lines.
| Block size | Verdict | Action |
|---|
| 1–10 lines | OK if it's an inline example | Keep. |
| 11–25 lines | WARN | Extract to a referenced file, leave a pointer (> See: docs/reference/<file>). |
| > 25 lines | FAIL | Definitely extract. Inline blob is a context tax. |
Cite line ranges for each finding.
Step 3: Dimension 3 — language precision
Run regex / heuristic over each rule line:
| Pattern | Flag |
|---|
| `\b(consider | try to |
| `\b(clean | good |
| `\b(always | never |
| Sentence with no verb in present tense | Likely descriptive, not prescriptive — rewrite. |
For each flagged line, emit a finding with verdict: WARN and a one-line rewrite suggestion.
Step 4: Dimension 4 — redundancy with auto-active layer
If ~/.claude/rules/*.md exists, read each. Build a topic index (typescript.md → ["unknown over any", "Zod validation", ...]).
For each rule line in the target file, attempt match:
- Keyword overlap (case-insensitive substring match on 3+ tokens).
- Same enforcement (allow / deny patterns matching).
| Match | Verdict |
|---|
| Exact or near-exact ai-devkit coverage | FAIL — cite ~/.claude/rules/<file>.md line. Rule should be removed. |
| Partial overlap | WARN — cite, ask user to decide. |
| No match in auto-active layer, but it's a mainstream framework idiom (e.g. "use React hooks not class components") | WARN — model knowledge probably covers it; ask if it's local-specific. |
Local-specific (anchored in docs/, lessons.md, an incident) | OK. |
If ~/.claude/rules/ is missing, the redundancy check is skipped with a note: "ai-devkit rules layer not installed at ~/.claude/rules/ — Dimension 4 partial."
Step 5: Dimension 5 — order
U-shaped attention: top and bottom of long contexts are best attended; middle is weakest. If the file is > 100 lines, the critical rules should be in the top third.
Heuristic for "critical": rules tagged by the user with **critical**, **must**, (critical), or appearing under a ## Critical heading. If no explicit tagging, infer from content (e.g. access-control, destructive-operation gates, irreversible-action rules).
| Order | Verdict |
|---|
| Critical rules all in top third | OK |
| Critical rules in middle third | WARN — propose reorder. |
| Critical rules in bottom third or scattered | FAIL — propose reorder. Print suggested section sequence. |
Step 6: Dimension 6 — cross-tool drift (beyond 10x)
Check sibling files for the same scope:
ls AGENTS.md CLAUDE.md .github/copilot-instructions.md .cursor/rules/*.mdc 2>/dev/null
For each pair of files present:
| Pair | Allowed shape | Drift check |
|---|
AGENTS.md + CLAUDE.md (shim) | CLAUDE.md is one-line @AGENTS.md import OR symlink | If CLAUDE.md has its own rules → FLAG; either consolidate into AGENTS.md or split scopes explicitly. |
AGENTS.md + .github/copilot-instructions.md | Copilot shim points to / mirrors AGENTS.md | If Copilot file has rules diverging from AGENTS.md, list the differences. |
AGENTS.md + .cursor/rules/*.mdc | Cursor rules are area / glob-scoped, AGENTS.md is repo-wide | If Cursor rule restates a repo-wide AGENTS.md rule, flag redundancy. |
For each drift finding, print the conflicting lines side by side:
DRIFT — error response shape
AGENTS.md:42 "Errors return { error: { code, message, context } }."
copilot-instructions:18 "Errors return { error: string }."
Suggested fix: align both to AGENTS.md (the canonical one), or split scopes.
Step 7: Dimension 7 — dead rules (beyond 10x)
For each rule that targets a code pattern, attempt a grep:
| Rule pattern | Grep |
|---|
"Use absolute imports @/..." | grep -rEn "from ['\"]@/" --include='*.ts' --include='*.tsx' |
"All migrations live in db/migrations/" | test -d db/migrations && ls db/migrations |
"Use the formatDate() helper, not new Date().toISOString()" | grep -rEn "new Date\\(\\)\\.toISOString" --include='*.ts' (occurrences = signal that the rule is being violated, not that it's dead) |
| "Class components are prohibited" | grep -rEn "class \\w+ extends (React\\.)?Component" --include='*.tsx' (zero hits across a year-old repo ⇒ probably no longer relevant) |
| Grep result | Verdict |
|---|
| Pattern is referenced widely in code | OK (rule is alive) |
| Pattern is rare but present | OK |
| Pattern is absent from the entire codebase | WARN — possibly obsolete. Ask the user. |
| Pattern is forbidden + still present (rule is failing!) | FAIL — surface the violating files. |
Skip rules that are not pattern-grep-able (workflow rules, business decisions). Note them in the report as "not grep-checkable".
Step 8: Emit the report
Print a single audit report:
# Rule audit — <path>
Audited: <YYYY-MM-DD> Total lines: <N> Rules parsed: <M>
## Verdict summary
| Dimension | Verdict | Findings |
|---|---|---|
| 1. Length | OK / WARN / FAIL | … |
| 2. Embedded blocks | OK / WARN / FAIL | … |
| 3. Language precision | OK / WARN / FAIL | <N> lines flagged |
| 4. Redundancy | OK / WARN / FAIL | <N> redundant w/ ai-devkit |
| 5. Order | OK / WARN / FAIL | … |
| 6. Cross-tool drift | OK / WARN / FAIL | <N> divergences |
| 7. Dead rules | OK / WARN / FAIL | <N> patterns absent |
## Findings
<one entry per finding, with: dimension, line range, verdict, evidence, suggested rewrite>
If invoked with --fix, jump to Step 9. Otherwise, STOP after the report and offer:
Actions you can take:
- Re-author from scratch: /agents-md <scope>
- Apply safe auto-fixes only: /rule-review <file> --fix
- Edit manually and re-audit
Step 9: --fix mode (opt-in only)
Apply only safe rewrites — never destructive:
| Finding type | Auto-fixable? | Action |
|---|
Redundant with ~/.claude/rules/ (FAIL) | YES | Remove the rule, leave a <!-- removed: covered by ~/.claude/rules/<file>.md --> marker. |
| Oversized code block (FAIL) | NO | Print the extraction path that should be created; do not auto-extract. |
| Wrong order (critical in middle) | YES | Reorder sections: critical → conventions → workflow → references. |
| Vague verb (WARN) | NO | Print suggested rewrite; user applies. |
| Drift between files (FAIL) | NO | Print diff; user resolves. |
| Dead rule (WARN) | NO | Mark with <!-- candidate: obsolete, no codebase matches as of <date> -->. |
Backup the original to <path>.bak-YYYYMMDD-HHMMSS before applying changes. Print the diff after applying.
Re-emit the audit report against the fixed file. Verify dimensions improved before declaring done.
Edge cases
- File doesn't exist: print "No file at ." Offer to delegate to
/agents-md to author one.
- File is only the YAML frontmatter / empty body: trivial OK; nothing to audit.
- File is for an entirely different tool format (e.g. raw JSON config like
.cursor/rules/*.mdc with non-markdown body): apply only dimensions 1, 5, 6 (length, order, cross-tool). Skip the rest with a note.
- Multiple files passed (
/rule-review AGENTS.md CLAUDE.md): audit each in turn, then run Dimension 6 across all of them as a single pass.
~/.claude/rules/ is gigantic and dimension-4 matching is slow: tolerate; cache the topic index in memory for the session.
