▋
agent/r-rule/SKILL.md

name: r-rule description: >- Add a new rule to the current repo's agent instructions (CLAUDE.md / AGENTS.md) cleanly — integrating it into the right section, condensing/pruning for succinctness, and extracting oversized sections into their own skills. The repo-level counterpart to /rule and /dir-rule. Invoke manually as /r-rule .

r-rule

Manually-invoked skill. The user runs /r-rule <new rule in their words> to fold a new standing instruction into this repo's agent instructions, keeping that file tight rather than letting it sprawl. This is the repo-scoped twin of /rule (which targets the user's global instructions) and the broader counterpart to /dir-rule (which targets nested directory instructions).

When to use this

  • The user types /r-rule ... (or asks to "add a repo rule", "add to this repo's claude.md / agents.md", "add a project-local instruction"). This is the trigger.
  • Do NOT use for the user's top-level personal instructions — that's /rule, which resolves this machine's global instructions file itself. If the user clearly means the global file, use /rule.
  • Do NOT use for subtree-only guidance that belongs in a nested CLAUDE.md / AGENTS.md; use /dir-rule.

The target — the repo's own agent instructions

These instructions belong to the repo, not the user's global dotfiles. CLAUDE.md or AGENTS.md may symlink to the other: resolve it and edit the repo-owned target without replacing the symlink. Locate the target:

  1. Resolve the repo root (git rev-parse --show-toplevel).
  2. Pick the agent-instructions file at the repo root, in this preference order:
    • CLAUDE.md if it exists (this is the file Claude Code loads for the project).
    • else AGENTS.md.
    • If both exist, prefer the one that already holds the kind of rule being added; if unclear, default to CLAUDE.md and mention the other so the user can redirect.
    • If neither exists, create CLAUDE.md at the repo root with a sensible top heading (e.g. # Development Rules) and the rule as its first entry; say you created it.
  3. If the rule is clearly scoped to a subtree or nested instruction file, stop and use /dir-rule instead.

Workflow

  1. Read the whole target file first. You must see every section to place the rule well and to spot redundancy. Read it fully, not just the section you expect to touch.
  2. Decide placement. Find the section the new rule belongs in:
    • If it sharpens or extends an existing bullet/section → merge it there, don't append a near-duplicate. Rewrite the existing bullet to cover both rather than stacking two.
    • If it's a genuinely new theme → add a new ## Section in a sensible spot, matching how this file is already organized.
  3. Integrate, don't just paste. Rewrite the user's phrasing into the file's voice: match its existing heading style, bullet vs prose, person, and terminology exactly. Concise and imperative.
  4. Condense while you're there. This is the whole point of the skill — leave the file tighter than you found it:
    • Collapse overlapping/redundant bullets across the file (not just the edited section).
    • Cut filler; prefer one sharp sentence over three soft ones.
    • Cross-link related sections instead of repeating.
    • Don't delete a rule's actual substance to save words — condense expression, preserve meaning.
  5. Extract oversized sections into skills. If a section has grown into a procedure (multi-step how-to, long command sequences, lots of conditional detail) rather than a standing principle, it doesn't belong in always-loaded context. Extract it:
    • Prefer a repo-local skill if the repo already keeps skills in-tree (e.g. .claude/skills/ or a bundled skills/ dir — match the repo's own convention); otherwise use the skill-maker skill to scaffold one per the user's symlink convention.
    • Move the procedural detail into that skill's SKILL.md.
    • Replace the section in the instructions file with a 1–2 line pointer: what it's for + "use the <name> skill".
    • Only extract when it's truly procedural/reusable. A short principle stays inline.
  6. Show the diff and explain. Report: which file you edited (repo-root vs nested), where the rule landed, anything you condensed or merged, and any section you extracted into a skill.
  7. Don't commit. Leave it in the working tree for the user to review and commit. Respect the repo's own rules while editing (many repos say "do not commit unless asked").

Judgement notes

  • Bias toward merging over adding. A new top-level section per rule is how the file bloats.
  • If the new rule contradicts an existing one, don't silently keep both — flag the conflict and propose the resolution rather than leaving the file self-contradictory.
  • The repo's instructions are shared with everyone working in it, not just the user — keep the edit in the repo's established voice and scope, not the user's personal phrasing.
  • Keep total edits surgical and reviewable; this file is read on every session in the repo, so churn has a cost — make the file better, not just longer.