▋
agent/rule/SKILL.md

name: rule description: >- Add a new high-level agent rule to the current user-level AGENTS/CLAUDE instructions cleanly — first resolving this machine's source-of-truth file, then integrating, condensing, or extracting oversized procedure into skills. The top-level counterpart to /r-rule and /dir-rule. Invoke manually as /rule .

rule

Manually-invoked skill. The user runs /rule <new rule in their words> to fold a new standing instruction into the high-level agent instructions, keeping that file tight rather than letting it sprawl.

When to use this

  • The user types /rule ... (or asks to "add a rule", "add to my agents.md / claude.md", "add a global instruction"). This is the trigger.
  • Do NOT use for project-local CLAUDE.md/AGENTS.md inside a specific repo — this skill targets only the user's top-level personal instructions. Use /r-rule for repo-wide rules and /dir-rule for nested directory rules.

Resolve the source of truth

Do not assume a fixed dotfiles path. First inspect the current user-level instruction entry points and resolve symlinks:

  • ~/.claude/CLAUDE.md
  • ~/AGENTS.md
  • ~/.codex/AGENTS.md

If they converge, edit the real target. If they do not converge, report the map and ask which file should be canonical instead of guessing. Never edit symlink copies or hand-sync between locations. On machines with dotfiles, the target may be ~/dotfiles/home/AGENTS.md; on work machines it may be ~/.claude/CLAUDE.md.

Workflow

  1. Resolve and read the whole file first. You must see every section to place the rule well and to spot redundancy. It's not large; read it fully.
  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 (core engineering principles high, tool/workflow defaults lower).
  3. Integrate, don't just paste. Rewrite the user's phrasing into the file's voice: imperative bullets, second person ("you"/"I" as already used), em-dash asides, concise. Match the surrounding style exactly.
  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 with a (see also [Section](#anchor)) 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:
    • Use the skill-maker skill to scaffold a new personal skill and respect its detected source root. If the skill is team- or repo-owned, keep its real source in the owning repo and point runtime symlinks there.
    • Move the procedural detail into that skill's SKILL.md.
    • Replace the section in AGENTS.md with a 1–2 line pointer: what it's for + "use the <name> skill". Mirror how Local LLM Preferences points at local-llm-curator.
    • Only extract when it's truly procedural/reusable. A short principle stays inline.
  6. Show the diff and explain. Report: where the rule landed, anything you condensed or merged, and any section you extracted into a skill (name it so it can be reviewed).
  7. Don't commit. Leave the change in the relevant source-of-truth working tree for the user to review and commit if that source is versioned.

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.
  • If the rule is really a fact about the user/his machine/an external resource rather than a behavioral instruction, consider whether it belongs in auto-memory instead, and say so.
  • Keep total edits surgical and reviewable; this file is read on every session, so churn has a cost — make the file better, not just longer.