Instruction Health Skills

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
• Philosophy
• Features
• Installation
• Usage
• Project Structure
• Contributing
• License

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](https://ivanmagda.dev/posts/fixing-40k-claude-md-warning-monorepo/)). 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.
• Prescripti