Instruction Health Skills
Agent skills to keep AI assistant instruction files (AGENTS.md, CLAUDE.md, MEMORY.md) lean. Two complementary skills: a reactive 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. Designed to work with Claude, Cursor, Windsurf, Copilot, Codex, and other AI coding assistants that support the Agent Skills / AGENTS.md format.
Why These Skills Exist
I built these after my team's CLAUDE.md hit Claude Code's 40k-character warning — 519 lines that had grown organically over three months. The cost wasn't tokens: instruction-following degrades uniformly as the file grows, so a fat instruction file makes the agent worse at every rule in it, not just the ones it skips. Cleaning that up by hand got our always-loaded context down 73% (writeup). These two skills are the codified version of that routine — one to prevent the bloat, one to fix it once it's there.
The instruction file is a prompt budget, not documentation.
Philosophy
These skills focus on facts about context-budget hygiene, not opinions about what belongs in your instruction file.
Covered:
- Routing — every piece of content has exactly 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 silently disappears
Intentionally excluded:
- No team workflow opinions — no mandate on what goes in CLAUDE.md vs AGENTS.md vs team docs
- No naming conventions — no rules about skill names, doc paths, or file structure
- No prescriptive style — the litmus test ("would removing this cause mistakes?") drives every call
Structure
instruction-health-skills/
├── .claude-plugin/
│ ├── plugin.json # Claude Code plugin manifest
│ └── marketplace.json # Claude Code marketplace catalog
├── instruction-cleanup/
│ └── SKILL.md # Three-phase restructuring procedure
└── instruction-guardian/
└── SKILL.md # Six-step pre-write checklist
Coverage
| 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. Politely pushes back when content doesn't belong in an instruction file. |
instruction-cleanup | One-time fix — run when files have already 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 → implement procedure. Measures the full context-budget surface area, classifies every section, restructures with a needle-grep verification step. |
Cleanup fixes the past, guardian prevents the future.
How to Use These Skills
Option A: Using skills.sh (recommended)
Run a single 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.
For more information, visit the per-skill platform pages:
Then use the skill in your AI agent, for example:
Use the instruction-guardian skill to check whether this new section belongs in CLAUDE.md
Or, when files have already bloated:
Use the instruction-cleanup skill to audit this repo's instruction files and propose a restructuring plan
Option B: Claude Code Plugin
Personal Usage
Both skills are bundled into 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
