Instruction Health Skills
Agent skills that keep AI assistant instruction files (AGENTS.md, CLAUDE.md, MEMORY.md) lean.
Two skills work together: a guardian that runs before an instruction file is edited to prevent bloat, and a three-phase cleanup for files that have already grown too large. They work with Claude, Cursor, Windsurf, Copilot, Codex, and other AI coding assistants that support the Agent Skills / AGENTS.md format.
Table of Contents
Background
My team's CLAUDE.md hit Claude Code's 40k-character warning at 519 lines, grown over three months. The cost wasn't token count. Instruction-following degrades as the file grows, so a bloated instruction file makes the agent worse at every rule it holds, not only the ones it skips. I cleaned ours up by hand and cut always-loaded context by 73% (writeup). These two skills codify that routine: one prevents the bloat, one fixes it once it lands.
Treat the instruction file as a prompt budget. Spend it on rules the agent needs in front of it every turn.
Philosophy
These skills handle context-budget hygiene as a set of facts, leaving opinions about what belongs in your instruction file to you.
Covered:
- Routing: every piece of content has one correct destination (instruction file, skill, rule, doc, memory, or delete).
- Context budget: measuring, condensing, and preventing re-bloat of always-loaded context.
- Compaction survival: which content survives
/compact and which disappears.
Intentionally excluded:
- Team workflow opinions. No mandate on what goes in CLAUDE.md vs AGENTS.md vs team docs.
- Naming conventions. No rules about skill names, doc paths, or file structure.
- Prescriptive style. The litmus test ("would removing this cause mistakes?") drives every call.
Features
| Skill | When to use it | What it does |
|---|
instruction-guardian | Day-to-day gate. Runs before every edit to CLAUDE.md / AGENTS.md / MEMORY.md / .claude/rules/, keeping files from re-bloating. | Runs a six-step checklist: line budget, dedup check, litmus test, destination routing, format rules, @-import prevention. Pushes back when content doesn't belong in an instruction file. |
instruction-cleanup | One-time fix. Run when files have grown past ~200 lines or ~40k chars and agent performance has degraded. Produces a written plan you approve before anything is rewritten. | Three-phase audit, plan, and implement procedure. Measures the full context-budget surface area, classifies every section, and restructures with a needle-grep verification step. |
Cleanup fixes the past, guardian prevents the future.
Installation
Option A: skills.sh (recommended)
Run one command and pick both skills in the wizard (space to toggle, enter to confirm):
npx skills add https://github.com/ivan-magda/instruction-health-skills
Or install both non-interactively in one shot:
npx skills add https://github.com/ivan-magda/instruction-health-skills --skill instruction-cleanup instruction-guardian
For an unattended setup that also picks every agent, use --all.
Per-skill platform pages:
Option B: Claude Code plugin
Both skills ship in a single plugin: one marketplace add, one install, and you get both.
Add the marketplace:
/plugin marketplace add ivan-magda/instruction-health-skills
Install the plugin:
/plugin install instruction-health@instruction-health-skills
