instruction-health

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). 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:

• instruction-cleanup
• instruction-guardian

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