instruction-cleanup

Restructures bloated instruction files in bulk to shrink always-loaded context and restore agent performance. Use when CLAUDE.md, AGENTS.md, Cursor rules, or other instruction files have grown too large (200+ lines, 40k+ chars), when agent performance has degraded due to bloated context, or when the user asks to audit, restructure, slim down, or clean up their instruction files. For a single small edit to an instruction file, use instruction-guardian instead.

1.31x

Quality

88%

Does it follow best practices?

Impact

100%

1.31x

Average score across 1 eval scenario

Securityby

Critical

Do not install without reviewing

Quality

Content

77%Weight 40%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable multi-phase workflow with strong validation checkpoints. Its main weaknesses are token efficiency (motivational/repeated prose) and a monolithic layout that, for a skill over 50 lines teaching extraction-to-reference-files, does not itself practice progressive disclosure.

Suggestions

Trim the 'Why This Matters' motivational prose (e.g. the 'Research shows instruction-following degrades uniformly' sentence) and deduplicate the compaction-survival explanation to raise conciseness.

Move the large dot routing flowchart and/or the detailed table templates into a reference file under references/, replacing them with a one-level-deep pointer from the body to improve progressive_disclosure.

The skill teaches extracting content to separate docs and skills; apply that principle to itself by splitting the Phase 3 flag/carve-out mechanics into a reference so the overview stays lean.

Dimension	Reasoning	Score
Conciseness	Mostly efficient procedural content (tables, templates, shell snippets), but it carries motivational prose that does not earn its tokens — e.g. "Instruction files are a prompt budget, not documentation... Research shows instruction-following degrades uniformly" — and repeats the compaction explanation. Not the level above, which would have every token earning its place; not the level below, which would be padded with concepts Claude already knows.	2 / 3
Actionability	Provides copy-paste-ready, executable guidance: a Context Budget Report table template, the Destination Guide, the Restructuring Plan table, and concrete shell commands (the cksum-keyed flag touch/rm) plus verification grep commands. Not the level below, which would rely on pseudocode or omit key details.	3 / 3
Workflow Clarity	Clear three-phase sequence (Audit -> Plan -> Implement) with explicit checkpoints ("Present this report to the user before proceeding", "get approval before implementing") and a feedback loop (unreachable terms -> fix before committing). Matches the anchor for explicit validation steps and error-recovery loops, not the level below where checkpoints are missing or implicit.	3 / 3
Progressive Disclosure	Well-organized into sections with no nested references, but it is a single monolithic ~263-line body with no external bundle files and content that could stand alone (the large dot flowchart, detailed table templates) kept inline rather than split out. Not the level above, which would split appropriately with one-level-deep references; not the level below, which would be a poorly-organized wall with 2+ level nesting.	2 / 3
	Total	10 / 12 Passed

Description

100%Weight 40%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it names concrete actions, gives multiple natural trigger phrases with quantified thresholds, answers both what and when, and explicitly carves out a neighboring skill to avoid conflict. No changes needed.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Restructures bloated instruction files in bulk to shrink always-loaded context and restore agent performance" — naming the domain and the concrete verbs (restructure, shrink, restore) rather than vague language. Not the level below, which would only name a domain without specific actions.	3 / 3
Completeness	Explicitly answers both what (restructure bloated instruction files to shrink context/restore performance) and when ("Use when...grown too large", "when agent performance has degraded", "when the user asks to audit, restructure, slim down, or clean up"). Not the level below, where "when" is missing or only implied.	3 / 3
Trigger Term Quality	Covers natural user phrasing — "CLAUDE.md, AGENTS.md, Cursor rules", "audit, restructure, slim down, or clean up", plus concrete thresholds ("200+ lines, 40k+ chars"). Not the level below, which would have only some relevant keywords missing common variations.	3 / 3
Distinctiveness Conflict Risk	Clear niche (bulk instruction-file cleanup) with explicit disambiguation — "For a single small edit to an instruction file, use instruction-guardian instead" — making conflict with adjacent skills unlikely. Not the level below, which could still overlap with similar skills.	3 / 3
	Total	12 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: ivan-magda/instruction-health-skills
Path: instruction-cleanup/SKILL.md
Commit: 2837bdc

Reviewed: 14 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.